Validateur de Cohérence de Contenu
Aperçu
Vérifie le contenu pour la cohérence du ton, de la terminologie, du formatage et de la structure sur plusieurs sources de documentation (sites web, dépôts GitHub, docs locaux). Génère des rapports de divergences en lecture seule avec des constats classés par sévérité et des suggestions d'actions correctives, incluant les chemins de fichiers et les numéros de ligne.
Exemples
- Audit pré-livraison : Avant de taguer une nouvelle version, exécutez le validateur pour détecter les incohérences de version entre votre README, le site de documentation et le journal des modifications — par exemple, le site annonce v2.1.0 mais le README GitHub fait encore référence à v2.0.0.
- Vérification post-rebranding : Après avoir renommé un produit ou mis à jour la terminologie (par exemple, « plugin » en « extension »), validez que tous les documents, pages d'accueil et guides de contribution utilisent systématiquement le nouveau terme.
- Examen d'intégration : Lorsqu'un nouveau contributeur signale une documentation confuse, effectuez un contrôle de cohérence pour révéler des allégations de fonctionnalités contradictoires, des informations de contact obsolètes ou des sections manquantes dans vos sources de documentation.
Prérequis
- Accès à au moins deux sources de contenu (site web, dépôt GitHub, ou dossier de documentation local)
- Permissions WebFetch configurées pour les URL distantes (sites déployés, contenu brut GitHub)
- Documentation locale stockée dans des chemins reconnaissables (
docs/,claudes-docs/,internal/)
Instructions
- Découvrir les sources — recherchez les répertoires de build (
dist/,build/,public/,out/,_site/), les fichiers README/CONTRIBUTING GitHub, et les dossiers de documentation locaux :find . -maxdepth 3 -name "README*" -o -name "CONTRIBUTING*" | head -20 ls -d docs/ claudes-docs/ internal/ 2>/dev/null - Extraire les données structurées de chaque source : numéros de version, allégations de fonctionnalités, noms de produits, slogans, informations de contact, URL, et exigences techniques :
grep -rn 'v[0-9]\+\.[0-9]\+' docs/ README.md grep -rn -i 'features\|capabilities' docs/ README.md - Vérifier l'extraction — confirmez au moins 3 points de données par source. Si une source renvoie un résultat vide, consultez le tableau de gestion des erreurs avant de continuer.
- Construire une matrice de comparaison en associant chaque source à toutes les autres (site web vs GitHub, site web vs docs locaux, GitHub vs docs locaux) :
diff <(grep -i 'version' README.md) <(grep -i 'version' docs/overview.md) - Classer les divergences par sévérité :
- Critique : numéros de version contradictoires, listes de fonctionnalités opposées, informations de contact erronées, références croisées cassées
- Avertissement : terminologie incohérente (par exemple, « plugin » vs « extension »), informations manquantes dans une source, dates obsolètes
- Information : différences stylistiques, formulation spécifique à la plateforme, niveaux de détail variés
- Appliquer la priorité de confiance : site web (le plus fiable) > GitHub (orienté développeur) > documentation locale (usage interne).
- Générer un rapport en Markdown contenant : résumé exécutif, tableaux de comparaison par paire, matrice de cohérence terminologique, et actions prioritaires avec chemins de fichiers et numéros de ligne.
- Sauvegarder dans
consistency-reports/YYYY-MM-DD-HH-MM-SS.md.
Format du rapport
# Rapport de Cohérence — JJ-MM-AAAA
## Résumé Exécutif
| Sévérité | Nombre |
|----------------|--------|
| Critique | 2 |
| Avertissement | 5 |
| Information | 3 |
## Site web vs GitHub
| Champ | Site web | GitHub | Sévérité |
|--------------|----------|-------------|---------------|
| Version | v2.1.0 | v2.0.0 | Critique |
| Fonctionnalité X | listée | manquante | Avertissement |
## Actions
1. **Critique** — Mettre à jour `README.md:14` version de v2.0.0 → v2.1.0
2. **Avertissement** — Ajouter « Fonctionnalité X » à la liste des fonctionnalités dans `README.md`
Gestion des erreurs
| Erreur | Cause | Solution |
|---|---|---|
| Contenu du site web inaccessible | L'URL retourne une erreur 4xx/5xx ou le répertoire de build est manquant | Vérifier que le site est déployé ou exécuter le build local ; vérifier les permissions WebFetch |
| Limite de débit de l'API GitHub | Trop de requêtes dans une courte fenêtre | Pause et réessayer après le reset ; utiliser des requêtes authentifiées |
| Aucun répertoire de documentation | Les chemins attendus n'existent pas | Confirmer le répertoire de travail ; spécifier explicitement le chemin de la documentation |
| Extraction de contenu vide | Rendu côté client non visible par fetch | Utiliser le répertoire de build local au lieu de l'URL en direct |
| Échec de la commande diff | Les chemins de fichiers contiennent des caractères spéciaux | Mettre entre guillemets tous les chemins de fichier passés à diff et grep |
Ressources
- Logique de découverte des sources :
${CLAUDE_SKILL_DIR}/references/how-it-works.md - Priorité de confiance et timing de validation :
${CLAUDE_SKILL_DIR}/references/best-practices.md - Exemples de cas d'utilisation :
${CLAUDE_SKILL_DIR}/references/example-use-cases.md