Audit de Synchronisation Docs

Vérifiez si la documentation correspond toujours au code, à la configuration, au comportement de l'API, aux commandes, aux exemples et aux flux de travail utilisateur. Signalez les docs obsolètes ou manquantes avec des preuves concrètes et une direction de mise à jour.

Règles Fondamentales

Restez en lecture seule sauf si l'utilisateur demande explicitement de mettre à jour les docs.
Par défaut, lancez un audit complet des docs du dépôt quand l'utilisateur ne fournit pas de périmètre spécifique. Inventoriez les surfaces docs du dépôt (README, répertoires docs, exemples, aide CLI, contrats API, exemples de config) et comparez-les au code qu'elles décrivent.
Les audits complets du dépôt sont en largeur d'abord, puis en profondeur limitée. Inventoriez le dépôt, classez les surfaces par risque, inspectez profondément autant de surfaces à haut risque que le tour le permet, et listez le reste sous Surveyed But Not Deeply Inspected (Vérifié mais non inspectée en détail) avec un pointeur pour relancer un autre passage. Indiquez les nombres de surfaces dans l'en-tête du rapport. Ne présentez jamais un balayage superficiel comme une couverture complète.
Ancrez chaque constat dans les deux côtés du décalage : le code/config/source de vérité et la documentation obsolète ou manquante.
Séparez la dérive confirmée des lacunes docs inférées.
Privilégiez la dérive docs ayant un impact utilisateur plutôt que les problèmes de formulation cosmétique.
Ne signalez pas les préférences de style à moins qu'elles ne rendent les instructions trompeuses, incomplètes ou difficiles à suivre.
Traitez les docs générées avec prudence : identifiez le générateur, le fichier source et la commande de génération attendue avant de recommander des modifications directes.
Si les docs générées semblent obsolètes mais n'ont pas été régénérées, dites-le explicitement et signalez le risque résiduel au lieu d'impliquer que la sortie générée a été vérifiée.
Évitez de créer des docs pendant la phase d'audit.

Entrées

Acceptez n'importe quelle cible docs-sync, notamment :

PRs ou branches : audit docs pour cette PR, quelles docs doivent être mises à jour avant la sortie.
Fonctionnalités : docs sync pour uploads, vérifier les docs de facturation après cette modification.
APIs : audit docs OpenAPI par rapport aux handlers, vérifier les exemples SDK pour le nouvel endpoint.
Config/setup : env docs drift, audit README setup, Docker docs sync.
CLI/workflows : vérifier les docs de commande, le onboarding correspond-il au flux actuel.
Hygiène docs complète du dépôt quand explicitement demandée.

Si le périmètre est flou, déduisez la plus petite frontière utile et énoncez-la. Si aucun périmètre n'est indiqué, ne posez pas de question ; procédez à un audit complet des docs du dépôt. Posez une question seulement si des périmètres différents produiraient des vérifications de docs matériellement différentes.

Flux de Découverte

Établissez la source de vérité.
- Vérifiez git status --short.
- Pour les audits PR/branche, identifiez la base et les fichiers modifiés si possible.
- Localisez les manifests, scripts, routes, configs, fichiers de schéma, migrations, handlers API, points d'entrée CLI, validation env, sources docs générées et tests qui révèlent le comportement attendu.
Localisez la documentation connexe.
- Cherchez les fichiers README, dossiers docs, docs API, specs OpenAPI/Swagger, changelogs, guides setup, docs de déploiement, exemples env, exemples, fixtures, commentaires, pages storybook/docs, docs de packages et runbooks.
- Incluez les docs à proximité de la fonctionnalité et les docs que les utilisateurs consulteraient raisonnablement en premier.
- Pour les docs générées, localisez le fichier source, la commande générateur, la sortie commise et n'importe quelle étape de build ou codegen de docs avant de décider où les mises à jour appartiennent.
Comparez code et docs.
- Exécutez d'abord le script scripts/docs_drift.py fourni quand il est disponible. Il vérifie uniquement les affirmations avec une réponse définitive : les scripts npm run documentés et les cibles make contre ceux qui existent, les liens Markdown relatifs par rapport au système de fichiers, et les noms de variables d'environnement dans les deux sens entre docs et code. Le chemin est relatif au répertoire de cette skill, qui varie selon l'hôte. Utilisez python si python3 n'est pas sur PATH.
- python <skill-dir>/scripts/docs_drift.py --top 30, ou --format json pour filtrer les résultats vous-même.
- Il signale un paramètre documenté qui est en lecture seule à l'intérieur d'un module qu'aucun autre n'importe, ce qui est une configuration qui se lit comme fonctionnelle mais ne peut pas prendre effet. Confirmez que le module est vraiment inaccessible avant de le signaler : la vérification utilise la correspondance de noms et ne peut pas voir les imports dynamiques.
- Ajoutez --check-paths seulement quand vous voulez que les chemins entre guillemets soient également vérifiés. C'est désactivé par défaut car la plupart de ces références sont ambiguës, et sur un grand dépôt le bruit enterre les véritables constatations. Lisez sa sortie comme des pistes, pas des constatations.
- Le script ne juge jamais la prose. La formulation, la complétude et le fait qu'une explication soit réellement correcte sont votre affaire, et c'est généralement là que se trouve la dérive importante.
- Commandes/scripts : noms, arguments, gestionnaire de paquets, répertoire de travail, prérequis, sorties.
- APIs : routes, méthodes, exigences d'auth, forme requête/réponse, codes statut, erreurs, pagination, webhooks, versioning.
- Config/env : vars requises, défauts, exemples, secrets, feature flags, paramètres de déploiement.
- UI/workflows : écrans, labels, étapes, permissions, rôles, états, captures d'écran, exemples.
- Données/schéma : champs, migrations, enums, limites, contraintes, seed data, formats import/export.
- Tests/exemples : exemple de code, fixtures, utilisation SDK, exemples curl, captures d'écran, sorties attendues.
Vérifiez en toute sécurité.
- Exécutez des commandes à faible risque qui révèlent les décalages docs/source quand disponibles : build docs, vérification de liens, typecheck des exemples, génération OpenAPI, aide CLI, scripts de package ou tests ciblés.
- N'installez pas les dépendances ni ne régénérez les grandes docs sauf si l'utilisateur le demande ou le dépôt l'attend clairement.
- Ne lancez jamais une commande qui écrit dans le dépôt comme effet secondaire. python -m compileall et py_compile émettent des fichiers .pyc, les formateurs réécrivent les sources, et les installateurs touchent les lockfiles. La sortie .pyc est généralement gitignorée, donc git status ressemble à du clean alors que l'arborescence a en fait été modifiée. Préférez les vérifications qui n'écrivent rien, et si un langage n'offre pas de vérification en lecture seule, signalez-le sous les vérifications ignorées.
- Enregistrez les vérifications exécutées et les vérifications ignorées.

Ce Qu'il Faut Chercher

Instructions de setup README qui ne fonctionnent plus.
Docs manquantes pour les nouvelles routes, commandes, env vars, permissions, flags, migrations, webhooks ou workflows utilisateur.
Anciens noms, chemins, captures d'écran, labels, exemples ou clés de config après un renommage.
Docs API qui ne sont pas d'accord avec les handlers, schémas, validation, auth, erreurs ou codes statut.
Changelog/notes de sortie manquant les modifications visibles par l'utilisateur ou opérationnelles.
.env.example, docs de déploiement ou runbooks manquant la configuration requise.
Code exemple qui importe d'anciens chemins, appelle les vieilles APIs, utilise les noms de package stales ou omet le setup requis.
Docs générées commises mais obsolètes par rapport à la source.
Commentaires ou docs d'architecture décrivant une ancienne frontière de module ou un comportement plus ancien.

Rubrique de Sévérité

P0 : La dérive docs pourrait causer une panne en production, une perte de données, une exposition de sécurité, un déploiement cassé, une mauvaise gestion des identifiants ou une défaillance opérationnelle critique.
P1 : Dérive docs à haut impact qui bloque le setup, la sortie, l'intégration API, la migration, le support ou un workflow utilisateur/admin courant.
P2 : Docs obsolètes ou manquantes significatif susceptible de confondre les utilisateurs, reviewers, opérateurs, consommateurs SDK ou contributeurs.
P3 : Nettoyage docs de risque inférieur, dérive de nommage, exemples, commentaires ou polish qui doivent être en queue.

Standards de Preuve

Vérifiez chaque citation avant de l'écrire. Relisez la plage exacte et confirmez qu'elle contient ce que vous décrivez. Quand vous citez un symbole nommé, fonction, CTE ou bloc, citez la ligne où le nom est défini, pas une ligne à l'intérieur d'un bloc voisin. Quand vous citez du texte, citez le fichier où la citation se trouve réellement. Préférez une seule ligne d'ancrage contenant un jeton distinctif plutôt qu'une plage comptée à la main.
Quand vous attribuez un constat à la sortie d'un outil, citez le chemin et la ligne que l'outil lui-même a signalés. Ne déduisez jamais les lignes sur lesquelles un linter ou type checker a tiré en lisant le code. Si la sortie de l'outil n'énonce pas la ligne, rapportez le motif sans prétendre que l'outil l'a signalé.
Ne reposez jamais un compte d'un grep, d'un script ou d'un outil sans la sortie brute en face de vous. Si vous ne pouvez pas re-dériver le nombre, décrivez le motif au lieu de le compter.
Avant de rapporter que quelque chose est absent -- config indocumentée, une dépendance inutilisée, un contrôle manquant, une variable que rien ne lit -- vérifiez chaque emplacement plausible, pas le premier. Pour une variable de config cela signifie le README, les fichiers d'exemple env, les manifests de déploiement, les commentaires et les appelants transitifs de n'importe quel helper qui la lit. Pour une dépendance cela signifie que c'est une exigence transitive documentée de quelque chose que vous utilisez. Une affirmation négative d'un seul grep n'est pas une preuve.
Citez la source de vérité et la documentation obsolète/manquante.
Pour les docs manquantes, citez le code/config/modification qui devrait être documentée et la zone de doc où les utilisateurs l'attendraient.
Incluez les chemins exacts et références de lignes chaque fois que possible.
Indiquez si les docs sont confirmées obsolètes, probablement obsolètes ou manquantes selon l'inférence.
Ne prétendez pas que les docs sont sûres de supprimer sauf si les références, liens, sources générées et navigation ont été vérifiés.

Format de Rapport

Utilisez cette structure sauf si l'utilisateur demande le contraire :

**Docs Sync Audit: <périmètre>**

Aucun code modifié. J'ai comparé <périmètre source/code/modification> par rapport à <docs vérifiées>. <résumé de vérification>. Aucun P0 trouvé / P0s trouvés : <nombre>.

1. **P1: <titre du constat>.**
   Dérive : <ce que disent ou omettent les docs vs ce que font le code/config>.
   Impact : <qui est trompé ou bloqué>.
   Preuve : source `<chemin>:<ligne>`; docs `<chemin>:<ligne>`.
   Mise à jour suggérée : <direction de modification docs spécifique>.

2. **P2: <titre du constat>.**
   Dérive : <ce qui est obsolète/manquant>.
   Impact : <pourquoi c'est important>.
   Preuve : source `<chemin>:<ligne>`; docs `<chemin>:<ligne>` ou zone docs attendue.
   Mise à jour suggérée : <direction spécifique>.

**Docs Susceptible d'Être Mises à Jour**
- `<chemin>` : <pourquoi>

**Vérifié mais non Inspectée en Détail**
- <Pour les audits complets du dépôt seulement : surfaces qui ont été inventoriées mais non inspectées profondément ce passage, et lesquelles relancer ensuite. Omettez cette section entièrement pour les audits ciblés.>

**Vérifications Exécutées**
- `<commande>` : <résultat>

**Non Testé**
- <build docs, vérification de liens, rebuild docs générées ou lacunes docs externes et pourquoi ; signalez le risque résiduel quand la sortie générée n'a pas été reconstruite>

**Hypothèses**
- <seulement inclure si utile>

Si aucune dérive n'est trouvée, dites-le clairement et listez les risques résiduels tels que les docs générées non reconstruites, les builds/vérifications de liens de docs non exécutés, ou les docs externes inaccessibles.

Flux de Mise à Jour Post-Audit

Quand l'utilisateur demande de mettre à jour les docs :

Mettez à jour uniquement les docs connexes à la dérive confirmée ou aux lacunes inférées explicitement sélectionnées.
Préservez le style, la structure et la terminologie de la documentation du dépôt.
Mettez à jour les docs générées à partir de la source/générateur quand c'est pratique au lieu de modifier directement la sortie générée.
Mettez à jour ensemble les exemples, captures d'écran, changelogs, exemples env, specs API et runbooks quand ils décrivent le même comportement.
Exécutez la build docs, vérification de liens, typecheck d'exemples ou vérification ciblée quand disponible.
La réponse finale doit mapper les constatations aux fichiers mis à jour et lister les vérifications exécutées.

Skills Connexes

Cette skill en est une de sept review skills qui partagent un contrat de rapport unique : chaque constat porte une sévérité P0-P3 et un chemin:ligne que vous pouvez ouvrir. Les cinq autres couvrent la préparation au lancement, la sécurité, la structure du dépôt, les idées d'amélioration et la communication de pull request. Elles se trouvent à https://github.com/specialone0007/review-skills.

Notes de Portabilité d'Agent

Utilisez les outils shell, recherche, git, browser, GitHub, docs ou MCP disponibles selon le contexte.
Si les docs web, docs privées, docs rendues ou docs API externes sont indisponibles, continuez avec l'inspection de source locale et signalez la limitation.
Si l'hôte supporte les commentaires de review en ligne, émettez-les uniquement pour la dérive docs confirmée actionnable et gardez les plages serrées.

docs-sync-audit