Une décision n'est enregistrée
que si quelqu'un peut dire qu'elle tient encore.
Le dossier est plein. Vingt ADR, neuf spécifications, dont quatre remplacées par une décision consignée ailleurs, et au moins une qui décrit un service supprimé l’an dernier. Rien dans le dossier ne dit lesquelles.
Alors les vraies questions d’un nouvel ingénieur — est-ce approuvé, est-ce construit, est-ce encore vrai — se posent dans le chat, reçoivent une réponse de mémoire, et une réponse différente selon qui est connecté. Les documents ont été écrits précisément pour que cela cesse.
La solution habituelle est un champ de statut dans le front matter, un champ que quelqu’un doit penser à modifier. Il est exact le jour où il est écrit et décoratif au bout d’un mois, car rien ne le relie au document qu’il surmonte.
Un statut qui ne remarque pas que le document a changé sous lui est pire que pas de statut du tout : c’est une affirmation périmée qui porte un badge.
Les parties qui comptent ici
Pas toute la liste des fonctionnalités — celles dont dépend ce problème précis.
Deux axes, pas un seul
L’état de relecture et l’état d’implémentation évoluent indépendamment, car une spécification approuvée par tous et construite par personne n’est pas dans la même situation qu’une spécification à moitié construite et contestée. Les réunir en un seul statut efface la distinction qui compte le plus.
La dérive se mesure sur le contenu
Un statut retient la version exacte sur laquelle il a été fixé. Modifiez le document et il indique validé · dérivé, au lieu de garder un badge qui a cessé d’être vrai sans bruit. Un horodatage se déclencherait chaque fois qu’un worker touche une ligne.
Aucune ligne tant que personne ne décide
Un document non trié n’a pas de statut et n’affiche aucune étiquette. Un dossier que personne n’a relu apparaît tel qu’il est, au lieu d’un mur de brouillons suggérant un processus qui n’a jamais eu lieu.
Rejeté est un vrai état
« Ne pas construire ceci » est une décision qui mérite d’être consignée, et elle exige un motif — écrit sous forme de note dans la même transaction que le statut, pour que le refus et son argument ne puissent pas être séparés.
Les objections vivent sur le titre
Une note est ancrée à la section qu’elle conteste. Si ce titre disparaît, la note échoue visiblement au lieu de se déplacer sur un texte qui dit autre chose.
Le tableau à l’échelle d’un projet
Chaque document doté d’un statut, dans des colonnes entre lesquelles vous pouvez glisser, filtré par une URL que vous pouvez coller dans un canal avant une revue de conception.
Ce qui se passe réellement
- 01Un ADR est fusionné et apparaît, sans statutIl est dans l’arborescence dès que la branch est lue. Personne ne l’a trié, donc il ne porte aucune étiquette — la représentation honnête d’un document que personne n’a encore regardé.
- 02Un relecteur le lit et conteste une sectionIl laisse une note sur ce titre plutôt qu’un commentaire sur une pull request fermée. La note est attachée au texte : elle sera encore là dans six mois quand quelqu’un demandera pourquoi cela a été fait.
- 03L’auteur révise et le relecteur valideL’état de relecture passe à validé, pour cette version exacte du texte. L’état d’implémentation reste où il est, car approuver n’est pas construire.
- 04Un agent lit la spécification et se met au travailIl trouve le document par la recherche, le lit et signale qu’il a commencé — avec des preuves enregistrées sous forme de note. Il consigne une affirmation, jamais un achèvement.
- 05Quelqu’un modifie la spécification trois semaines plus tardLe badge devient validé · dérivé dès que le contenu change. Personne n’a besoin de le remarquer ; le document le dit lui-même, et l’agent peut demander le diff entre la version validée et le texte actuel.
- 06Une personne boucle la boucle, ou nonUn agent peut dire qu’un retour est traité. Seule une personne peut le clore. Cette asymétrie est toute la raison d’être de cette couche, et elle est appliquée dans une seule fonction, avec un test.
Ce que cela ne résout pas
Chaque page de ce site en porte une, pour la même raison : une page de cas d'usage sans limite est une brochure.
- Il n’écrira pas l’ADR
- C’est un outil de lecture. Vous écrivez dans votre éditeur et faites un commit, exactement comme aujourd’hui — il n’y a pas d’interface de rédaction et il n’y en aura pas.
- Il ne modélise pas les remplacements
- « ADR-014 remplace ADR-009 » est une relation entre documents, et nous ne la suivons pas. Un lien et un état rejeté sont ce qui s’en approche le plus.
- Une coquille déclenche la dérive
- L’identité du contenu est tout le mécanisme : corriger une virgule marque un document validé comme dérivé. C’est accepté délibérément : l’autre option est une règle qui devine quelles modifications comptent.