gener8v/gener8v.claude-skills.engineering

Synchronisation de la documentation

Le code et ses documents changent ensemble, dans le même commit. Un document erroné est pire qu'aucun document.

Trois façons dont les documents deviennent erronés

• Obsolète. Le document décrit toujours l'ancien comportement, nom ou commande.
• Manquant. Un nouveau comportement, une nouvelle commande ou un nouveau paramètre n'a pas de documentation.
• Dupliqué. Le même fait se trouve à deux endroits. Plus tard, une copie change et l'autre non.

Étapes

1. Voir ce qui a changé.

   git diff --cached --stat
   git diff --stat
   

2. Trouver les propres règles du dépôt. Lisez CLAUDE.md, CONTRIBUTING.md et docs/README.md. S'ils précisent quel document traite quel sujet, suivez-les. Ils priment sur l'étape 3.
3. Router chaque modification vers son propriétaire. Utilisez resources/doc-routing.md. Un fait a un seul emplacement. Les autres documents y font référence.
4. Trouver les références obsolètes. Pour chaque nom que vous avez renommé ou supprimé (une fonction, un indicateur, un point de terminaison, un paramètre, un chemin de fichier, une commande) :

   git grep -n '<ancien nom>'
   

   Corrigez chaque occurrence dans un document. Relancez la commande grep. La post-condition est : aucune occurrence, ou seulement des occurrences qui doivent rester (par exemple une entrée CHANGELOG concernant le renommage).
5. Éditer. Modifiez uniquement ce que la modification du code rend erroné ou incomplet. Ne réécrivez pas des sections non concernées. Pour un libellé clair, utilisez la compétence simple-english si elle est installée.
6. Valider ensemble. Mettez en scène les modifications de documentation avec le code. Ne les placez pas dans une PR ultérieure.
7. Rapporter. Listez les documents que vous avez modifiés. Si aucun ne nécessitait de changement, dites-le en une ligne et donnez la raison. Par exemple : « Aucun doc : refactorisation interne, aucun changement de comportement, de commande ou de paramètre. »

Lorsque le propriétaire n'est pas clair

Demandez à l'utilisateur. Ne créez pas un nouveau document pour éviter la question.

Un test utile : s'agit-il d'un fait concernant l'état actuel (un paramètre, une version, un état) ? Il va dans le document de référence ou d'état. S'agit-il d'une procédure (étapes que quelqu'un suit) ? Elle va dans le guide, le runbook ou la compétence propriétaire de cette procédure.

Les spécifications priment

Si le dépôt possède un fichier SPEC.md (voir engineering:spec-writing) ou des spécifications gener8v sous .gener8v/specifications/, ils définissent le comportement attendu.

• Si votre modification respecte ce que dit la spécification, la spécification n'a pas besoin de modification.
• Si votre modification contredit la spécification, arrêtez-vous. Prévenez l'utilisateur. Modifiez d'abord la spécification, via son propriétaire : engineering:spec-writing pour SPEC.md, gener8v:specification pour les spécifications de pipeline. Ne modifiez pas la spécification en silence pour correspondre au code.

Documents de pipeline

Ne modifiez pas manuellement les fichiers sous .gener8v/. Les compétences de pipeline gener8v les écrivent et les mettent à jour.

Compétences connexes

• engineering:documentation-bootstrap : lorsqu'un document entier est manquant, pas seulement un paragraphe.
• engineering:github-pr-merge : exécute cette vérification avant une PR.
• engineering:github-release : lit la section Unreleased du CHANGELOG que cette compétence maintient à jour.