Détection de dérive documentaire post-merge

Contexte

La documentation dérive dès qu’une PR est mergée sans mise à jour correspondante. Au fil du temps, les docs référencent des APIs modifiées, des endpoints supprimés, des configurations obsolètes.

Ce use case configure une Routine GitHub déclenchée sur pull_request.closed (merged) qui :

1. Scanne les fichiers modifiés dans la PR
2. Identifie les docs qui référencent ces APIs/fichiers
3. Ouvre une PR de correction doc, ou une issue listant les dérives

Agent cœur : strange (16) en mode reverse doc, adapté pour tourner de façon autonome.

Prérequis

• Compte Claude Pro/Max/Team/Enterprise avec Claude Code web activé
• Repository GitHub connecté avec docs dans docs/ (ou README, wiki)
• App Claude GitHub installée sur le repo
• Docs existantes (la routine ne crée pas la doc from scratch)

Étapes

1. Générer la configuration de la routine

/ulk:routine
# Agent : strange (16) mode=drift
# Repo : votre-org/votre-repo
# Objectif : scanner les dérives doc après chaque merge sur main
# Trigger : GitHub pull_request.closed (merged, base: main)

L’agent routine (53) génère docs/routines/docs-drift-config.md avec le prompt complet.

2. Configurer la Routine sur claude.ai

1. Aller sur https://claude.ai/code/routines → New routine
2. Name : Docs Drift — <nom-repo>
3. Prompt : voir ci-dessous (prompt self-contained)
4. Repository : votre repo
5. Trigger : GitHub event → pull_request → closed

Filtres recommandés :

Filtre	Valeur	Raison
Base branch	main	Uniquement les merges sur main
Is draft	false	Ignorer les drafts
Is merged	true	Uniquement les PR effectivement mergées

3. Prompt self-contained (copier-coller)

Tu es strange (16) adapté pour tourner de façon autonome sur <REPO>.

CONTEXTE DE LA PR MERGÉE (injecté automatiquement dans le message suivant).

OBJECTIF : Identifier les fichiers de documentation qui référencent des APIs,
fonctions, endpoints, ou composants modifiés par cette PR. Ouvrir une PR de
correction si des dérives concrètes sont trouvées, sinon terminer silencieusement.

PÉRIMÈTRE :
- Docs à scanner : docs/, README.md, CLAUDE.md, *.md à la racine
- Fichiers source à inspecter : tous les fichiers modifiés dans la PR

ÉTAPES :
1. Lire la liste des fichiers modifiés par la PR mergée via :
   git log --oneline -1 --name-only
   git diff HEAD~1 --name-only

2. Pour chaque fichier source modifié :
   a. Extraire les noms d'exports, fonctions, types, endpoints, configs modifiés
   b. Chercher ces noms dans docs/ et README.md avec grep

3. Pour chaque occurrence doc trouvée :
   a. Lire le contexte (paragraphe autour)
   b. Déterminer si la doc est maintenant inexacte (API renommée, supprimée, signature changée)
   c. Si inexacte → noter dans la liste des dérives

4. Si dérives trouvées (liste non vide) :
   a. Créer branche : claude/docs-drift-<sha-court>-<date>
   b. Corriger les occurrences identifiées dans les fichiers doc
   c. Ouvrir draft PR avec le diff et la liste des corrections
   d. Logger dans docs/routines/docs-drift-log.md

5. Si aucune dérive :
   a. Logger "YYYY-MM-DD — PR #N : aucune dérive détectée" dans docs/routines/docs-drift-log.md
   b. Terminer sans créer de branche ni de PR

LIMITES ABSOLUES :
- Ne jamais modifier les fichiers source (uniquement les docs)
- Ne jamais supprimer de sections docs sans backup
- Maximum 1 PR ouverte par run
- Ne pas ouvrir de PR si les changements doc touchent > 20 fichiers (ouvrir une issue à la place)
- Branche : claude/docs-drift-<sha-court>-<date>

CAS LIMITE — PR cosmétique (typos, formatting seulement) :
Si la PR ne touche qu'à du formatting ou des commentaires sans export public,
terminer silencieusement (pas de log).

4. Observer un run

Exemple pour une PR qui renomme authMiddleware → withAuth :

Docs Drift — run #3 (PR #87 merged)

Phase 1 — Fichiers modifiés dans PR #87 :
  src/middleware/auth.ts
  src/types/auth.d.ts

Phase 2 — Extraction des exports modifiés :
  Renommage détecté : authMiddleware → withAuth
  Type modifié : AuthConfig.secret → AuthConfig.signingKey

Phase 3 — Recherche dans docs/ :
  docs/api/middleware.md:23 → référence authMiddleware ⚠️
  docs/api/middleware.md:45 → référence AuthConfig.secret ⚠️
  README.md:112 → exemple avec authMiddleware ⚠️
  docs/getting-started.md:67 → exemple avec authMiddleware ⚠️

Phase 4 — 4 dérives trouvées → correction...
  Branche : claude/docs-drift-abc1234-20260414
  Corrections : 4 occurrences dans 3 fichiers

Draft PR #88 créé — "docs: fix drift après renommage authMiddleware→withAuth"

Exemple de draft PR générée

## Docs Drift — Corrections post-merge PR #87

**PR mergée** : #87 — feat: rename authMiddleware to withAuth
**Dérives détectées** : 4 occurrences dans 3 fichiers

### Changements

| Fichier | Ligne | Avant | Après |
|---------|-------|-------|-------|
| docs/api/middleware.md | 23 | `authMiddleware` | `withAuth` |
| docs/api/middleware.md | 45 | `AuthConfig.secret` | `AuthConfig.signingKey` |
| README.md | 112 | `authMiddleware(app)` | `withAuth(app)` |
| docs/getting-started.md | 67 | `authMiddleware` | `withAuth` |

### Vérification recommandée

- [ ] Vérifier que les corrections de sens sont correctes (pas juste find/replace)
- [ ] Tester les exemples de code modifiés
- [ ] Merger si tout est correct

---
*Auto-généré par ulk docs-drift (strange 16 + routine 53)*

Variantes

• Filtre par label : Ajouter filtre labels: api-change pour ne réagir qu’aux PRs taguées
• Multi-repo docs : Ajouter un second repo de documentation en lecture seule
• Issue plutôt que PR : Modifier le prompt pour créer des issues au lieu de PRs (revue humaine systématique)
• Combine avec shuri : Après la correction des dérives, déclencher shuri mode=sync pour mettre à jour CLAUDE.md

Agents enchaînés

Workflow complet post-merge :

PR mergée (GitHub event)
  ↓
docs-drift routine (strange 16)
  → PR #N drift corrections (draft)
    ↓
  shuri mode=sync (01)
    → CLAUDE.md mis à jour
      ↓
    2b3 (08) checkpoint
      → commit final propre

Troubleshooting

Symptôme	Cause probable	Résolution
Routine se déclenche trop souvent	Filtre is merged manquant	Ajouter le filtre dans la config GitHub trigger
Trop de faux positifs	Noms trop génériques	Affiner le prompt : “ignorer les noms < 4 caractères”
PR avec > 20 fichiers docs	PR très large	Le prompt gère ce cas → issue créée automatiquement
Docs dans un repo séparé	Repo doc distinct	Ajouter le repo doc en lecture seule dans la config de la routine

Voir aussi

• 36-routine-architect.md — Créer d’autres routines cloud
• 17-strange-user-docs.md — Génération de doc depuis le code (mode interactif)
• 14-shuri-spec-to-kanban.md — Sync locale de CLAUDE.md et README