Notes de Décision

Que fait Notes de Décision ?

Distinguer clairement entre le rejet par l'utilisateur, les tentatives échouées, les options non retenues après comparaison, les éléments différés et ceux hors périmètre. Ne pas tous les traiter comme définitivement irréalisables.

Les notes ne sont pas destinées aux propositions non résolues, aux exigences complètes, aux étapes de mise en œuvre, à l'avancement des tâches ou aux journaux de dépannage. Conserver les propositions et les plans de mise en œuvre dans les documents de conception et de planification ; maintenir le comportement actuel dans la documentation du sous-système propriétaire et le vérifier par rapport au code source. Conserver la justification à long terme dans les notes ; la résumer et y faire référence ailleurs.

1. Recherche avant les Décisions et les Modifications

Avant d'entamer le travail suivant, consulter les contraintes applicables au niveau du projet, la documentation pertinente du sous-système et les notes associées :

• Proposer une solution concrète, arrêter un comportement ou effectuer un compromis de conception clé.
• Modifier l'implémentation associée ou les tests de comportement ; pour un travail intersous-système, couvrir les interfaces concernées et les contraintes partagées.
• Créer ou modifier un enregistrement de décision ; rechercher d'abord les conclusions existantes sur le même sujet.

Lorsque l'utilisateur s'interroge sur l'historique, qu'un pointeur de décision est trouvé ou qu'un conflit apparaît, lire directement l'enregistrement concerné. Les corrections orthographiques, de mise en forme et de statut ne nécessitent pas une nouvelle recherche lorsqu'elles n'impliquent pas de contraintes établies.

Localiser et évaluer les enregistrements dans cet ordre :

1. Utiliser le point d'entrée de l'Agent du projet pour trouver l'emplacement réel des notes et les contraintes globales applicables. Utiliser la documentation du sous-système pour localiser les responsabilités, contrats, code source, tests et notes associées. Un sous-système peut s'étendre sur des packages ou des dépôts, et une note peut concerner plusieurs sous-systèmes.
2. Suivre les liens, puis rechercher par question, mécanisme, nom de solution et contrainte si nécessaire. L'absence d'un lien, de code correspondant ou d'un nom concordant ne prouve pas l'absence d'historique pertinent. Si aucune page de sous-système n'existe, localiser le contexte pertinent à partir des documents disponibles et du sujet de la tâche ; ne pas créer de document vide à l'avance.
3. Commencer par le titre, le Statut, la Portée et la conclusion ; lire la justification, les alternatives et les preuves lorsque c'est pertinent. Privilégier les enregistrements actuellement en vigueur, puis retracer l'historique par ordre de pertinence. Rechercher directement dans les enregistrements archivés lorsqu'on reconsidère une ancienne option ou que les directives actuelles sont insuffisantes. Suivre la supersession en fonction de la portée concernée ; ne pas suivre une chaîne arbitraire jusqu'à son terme.
4. Confirmer l'applicabilité de l'enregistrement et les faits actuels. Si le répertoire n'existe vraiment pas, continuer ; ne le créer que lorsqu'un enregistrement est nécessaire pour la première fois. Un échec de lecture ou une recherche sans résultat ne prouve pas l'absence d'historique.

Au sein d'une même tâche, réutiliser les résultats déjà vérifiés et toujours applicables. Revérifier les parties affectées lorsque la portée, une prémisse clé ou un enregistrement associé change, ou lorsqu'un conflit apparaît. Ne pas tout renumériser simplement parce que le tour ou la compétence a changé.

Soulever de manière proactive une ancienne option uniquement si ses prémisses ont clairement changé, en expliquant pourquoi elle n'a pas été choisie auparavant, quelles conditions ont changé et l'impact. Si l'utilisateur annule explicitement une décision antérieure, suivre la nouvelle instruction sans demander une nouvelle approbation. Une autorisation générale de mise en œuvre n'annule pas automatiquement un rejet ou une restriction de portée existant.

2. Décider s'il Faut Créer un Enregistrement

Un nouvel enregistrement doit satisfaire à toutes ces conditions :

1. La conclusion est arrêtée. Elle a été adoptée, rejetée, différée ou limitée en portée, ou il y a un résultat d'échec et des conditions qui méritent d'être conservées à long terme. Les propositions non résolues et les hypothèses en attente de vérification appartiennent aux documents de conception et aux plans.
2. Elle a une valeur durable. Sans la justification, un futur Agent pourrait soulever à nouveau une ancienne option, répéter une tentative infructueuse significative ou modifier accidentellement une contrainte importante. Le simple fait de reformuler le comportement actuel n'atteint pas ce seuil.
3. Elle nécessite un enregistrement séparé. L'historique associé a été recherché et les informations ne peuvent pas être capturées en mettant à jour des faits, en ajoutant des preuves ou en clarifiant la portée. Un changement réel de décision nécessite un nouvel enregistrement selon les règles de supersession. Ne pas créer d'enregistrements mécaniquement par date, nombre de livraisons ou nombre d'alternatives.

Les sujets typiques incluent les limites de sous-système non évidentes, les interfaces ou les choix de persistance et de compatibilité ; les sélections importantes et les raisons de ne pas choisir d'alternatives ; les raisons d'éviter délibérément la mise en cache ou les nouvelles tentatives automatiques ; les rejets ou reports significatifs qui pourraient être soulevés à nouveau ; et les conclusions d'échec à long terme étayées par des preuves ou les politiques inter-tâches.

Généralement, ne pas créer de notes pour la mise en forme, les renommages mécaniques, les implémentations ou correctifs ordinaires compréhensibles à partir du code et des tests, les mises à jour de dépendances de routine, les tentatives de dépannage général, les journaux, les TODO ou l'avancement. La taille n'est pas un critère. Maintenir une note existante si le travail la rend inexacte, et enregistrer une nouvelle décision si le travail en produit une qui répond au seuil.

S'il n'y a pas de valeur à long terme distincte à préserver, ne pas créer d'enregistrement simplement pour remplir un modèle. Si l'utilisateur demande explicitement de préserver une décision importante, réutiliser ou créer une source appropriée ; ne pas la supprimer silencieusement.

3. Enregistrer les Conclusions Réelles Rapidement

Enregistrer une conclusion importante rapidement dès qu'elle est claire ; ne pas attendre l'achèvement, la fin d'une session ou l'approbation d'un commit. Une décision peut provenir de l'utilisateur ou d'un Agent effectuant un choix dans le cadre de l'autorité déléguée. L'enregistrement n'ajoute pas d'étape d'approbation, et un compromis encore en attente de la décision de l'utilisateur ne peut pas être réglé en écrivant une note.

Avant d'écrire, lire Format et Exemples. L'emplacement par défaut est .agents/notes/YYYY-MM-DD-sujet.md dans le projet cible ; préférer un emplacement de projet existant. Conserver un sujet de décision par fichier et un chemin stable. Ne pas organiser les notes dans des répertoires par statut ou sous-système.

• Conserver un titre, un Statut et une Portée. Centrer le corps sur la conclusion, la justification et les compromis ; ajouter d'autres sections si nécessaire. Le texte du corps est par défaut en anglais, sauf si le projet a une langue cohérente. Ne pas inventer d'alternatives, exiger un nombre fixe ou forcer des étiquettes de conséquences positives/négatives.
• Énoncer la portée et les conditions de chaque conclusion. Ne pas décrire un objectif adopté mais non mis en œuvre comme un fait d'implémentation, de migration ou de déploiement actuel. Les documents de conception et de planification sont propriétaires de l'avancement de la mise en œuvre.
• Si la justification est manquante, dire qu'elle n'a pas été fournie ou enregistrée. Pour un échec, conserver ses conditions, son résultat et les preuves nécessaires ou les lacunes de preuves ; ne pas en déduire une infaisabilité permanente. Ne pas se fier uniquement au chat ou à une sortie temporaire qu'une session ultérieure ne pourra pas consulter.

4. Mettre à Jour, Remplacer et Organiser

Statut	Signification
active	Explicitement adopté et toujours applicable dans sa portée déclarée ; les rejets et reports valides utilisent également ce statut
superseded	La portée entière a été remplacée par une ou plusieurs nouvelles décisions
retired	Rien n'est plus en vigueur, et aucune nouvelle décision ne le reprend entièrement

Le statut n'indique pas l'avancement de la mise en œuvre ou le sort d'une solution candidate. Si les faits, les noms, les chemins ou les preuves changent mais que la décision ne change pas, mettre à jour l'enregistrement existant. Créer un nouvel enregistrement lorsqu'un choix fondamental ou une contrainte change clairement. Réévaluer lorsque des preuves deviennent invalides ; ne pas modifier la décision automatiquement.

Avant de changer le statut, de remplacer une décision, de gérer un remplacement partiel ou de restaurer une ancienne option, lire Statut et Supersession. Établir des liens croisés entre les anciens et les nouveaux enregistrements par portée ; conserver les contraintes restantes après un remplacement partiel. Si une ancienne option est adoptée à nouveau, créer un nouvel enregistrement plutôt que d'effacer les décisions intermédiaires.

Avant d'archiver, de fusionner ou de supprimer, lire Rétention et Organisation. Conserver les enregistrements par défaut. L'archivage logique ne déplace pas les chemins ; la fusion ne doit pas effacer de véritables changements de décision ; avant la suppression, migrer les informations uniques et mettre à jour les références. Organiser uniquement les enregistrements affectés par la tâche en cours ; un nettoyage complet doit être dans le périmètre.

5. Vérifier avant la Livraison

Vérifier les enregistrements et la portée associée pertinents pour ce travail. Même si aucune nouvelle note n'a été créée, vérifier si les modifications ont rendu une note existante inexacte.

1. Omissions et doublons : Les conclusions importantes et la justification à long terme ont-elles été sauvegardées ? Sont-elles uniquement dans la conversation ? Un enregistrement existant est-il déjà suffisant ?
2. Vérité et preuves : Ne pas présenter une recommandation comme une décision, un objectif comme un état actuel, un échec comme un rejet permanent, une option non choisie comme interdite, ou un report comme un engagement de mise en œuvre. Énoncer avec précision les informations inconnues, non fournies et non vérifiées.
3. Statut et portée : La portée et les conditions sont-elles exactes ? Le remplacement partiel conserve-t-il les obligations restantes ? Existe-t-il des conclusions en vigueur contradictoires pour la même portée et les mêmes conditions ? L'archivage cache-t-il une contrainte actuelle ?
4. Propriété des documents : Mettre à jour la documentation du sous-système affectée, les conceptions, les plans et les notes ; chaque source est propriétaire de ses informations, et les autres emplacements y renvoient.
5. Liens et chaîne de supersession : Les sources nécessaires sont-elles localisables ? Les conclusions peuvent-elles être retracées par portée sans auto-liens, liens brisés ou cycles ? L'organisation a-t-elle préservé la justification unique, les preuves et les références historiques significatives ?
6. Vérification : Exécuter les vérifications pertinentes déjà disponibles dans le projet et examiner leurs résultats. Si aucune n'est configurée, vérifier manuellement. Ne pas ajouter automatiquement des dépendances, des scripts, de l'IC ou des migrations de format. Corriger les problèmes réels trouvés ; ne pas fabriquer de contenu. Réutiliser les résultats réussis lorsque le contenu pertinent n'a pas changé.

Le passage d'une vérification de format ne prouve pas que la justification est correcte, que la récupération est complète ou que la mise en œuvre suit la décision. Si les faits actuels contredisent un enregistrement, faire la distinction entre les dispositions transitoires, la documentation obsolète, la mise en œuvre incomplète et le conflit réel. Corriger les erreurs vérifiées. Si un jugement clé reste flou, expliquer le conflit et demander une décision ; ne pas passer outre une nouvelle instruction de l'utilisateur ni prétendre à l'achèvement. Continuer le travail qui ne dépend pas de la réponse.

Lors de l'ajout, de la mise à jour substantielle, du remplacement ou de l'organisation de notes, expliquer brièvement ce qui a changé, pourquoi et les éventuelles lacunes, avec des liens. Ne pas émettre un message fixe "aucune note ajoutée" lorsque rien de pertinent n'a changé.

Garder le code, la documentation associée et les notes ensemble comme un seul livrable en attente. Après avoir terminé les modifications et vérifications de cette série et montré les résultats, demander si le travail est terminé et si un commit local peut être créé. Si l'utilisateur donne plus de commentaires, continuer à éditer. La sauvegarde ou la validation des notes n'autorise pas un commit, un push ou une publication, et n'exige pas de commiter les notes prématurément.