ejklock/living-docs-skill

Living Docs

Traitez la documentation comme un système vivant qui reste synchronisé avec le code, et non comme un artefact écrit une fois qui se dégrade. La discipline a une colonne vertébrale — chaque élément de connaissance a exactement un domicile, ce domicile est indexé, et rien de structurel n'est livré sans sa documentation — et plusieurs types de documents qui en dépendent : une constitution, des ADRs, des BDRs, des PRDs, des tickets, de la recherche, des diagrammes d'architecture et un index de contexte sémantique.

Cette compétence est indépendante de la pile. Elle gouverne comment les docs sont organisés et maintenus, jamais quelle technologie un projet utilise.

---

Invariants fondamentaux (la colonne vertébrale)

Ils s'appliquent à tous les types de documents. Tout le reste n'est que détail.

1. Docs d'abord. Rédigez le corps dans le dépôt (docs/…) avant de publier ailleurs (traqueur, wiki). Le fichier du dépôt est la source de vérité ; la copie externe est un miroir.
2. Un seul domicile par fait. Chaque concept, décision ou exigence vit dans exactement un fichier. Pas de duplication — croisez les références plutôt que de copier. Un texte dupliqué est une dérive qui n'attend qu'à se produire.
3. Indexé ou ça n'existe pas. Chaque doc est accessible depuis un index (un index.md listant dans son répertoire, et l'index racine du bundle docs/index.md que le guide de projet référence). Pas de fichiers orphelins.
4. Remplacez, ne réécrivez jamais l'historique. Les décisions et les exigences sont des enregistrements à ajouts uniquement. Quand quelque chose change, marquez l'ancien enregistrement comme remplacé et écrivez-en un nouveau — ne modifiez jamais silencieusement le passé.
5. Pas de changement structurel sans sa documentation. Nouveau module, fichiers déplacés, changement de schéma, nouveau flux de données → mettez à jour le doc concerné et son diagramme dans le même changement. Pas de « Je le documenterai plus tard. »

En cas de doute, déduisez la bonne action à partir de ces cinq règles. Les fichiers de règles ci-dessous ne sont que ces invariants appliqués à chaque type de document.

---

Format : conforme OKF

Les cinq invariants gouvernent l'organisation et le cycle de vie ; le format Open Knowledge gouverne le format de fichier pour que le corpus reste portable et analysable par un agent. Chaque doc du système est aussi un concept OKF. Chargez la compétence okf-knowledge-format (elle fournit la spécification) lors de la rédaction ou de la vérification du format.

OKF est une dépendance légère et interchangeable — pas un fondement (risque de version). OKF est en v0.1 d'un seul fournisseur ; une v0.2 non rétrocompatible est une possibilité réelle. Les invariants ci-dessus ne dépendent pas d'OKF — ils ne dépendent que d'un petit ensemble de champs de frontmatter, de sorte qu'une rupture d'OKF ne peut pas emporter la couche de gouvernance avec elle. Gardez la limite explicite :

• Requis par Living Docs (le contrat de fait appliqué par scripts/lint-docs.sh) : un type non vide, et status + superseded_by sur les enregistrements remplacés. Ce sont les nôtres ; ils survivent indépendamment d'OKF.
• Hérité d'OKF (conventions de format) : index.md/log.md réservés, okf_version à la racine du bundle, liens relatifs au bundle, l'en-tête # Références (§8). Si OKF change, seule cette ligne bouge — ré-épinglez la version dans la compétence okf-knowledge-format et ajustez.

Deux règles s'appliquent à chaque fichier de concept :

1. Frontmatter avec un type requis. Chaque doc .md non réservé s'ouvre par un bloc frontmatter YAML dont le type nomme le type de doc (Constitution, PRD, ADR, BDR, Issue, Context, Architecture View, Research, Reference). Recommandé : title, description, tags, timestamp. Living-docs ajoute des clés de producteur : status, supersedes, superseded_by. Le statut passe dans le frontmatter — pas de ligne **Statut :** dans le corps.
2. Fichiers réservés + liens relatifs au bundle. La racine du bundle est docs/. Les listes de répertoire sont index.md (OKF §6, pas de frontmatter — sauf pour docs/index.md à la racine du bundle, qui porte okf_version: "0.1"). log.md facultatif enregistre l'historique du répertoire (§7). Liez avec des chemins relatifs au bundle préfixés par / (/adr/0007-slug.md) ; listez les sources sous un en-tête # Références (§8), chaque entrée formatée selon rules/citation-conventions.md — structure ABNT NBR 6023, toujours avec le lien, avec des étiquettes de connexion dans la langue du document du projet (anglais par défaut : Available at: <URL>. Accessed on: <date>) selon rules/doc-language.md.

---

Chaîne documentaire

Chaque changement suit cette chaîne, de la source de vérité fondamentale jusqu'au code :

flowchart LR
  C[constitution] --> P[PRD]
  P --> A[ADR]
  P --> B[BDR]
  A --> I[tickets]
  B --> I
  I --> K[code]

Artefact	Rôle
constitution	Source de vérité fondamentale : ce qu'est le produit, modèle de données de base, non-négociables. Tous les autres docs en dépendent.
PRD	Ce que le système doit faire et pourquoi — spécification d'exigences produit/fonctionnalité.
ADR	Comment le système est structuré — décision architecturale/d'implémentation et justification.
BDR	Ce que le système doit observablement faire — entrées, sorties, effets secondaires, scénarios Given/When/Then — et comment chacun est testé (la matrice de conception de test ; domicile unique pour « comment tester », un ticket d'exécution y fait référence).
tickets	Tranches d'exécution — unités de travail discrètes qui remontent aux ADRs/BDRs.
code	Implémentation — chaque comportement, structure et interface spécifiés ci-dessus, réalisés.

---

Quand invoquer

• Mise en place de la documentation pour un projet (création de la structure docs/, de l'index des docs, des répertoires ADR/ticket/BDR/constitution).
• Première exécution de living-docs dans un projet (pas de bloc ## Living Docs dans le guide de projet) → poser la question du mode d'application et persister la réponse → voir Modes d'application.
• Adoption de living-docs dans un projet existant/brownfield (décisions déjà prises mais non documentées) → suivre Procédure → Adoption de living docs dans un projet existant : inventorier les décisions, confirmer chacune avec l'utilisateur avant d'enregistrer un ADR, ne jamais rétro-remplir par simple inférence.
• Rédaction ou édition d'un ADR (une décision architecturale/d'implémentation) → charger rules/adr-conventions.md + templates/adr.md.
• Rédaction ou édition d'un PRD (une spécification d'exigences produit/fonctionnalité) → charger rules/prd-conventions.md + templates/prd.md.
• Rédaction ou édition d'un BDR (comportement observable — entrées, sorties, scénarios Given/When/Then, et la matrice de conception de test pour comment chacun est testé) → charger rules/bdr-conventions.md + templates/bdr.md. Une décision de stratégie de test (niveau non défaut, technique, déviation de barre) est un ADR avec tags: [testing], pas un nouveau type d'enregistrement (pas de « TDR »).
• Spécification d'une exigence non fonctionnelle (performance, disponibilité, sécurité, passage à l'échelle) → un scénario d'attribut de qualité lié à un instrument dans le PRD (rules/prd-conventions.md règle 9 + templates/prd.md) ; la décision + la fonction d'adéquation vont dans un ADR. Pas un nouveau type de doc.
• Établissement ou modification de la constitution (périmètre fondamental, modèle de données, non-négociables) → charger rules/constitution-conventions.md + templates/constitution.md.
• Création ou édition d'un ticket → charger rules/issue-workflow.md + templates/issue.md.
• Enregistrement de recherche (évaluation technologique, compromis externes) → charger la compétence research-artifacts. Elle possède le format de note de recherche OKF (un seul fichier par note, pas de sous-dossier par recherche), la discipline de source et la chaîne traçable recherche → décision → ticket, et fait le lien ici pour les artefacts ADR/BDR/ticket. Se couple avec la compétence deep-research.
• Dessin ou mise à jour d'un diagramme d'architecture, de flux de données ou d'appel d'outils → charger rules/architecture-diagrams.md + templates/architecture-index.md.
• Définition d'un terme ou acronyme utilisé par les docs → l'ajouter au glossaire (docs/context/glossary.md), un seul domicile par terme → charger rules/glossary-conventions.md + templates/glossary.md.
• Un doc est devenu trop volumineux ou mélange les préoccupations → scinder en un index sémantique → charger rules/semantic-index.md + templates/context-index.md.
• Application de la règle de maintenance sans dérive après tout changement structurel → charger rules/maintenance-invariant.md.
• Rédaction ou vérification du format OKF de tout doc (frontmatter type, index.md/log.md réservés, liens relatifs au bundle, # Références) → charger la compétence okf-knowledge-format.
• Décision de la langue dans laquelle les docs sont rédigés (anglais par défaut ; l'utilisateur peut la modifier en début de session et l'épingler) → charger rules/doc-language.md.

---

Carte des documents

Type	Emplacement	Objectif	Mutabilité
Guide de projet	CLAUDE.md / README.md (racine)	Point d'entrée : périmètre, pile, index des docs, flux de travail obligatoires	Vivant — modifiable librement
Constitution	docs/constitution.md	Source de vérité fondamentale : périmètre du produit, modèle de données, non-négociables	Ajouts uniquement une fois ratifiée (journal d'amendement)
Index de contexte	docs/context/index.md + fichiers de groupe	Vocabulaire du domaine et du module, regroupé sémantiquement	Vivant — modifiable librement
Glossaire	docs/context/glossary.md	Termes et acronymes définis une fois, dans la langue du document (vedettes d'acronymes telles quelles)	Vivant — modifiable librement
Architecture	docs/architecture.md ou docs/architecture/ + index	Diagrammes Mermaid vivants : structure, modèle de données, flux, appels d'outils	Vivant — doit correspondre au code
ADR	docs/adr/NNNN-slug.md	Une décision architecturale/d'implémentation	Ajouts uniquement (remplacement)
BDR	docs/bdr/NNNN-slug.md	Une décision de comportement observable	Ajouts uniquement (remplacement ou amendement)
PRD	docs/prd/NNNN-slug.md	Une spécification d'exigences produit/fonctionnalité	Ajouts uniquement une fois acceptée
Ticket	docs/issues/NNNN-slug.md	Miroir du traqueur (corps), un par ticket	Corps modifiable ; copie publiée suit
Recherche	docs/research/NNNN-<slug>.md (un seul fichier, pas de sous-dossier ; numéro séquentiel en tête, date dans le frontmatter timestamp ; se termine par # Références)	Preuve externe avec affirmations sourcées	Ajouts uniquement (les preuves sont datées)

Chaque répertoire porte son propre index.md listant (OKF §6, pas de frontmatter). La section « Index des docs » du guide de projet renvoie au docs/index.md racine du bundle. Voir rules/semantic-index.md pour le contrat d'indexation.

---

Procédure

Mise en place de living docs dans un nouveau projet

1. Posez la question du mode d'application (voir Modes d'application → Question du premier lancement) avant toute autre chose, car aucune préférence n'est encore persistée. Enregistrez la réponse comme le bloc ## Living Docs dans le guide de projet ; par défaut à strict si l'utilisateur n'a pas de préférence.
2. Créez le guide de projet (CLAUDE.md ou équivalent) avec une section Index des docs et une section Règle de maintenance (copiez le libellé de rules/maintenance-invariant.md). Utilisez templates/claude-hard-rules.md comme point de départ pour la section des règles strictes du guide de projet — elle contient déjà le bloc d'application ## Living Docs ; remplissez les espaces réservés avant de valider.
3. Créez docs/ avec les répertoires dont le projet a besoin (adr/, bdr/, issues/, prd/, research/, context/). Initialisez docs/constitution.md à partir de templates/constitution.md. Ajoutez le docs/index.md racine du bundle (portant okf_version: "0.1"), et donnez à chaque répertoire son propre index.md listant dès le premier jour — même s'il est presque vide.
4. Initialisez l'index de contexte (docs/context/index.md) avec le vocabulaire du domaine existant, et le glossaire (docs/context/glossary.md) avec les termes et acronymes que les docs supposent déjà (rules/glossary-conventions.md). Développez les deux à mesure que les concepts sont nommés.
5. Initialisez le doc d'architecture (docs/architecture.md) avec les vues Mermaid de haut niveau que le système possède déjà. Passez à un répertoire docs/architecture/ + index une fois qu'il grandit (rules/architecture-diagrams.md).
6. Enregistrez les décisions déjà prises comme ADRs pour qu'elles ne soient pas remises en cause — mais confirmez chacune avec l'utilisateur avant d'enregistrer (voir Adoption de living docs dans un projet existant, étapes 3–5) ; ne rétro-remplissez jamais un ADR par simple inférence.

Adoption de living docs dans un projet existant (brownfield)

Une base de code existante incarne déjà des décisions qui n'ont jamais été écrites. Le mode d'échec ici est que l'agent rétro-remplisse des ADRs par inférence et les présente comme acquis — enregistrant des décisions que l'utilisateur n'a jamais été invité à confirmer. L'adoption est donc un exercice d'élicitation, pas de transcription.

1. Posez la question du mode d'application (premier lancement) et persistez le bloc ## Living Docs, exactement comme pour un nouveau projet.
2. Échafaudez sans décider. Créez docs/ + l'index.md de chaque répertoire, le docs/index.md racine du bundle, et initialisez le glossaire/l'index de contexte à partir du vocabulaire déjà présent dans le code, le README, et les guides d'agent (CLAUDE.md / AGENTS.md). C'est mécanique — aucune décision n'est prise ici.
3. Lisez d'abord le contexte existant, puis inventorier les décisions — comme candidats, pas comme enregistrements. Récoltez ce que le projet porte déjà : le code lui-même, plus le README, les guides d'agent (CLAUDE.md / AGENTS.md), les manifests de paquets, et toutes notes de conception ou commentaires. À partir de cela, produisez une liste des décisions porteuses que le projet semble incarner (pile, limites, modèle de données, compromis clés). N'écrivez pas d'ADRs encore.
4. Présentez l'inventaire à l'utilisateur et confirmez chaque élément. Pour chaque candidat, énoncez la décision inférée et les alternatives qu'elle semble avoir écartées, et demandez à l'utilisateur de confirmer, corriger ou rejeter — questionnez les décisions porteuses (grill-me si installé). L'utilisateur possède la décision ; l'agent ne fait que mettre en surface ce que le code implique.
5. Enregistrez uniquement les décisions confirmées comme ADRs. Ce sont des enregistrements d'origine — ils ne remplacent rien. Capturez l'option choisie et les alternatives rejetées que l'utilisateur a confirmées. Un candidat que l'utilisateur rejette, ou dont personne ne connaît réellement la justification, n'est pas inventé en ADR.
6. Initialisez le doc d'architecture avec les vues Mermaid de haut niveau que le système possède déjà (rules/architecture-diagrams.md), puis reprenez la boucle de Maintenance ci-dessous.

Maintenance de living docs (chaque tâche)

1. Avant de coder : lisez le mode d'application ## Living Docs depuis le guide de projet (si le bloc est absent, c'est le premier lancement — posez la question du premier lancement et persistez la réponse). Ensuite, lisez la constitution, les ADRs, les BDRs et l'index de contexte pertinents. Les diagrammes d'architecture et le glossaire au besoin.