doc-reset — Remise en état documentaire

Agent de diagnostic et correction minimale de la documentation d'un projet ulk. Fonctionne sur n'importe quel projet (pas seulement ce repo).

Mode d'utilisation

/ulk:doc-reset          # Audit seul — liste les problèmes
/ulk:doc-reset --fix    # Audit + corrections automatiques minimales

---

Phase 0 : Détection du mode documentaire

DOC_MODE=$(grep -m1 '^doc-mode:' CLAUDE.md 2>/dev/null \
  | sed 's/doc-mode:[[:space:]]*//' | tr -d '[:space:]"'"'"')
if [ -z "$DOC_MODE" ] || [ "$DOC_MODE" = "auto" ]; then
  [ -d docs/backlog ] && DOC_MODE="faru" \
    || { [ -f docs/07-spec/spec.md ] || [ -f docs/spec.md ] || [ -f docs/todo.md ]; } \
    && DOC_MODE="obsidian" || DOC_MODE="faru"
fi
echo "▸ Mode : $DOC_MODE"

---

Phase 1 : Vérification spec / backlog

Mode faru

ls docs/backlog/ 2>/dev/null | wc -l

Vérifier :

• docs/backlog/ existe
• Au moins une carte */CARD.md présente
• Chaque CARD.md a les champs frontmatter minimaux : title, type, status

Problèmes à signaler :

• docs/backlog/ absent → MISSING (avec --fix : mkdir -p docs/backlog/)
• Cartes sans title: ou status: → INVALID (lister les chemins)
• Cartes en status: wip sans completed: ni description: → INCOMPLETE

Mode obsidian

Vérifier que docs/07-spec/spec.md ou docs/spec.md existe et contient un frontmatter YAML valide (délimiteurs ---).

Problèmes :

• Fichier absent → MISSING
• Frontmatter manquant ou malformé → INVALID

---

Phase 2 : Vérification todo.md (mode obsidian / coexist)

cat docs/todo.md 2>/dev/null | head -10

Vérifier :

• kanban-plugin: board dans le frontmatter
• Au moins 3 colonnes ## H2 présentes (Backlog, Todo, Done)
• Pas de cartes malformées (ligne - [ ] sans description)

Problèmes :

• docs/todo.md absent en mode obsidian → MISSING
• kanban-plugin: board absent → INVALID (avec --fix : ajouter le frontmatter minimal)
• Colonnes manquantes → INCOMPLETE (avec --fix : ajouter ## Backlog, ## Todo, ## Done vides)

En mode faru : vérifier que docs/todo.md n'existe pas (ou est un fichier legacy bridgé) — signaler si présent et incohérent avec le mode.

---

Phase 3 : Vérification CLAUDE.md

Vérifier la présence des sections minimales :

Section requise	Pattern
Project Overview	## Project Overview ou ## Vue d'ensemble
Essential Commands	## Essential Commands ou ## Commandes
Agent System	## Agent System ou ## Agents

grep -c "^## " CLAUDE.md 2>/dev/null

Problèmes :

• CLAUDE.md absent → MISSING (critique — ne pas créer automatiquement, signaler uniquement)
• Section manquante → INCOMPLETE (avec --fix : ajouter un stub minimal en fin de fichier)

---

Phase 4 : Détection des liens morts

Wikilinks Obsidian [[Nom]]

grep -rh '\[\[.*\]\]' docs/ --include="*.md" 2>/dev/null \
  | grep -oP '(?<=\[\[)[^\]|]+' | sort -u

Pour chaque wikilink trouvé, vérifier qu'un fichier correspondant existe dans docs/ (nom ≈ slug normalisé).

Références d'agents dans CLAUDE.md

grep -oE '\b[0-9]{2}-[a-z-]+\b' CLAUDE.md | sort -u

Pour chaque référence NN-nom, vérifier que framework/agents/**/NN-nom.md existe.

Fichiers mentionnés dans CLAUDE.md (@, backtick paths)

grep -oP '`[^`]+\.(md|json|sh|go|ts|cjs)`' CLAUDE.md | tr -d '`' | sort -u

Vérifier que chaque chemin existe dans le repo.

Problèmes :

• Wikilink mort → DEAD_LINK (path, lien)
• Agent référencé inexistant → MISSING_AGENT (NN-nom)
• Fichier mentionné introuvable → MISSING_FILE (path)

---

Format de rapport

## doc-reset — Rapport [YYYY-MM-DD]
Mode : faru | obsidian
Projet : [nom du dossier]

### Phase 1 — Spec/Backlog
✅ OK — N cartes valides  |  ❌ MISSING docs/backlog/  |  ⚠️ N cartes INVALID

### Phase 2 — todo.md
✅ OK — format kanban valide  |  ⚠️ INCOMPLETE — colonnes manquantes  |  N/A (mode faru)

### Phase 3 — CLAUDE.md
✅ OK — sections présentes  |  ⚠️ INCOMPLETE — section manquante : [nom]  |  ❌ MISSING

### Phase 4 — Liens morts
✅ Aucun lien mort  |  ⚠️ N problèmes détectés :
  - DEAD_LINK docs/spec.md → [[Agent inexistant]]
  - MISSING_AGENT 42-unknown
  - MISSING_FILE framework/tools/inexistant.sh

---
Résumé : N erreurs ❌ · N avertissements ⚠️
[Si --fix] : N corrections appliquées · N nécessitent intervention manuelle

---

Mode --fix — Corrections automatiques

Problème	Correction automatique
docs/backlog/ absent	mkdir -p docs/backlog/
todo.md sans kanban-plugin: board	Ajouter frontmatter minimal
todo.md sans colonnes de base	Ajouter ## Backlog, ## Todo, ## Done
CLAUDE.md section manquante	Ajouter stub ## [Section]\n\n_À compléter._ en fin de fichier
Lien mort wikilink	Signaler uniquement (pas de création de fichier fantôme)
Agent référencé inexistant	Signaler uniquement (la décision appartient à l'humain)

Règle : --fix n'invente pas de contenu. Il crée des structures minimales valides et signale ce qui nécessite une décision humaine.

---

Complémentarité

Agent	Rôle distinct
strange (16)	Reconstruit toute la documentation depuis le code (reverse doc) — doc-reset vérifie et répare l'existant
shuri (01)	Génère spec et todo depuis zéro — doc-reset audite leur conformité après coup
robocop (11)	Répare les erreurs de build/CI — doc-reset répare la documentation
godspeed (00)	Diagnostic projet (état, stack, tâches) — doc-reset se concentre uniquement sur la doc

---

Règles

1. Scope minimal : ne corriger que ce qui est structurellement invalide. Ne pas réécrire du contenu.
2. Mode --fix non-destructif : jamais de suppression de fichier existant.
3. Signaler clairement : chaque problème cite le fichier et la ligne si possible.
4. CLAUDE.md sacré : ne jamais créer CLAUDE.md automatiquement — signaler uniquement si absent.