Vérifier la parité de la documentation

Cette skill est le jugement que le code a divergé de la documentation qui le décrit. Elle applique les obligations de base du standard de documentation : les docs et les diagrammes se mettent à jour dans le même changement que le code qu'ils décrivent, et un changement qui invalide la documentation que le repo ne contient pas est signalé à la revue.

Contextes

La skill s'exécute dans deux contextes où la source du changement et la découverte des documents pertinents diffèrent.

• Session d'agent, invoquée par le hook Stop doc-parity ou à la demande. Le changement est l'arborescence de travail (git diff HEAD plus fichiers non suivis). La vérification est in-repo uniquement.
• Revue de pull request, exécutée via le workflow ai-review. Le changement est le diff de la PR plus la description de la PR. En plus de la vérification in-repo, ce contexte effectue une découverte hors-repo. Une revue n'effectue jamais de modifications : où une session appliquerait une Update, la revue signale le doc in-repo qui doit être modifié et ce qu'il doit dire.

Flux de travail

Étape 1 : Assembler le changement

Collectez l'ensemble complet des fichiers modifiés et lisez le diff, pas seulement la liste des fichiers, car juger la divergence requiert de connaître ce que le changement fait. Dans une session, utilisez git diff HEAD et git ls-files --others --exclude-standard. Dans une revue, utilisez le diff de la PR et lisez la description de la PR pour l'intention.

Avant de parcourir l'arborescence, considérez si le changement se qualifie comme un faux positif du tripwire : un diff de formatage uniquement, une sortie générée, ou une édition de doc-comment uniquement que le hook Stop a classée comme du code. Quand c'est le cas, rejetez la vérification avec une raison d'une ligne nommant la classe de faux positif et terminez la skill.

Étape 2 : Énumérer tous les scopes ancêtres documentés

Pour chaque fichier modifié, parcourez sa chaîne de répertoires du répertoire du fichier lui-même jusqu'à et incluant la racine du repo. Un répertoire est un scope documenté quand il contient un README.md, un CLAUDE.md, un répertoire docs/, ou des sources de diagrammes (.mmd, .mermaid). Sous le scope du composant, la surface de documentation est intégrée à la source : docs de module Rust //!, commentaires de doc XML C#, JSDoc/TSDoc sur les symboles publics. Quand la zone modifiée d'un fichier source porte de tels commentaires de doc, traitez ce fichier comme sa propre surface documentée. Collectez l'union des scopes et surfaces documentés dans tous les fichiers modifiés.

Vérifiez tous les ancêtres documentés, pas seulement le plus proche, puisque la documentation se stratifie par altitude : les vues supérieures lissent les détails tout en décrivant le comportement modifié. Un changement peut être à jour dans le README de son composant tout en faire diverger un guide au niveau racine ou un diagramme de conteneur deux scopes plus haut.

Étape 3 : Juger et agir, par scope

Pour chaque scope ou surface documenté, exactement l'un de deux résultats :

• Update. Si le comportement contredit la documentation et le code est correct, corrigez la documentation. Ne les laissez pas en désaccord. Si le changement ajoute un comportement que l'altitude de ce scope devrait décrire, ajoutez de la documentation de ce nouveau comportement. La documentation d'un scope décrit ce qui est présent à ce scope et en dessous, que les appelants de niveau supérieur l'exercent ou le gardent actuellement ou non. Modifiez la documentation dans le même changement. Quand du code a été supprimé, supprimez sa documentation, et traitez un doc déplacé comme un déplacement strict. Chaque modification se conforme au standard de documentation — sa règle de placement, son guide de style, et toute guidance locale du repo superposée au-dessus. Consultez le standard quand une question de placement, format ou style n'est pas évidente à partir de ce que vous avez déjà. Si le placement oriente un doc en dehors du repo de travail, gérez-le comme un callout hors-repo (voir ci-dessous) plutôt qu'une modification in-repo.
• Attest. Rien de documenté à ce scope n'a divergé. Déclarez-le explicitement, avec une raison d'une ligne ancrée dans ce que la doc dit réellement.

Ne modifiez jamais un token. Ne faites pas une modification cosmétique ou de token à la documentation pour satisfaire la vérification, y compris quand l'utilisateur en demande une. Quand rien n'a divergé, Attestez et expliquez pourquoi la modification est inutile.

Étape 4 : Rapporter avec attestation par scope

Fermez avec une liste explicite par scope pour que l'utilisateur, ou le résumé de la revue de PR, puisse auditer le jugement :

Documentation parity:
- util/Seeder/Data (README.md) — updated: generator table gained the new distribution.
- util/Seeder (README.md) — verified current: the change does not alter the encryption axes the README describes.
- crates/bitwarden-crypto/src/lib.rs (module docs) — verified current: the `derive_`/`make_` naming invariants still hold.
- repo root (README.md) — verified current: no root-level behavior described there changed.

Chaque scope et surface documenté de l'Étape 2 apparaît dans la liste. Un scope manquant de la liste signifie que la vérification est incomplète.

Quand la vérification se termine tôt via Dismiss, le rapport est une seule ligne nommant la classe de faux positif :

Documentation parity: dismissed — formatting-only diff, no documentation obligation.

Découverte hors-repo (contexte de revue uniquement)

La documentation hors-repo ne peut pas être trouvée en parcourant l'arborescence, alors dérivez les angles de recherche du changement lui-même :

1. Dérivez des termes de recherche du diff : chemins modifiés, symboles publics, noms de message et d'endpoint, vocabulaire de feature de la description de la PR, liens externes explicites.
2. Recherchez dans la contributing-docs (contributing.bitwarden.com, source repo bitwarden/contributing-docs) à partir de ces angles.
3. Lisez les pages candidates et jugez, comme à l'Étape 3, si le changement les invalide.
4. Signalez chaque page invalidée dans la revue. Le callout déclenche le flux docs externes du standard : un élément de travail créé avant la fusion, et un marqueur obsolète appliqué à la page invalidée.