docs-update (mise à jour de la documentation)
La documentation se dégrade en silence : rien n'échoue, mais le texte cesse simplement d'être vrai. Cette compétence trouve les documents que les modifications récentes auraient dû toucher et les met à jour.
Les commandes ci-dessous utilisent le chemin complet ~/.claude/skills/docs-update/scripts/. Exécutez-les exactement comme écrites – conservez le ~ initial et ne le développez pas. Une règle d'autorisation correspond à la chaîne de commande littérale, donc /home/<vous>/.claude/... (le tilde développé), python3 ~/..., un chemin relatif, ou un cd préalable sont chacun une chaîne différente, chacun demandant une nouvelle autorisation. Un chemin avec tilde n'est pas "le chemin absolu écrit de manière informelle" – pour une règle d'autorisation, ce est le chemin.
La documentation est livrée avec la modification, pas après. Si vous êtes sur une branche de fonctionnalité, commitez la documentation sur cette branche pour que la fusion l'emporte. Une PR de suivi de documentation est une PR que personne n'écrit.
1. Choisir le périmètre
Par ordre de priorité :
L'utilisateur a précisé. "Analyse complète", "depuis v2.1", "juste cette branche" – utilisez-le. Une analyse complète est --full et lit tout ; c'est le bon choix après une longue absence ou lors de l'adoption de cette compétence sur un dépôt pour la première fois.
Un document enregistre son propre point de dernière mise à jour :
~/.claude/skills/docs-update/scripts/docscheck.py markers
Si un document contient Dernière mise à jour : <date|sha>, limitez ce document à partir de là (--since). Les documents qui indiquent des dates différentes ont leurs propres périmètres ; il n'y a pas de réponse unique.
Sinon, déduisez-le de git :
~/.claude/skills/docs-update/scripts/docscheck.py scope
Il privilégie la dernière branche fusionnée (le travail d'une branche est l'unité que les gens veulent dire), en se rabattant sur le dernier commit. Remplacez avec --since <ref>.
Le travail effectué dans cette session est un cas que le script ne peut pas voir. Si cette session a effectué les modifications, vous connaissez déjà les fichiers ; passez la référence pré-session comme --since, ou basez-vous sur votre propre liste de modifications.
scope sépare kind=code de kind=doc-already-touched. La deuxième liste est importante : ces documents ont été mis à jour en même temps que la modification, vérifiez donc leur exactitude plutôt que leur absence.
2. Trouver les documents réellement impactés par la modification
~/.claude/skills/docs-update/scripts/docscheck.py impacted
Pour chaque fichier de code modifié, cela signale les documents qui citent ce chemin exact. Un document qui mentionne un fichier que vous avez modifié est celui qui décrit le plus probablement quelque chose qui n'est plus vrai, et c'est un bien meilleur point de départ que de relire chaque document.
Il ne correspond qu'aux chemins complets, délibérément. Correspondre également aux répertoires parents semble plus généreux mais est inutile : sur un monorepo, apps/web-nuxt/ apparaît dans 55 des 62 documents, donc tout impacte tout.
result=none est normal et ne signifie pas "rien à faire" – cela signifie qu'aucun document ne nomme ces chemins, donc jugez plutôt par sujet. C'est l'étape 3.
3. Juger par sujet, en utilisant la taxonomie documentaire du dépôt
impacted trouve les citations de chemins. Il ne peut pas trouver un document qui décrit un comportement que vous avez modifié sans nommer de fichier. Lisez donc la modification et demandez ce qu'elle signifie.
Apprenez d'abord comment ce dépôt organise les documents – un brain/, un docs/, un CONTEXT.md, un répertoire ADR – et suivez cette structure plutôt que d'en inventer une. Si une compétence de projet couvre les documents (.claude/skills/*), elle a priorité sur celle-ci.
Le tableau de correspondance habituel :
| La modification | Le document |
|---|---|
| nouvelle fonctionnalité visible par l'utilisateur | document de fonctionnalité + sa ligne dans l'index/catalogue ; liste des fonctionnalités du README |
| changement de comportement existant | le document de cette fonctionnalité |
| schéma, authentification, build, stockage, temps réel, fournisseurs | le document d'architecture correspondant |
| une décision non évidente, ou soulevée en relecture | le journal des décisions/ADR, avec son pourquoi |
| nouveau terme | le glossaire |
| nouvelle variable d'environnement, commande, script | le README et tout document de configuration/ops |
| nouvelle dépendance | tout document listant la pile technique (ces listes sont maintenues à la main et toujours oubliées – diff du manifeste) |
| modification visible par l'utilisateur | CHANGELOG [Unreleased] |
Deux pièges :
- Faits dérivés intégrés dans la prose. Un document disant "la version actuelle est 2.16.2" ou listant la pile technique est une copie de quelque chose d'autre qui a bougé. Diff la source de vérité (le manifeste, le fichier de version) plutôt que de faire confiance à la prose.
- Documents destinés à être historiques ou visionnaires. Les entrées CHANGELOG, TODO et ROADMAP citent des fichiers qui ont été supprimés ou jamais écrits. Ne les "corrigez" pas.
4. Vérifier que les citations sont toujours résolubles
~/.claude/skills/docs-update/scripts/docscheck.py links
Deux types :
kind=link– un lien markdown relatif dont la cible a disparu. Toujours un vrai problème.kind=source– un chemin en code en ligne qui n'existe plus, généralement parce que le fichier a été déplacé ou renommé. Les documents narratifs sont exclus, et les expansions d'accolades,<placeholders>, les globs et les sorties de build gitignorées sont filtrées, donc ce qui subsiste mérite d'être examiné.
Corrigez ce qui est dans le périmètre. Les autres résultats dans le dépôt valent la peine d'être signalés mais n'élargissez pas silencieusement le travail à une analyse complète.
5. Écrire
Déslopifiez tout ce que vous écrivez
Appliquez la compétence unslop à chaque ligne que vous ajoutez ou modifiez. La documentation est l'endroit où le slop fait le plus de dégâts : elle est lue par des gens qui essaient d'apprendre quelque chose, c'est la première chose qu'un nouveau venu rencontre, et contrairement à un message de chat, elle reste.
Les signes qui apparaissent spécifiquement dans la documentation :
- Ouvertures qui s'éclaircissent la gorge. "Ce document fournit un aperçu de...", "Dans cette section, nous explorerons...". Supprimez-les et commencez par le fait.
- Réécrire le code en prose. "La fonction
getUserrécupère un utilisateur." Si la phrase est l'identifiant développé en anglais, elle ne vaut rien. Écrivez la partie que le code ne peut pas dire : la contrainte, le pourquoi, l'écueil. - Intensificateurs vides : complet, robuste, transparent, puissant, flexible, simplement, facilement, juste. "Exécutez simplement X" est faux chaque fois que X n'est pas simple.
- Hésitations alors que la réponse est définitive : "généralement", "typiquement", "devrait normalement". Soit ça fait, soit ça dépend de quelque chose de nommable – nommez-le.
- Remplissage note-que : "Il est important de noter que", "Veuillez noter", "Gardez à l'esprit". La phrase après est le contenu ; livrez-la.
- Sections de résumé qui résument la page au-dessus. Si le document a besoin d'un récapitulatif, il est trop long.
- Colonnes de description qui répètent le nom. Une ligne de tableau
| --verbose | Active la sortie verbose |coûte une ligne et n'apprend rien. - Bourrage par la règle de trois – un troisième exemple ajouté pour le rythme plutôt que parce qu'il diffère des deux premiers.
Correspondre au fichier, pas au slop
Correspondre à la voix existante du fichier : son temps, sa densité, si les entrées sont des lignes uniques ou de la prose. Un document où une section devient soudainement différente est pire qu'un document uniformément concis.
Ces deux règles ne s'opposent que lorsque le document existant est lui-même négligé. Alors : respectez sa structure et sa densité, pas son remplissage, et ne réécrivez pas les sections que vous n'avez pas touchées par ailleurs. Une mise à jour de documentation qui restyle également tout le fichier est un diff impossible à réviser, et elle enterre la modification qui comptait vraiment. Si un document a besoin d'une passe de prose dans son ensemble, dites-le et proposez-le comme un travail séparé.
Le reste
- Liez les chemins source plutôt que de réécrire le code, afin que la prochaine modification casse le lien au lieu de contredire silencieusement la prose.
- Décrivez ce qui est vrai maintenant, au présent. Les documents ne sont pas un journal des modifications : "nous avons remplacé X par Y" appartient au CHANGELOG, "le système utilise Y" appartient au document.
- Si un document a un marqueur de dernière mise à jour, déplacez-le.
6. Rapporter
- le périmètre utilisé, et pourquoi celui-ci
- les documents mis à jour, et ce qui a changé dans chacun
- les documents vérifiés et délibérément laissés intacts
- les liens ou citations cassés trouvés en dehors du périmètre, listés mais non corrigés
- tout ce que vous n'avez pas pu juger sans l'utilisateur