Lint de documentation
Exécuté une fois juste avant le déploiement. Ne détecte que ce que la validation structurelle (pnpm docs:validate) ne peut pas attraper.
Exécuter avec le modèle le plus puissant. La capacité à trouver des règles et la capacité à les suivre sont distinctes.
Périmètre de lecture
Ne pas lire l'intégralité. Une lecture trop large augmente les documents parasites et réduit la précision.
- Obtenir les chemins de code concernés par ce déploiement via
pnpm docs:related <chemins…>pour obtenir les documents routés. - Les ADR liés par ces documents et les plans actifs dans ce domaine.
- Les documents permanents pour lesquels
pnpm docs:validatea émis un avertissement de validité dépassant 90 jours. - Les éléments ouverts dans
docs/findings.md.
Ce qui est inspecté
- Incohérences document-code dans les deux sens. Ce qui est dans le code mais pas dans le document (omission) et ce qui est dans le document mais pas dans le code (hallucination) sont examinés séparément. Ne regarder qu'un seul côté fait perdre la moitié.
- Candidats à la contradiction dans les ADR. Deux ADR Acceptés dans le même domaine avec des conclusions opposées sans relation de remplacement. Utiliser
pnpm docs:links <ADR>pour vérifier la chaîne de remplacement. - Tableaux de valeurs dupliqués avec le code. Le document copie-t-il des valeurs ou listes lisibles dans le code ?
- Plans en suspens depuis plus de 90 jours. Remonter en élément demandant s'il faut abandonner ou reprendre.
- ADR en statut Proposed depuis plus de 14 jours. Décision en attente.
- Expériences personnelles mélangées dans les guides. Les récits comme « j'ai essayé, ça n'a pas marché » doivent aller dans
docs/flows/. - Lignes expirées dans
docs/operations/current-state.md. Les lignes dont la date de vérification est ancienne ne sont pas des succès mais des non-vérifiés.
Résultat
Ajouter des éléments dans docs/findings.md. Chaque élément fait cinq lignes.
- constat 2026-09-04 · docs/policies/xxx.md
affirmation : (ce que dit le document)
preuve : (chemin de code ou numéro d'ADR)
suggestion : (ce qu'il faut faire)
périmètre : (corriger dans ce déploiement ou reporter)
Ne pas corriger. La résolution est faite par la PR qui effectue le travail, et cette PR supprime l'élément.
Mettre à jour la date de vérification des documents permanents lus avec la date du jour. Ne mettre à jour que les documents effectivement comparés au code. Apposer la date du jour sur un document non comparé donne un faux signal de fraîcheur.
Budget
Partir du principe qu'un tiers des constats sont des faux positifs. La précision de la détection seule des incohérences par LLM est d'environ 0,6. En cas de doute, l'indiquer dans l'élément.
Dans la première ligne du rapport, inscrire « nombre de constats ouverts et âge de l'élément le plus ancien ».
Ajout et suppression de règles
Pour ajouter un élément à cette liste, il faut fournir un cas réel que cet élément aurait détecté. Ne pas ajouter d'élément sans fondement. Si aucune occurrence du même échec n'est survenue depuis 12 mois et que l'élément n'a pas été utile dans pnpm docs:harness-eval, le supprimer.