Générer documentation utilisateur finale avec Strange

Contexte

Vous avez un projet existant avec code mais documentation absente, obsolète ou fragmentaire. Strange analyse le code source pour produire 6 documents complets : spécification technique, documentation utilisateur, cahier des charges, user stories, glossaire et architecture.

Prérequis

• Projet existant avec code source (au moins 500 LOC)
• Accès Read complet sur le projet
• Pas de dépendance sur doc existante (Strange commence par le code)
• docs/rewrite/ directory sera créé par Strange

Étapes

1. Invocation reverse-documentation

Lancez Strange :

/ulk:strange

ou

Documente le projet à partir du code

Strange débute Phase 1 (Reconnaissance du code).

2. Phase 1 — Scan structurel

Strange exécute :

ls -la
find . -maxdepth 3 -type f | head -200
cat package.json 2>/dev/null
cat go.mod 2>/dev/null

Détecte :

• Language(s) et frameworks
• Patterns architecturaux
• Points d’entrée (main., index., app.*)
• Modèles de données
• Routes/API

3. Phase 2 — Cartographie des couches

Strange lit :

find . -name "*model*" -o -name "*entity*" -o -name "*dto*" -o -name "*service*" -o -name "*controller*" -o -name "*api*"

Comprend :

• Entités métier
• Services et business logic
• Routes et endpoints
• Intégrations externes

4. Phase 3 — Analyse des tests (si présents)

find . -name "*test*" -o -name "*spec*"

Utilise les tests comme spécification de comportement :

• Quels workflows les tests valident-ils ?
• Quels cas limites sont couverts ?

5. Phase 4 — Production des 6 documents

Strange génère dans docs/rewrite/ :

5a. Technical Spec (spec-technique.md)

# Spécification Technique

## Architecture générale
[Diagramme compris du code]

## Data Model
[Entités, relations, types]

## API Endpoints
[Routes, méthodes, schemas]

## Services et Workflows
[Logique métier, flows complexes]

## Stack & Dependencies
[Frameworks, librairies, versions]

## Testing Strategy
[Patterns observés dans les tests]

5b. User Guide (guide-utilisateur.md)

# Guide Utilisateur

## Getting Started
[Installation, setup initial]

## Features Principales
[Avec screenshots / exemples]

## Workflows Typiques
[Cas d'usage courants, step-by-step]

## FAQ & Troubleshooting
[Problèmes courants, solutions]

## Keyboard Shortcuts / CLI
[Commandes, hotkeys]

5c. Requirements (cahier-des-charges.md)

# Cahier des Charges

## Objectifs Métier
[Inférés du code et de l'architecture]

## Fonctionnalités Cibles
[Core features découvertes dans le code]

## Critères d'Acceptation
[Basés sur les tests existants]

## Contraintes & Limitations
[Découverts en lisant le code]

5d. User Stories (user-stories.md)

# User Stories

## Epic 1 : Authentication
- As a user, I want to sign up so that I can access the system
- As a user, I want to reset my password...

## Epic 2 : Dashboard
- As a user, I want to see my profile...

[Chaque story avec acceptance criteria depuis le code]

5e. Glossary (glossaire.md)

# Glossaire

**API** : Application Programming Interface — endpoints exposés par ce système

**DAO** : Data Access Object — couche d'accès à la base de données

**Provider** : (Riverpod en Flutter) gère l'état d'une feature

[Chaque terme extrait du code avec définition contextualisée]

5f. Architecture Diagram (architecture.md)

# Architecture

## Composants Principaux
[Identifiés du code]

┌─────────────────────────────────┐ │ Client (Web/Mobile) │ └────────────┬────────────────────┘ │ HTTP/REST │ ┌────────────▼────────────────────┐ │ API Gateway / Server │ │ (Express / Django / Go) │ └────────────┬────────────────────┘ │ ┌───────┴───────┐ │ │ ┌────▼────┐ ┌─────▼───┐ │Database │ │ Cache │ └─────────┘ └─────────┘

## Connexions Inter-Couches
[Explicités du code]

6. Comparaison avec doc existante (Phase 5)

Si docs/ existe, Strange compare :

=== Divergences Détectées ===

⚠️ CLAUDE.md dit "Database: MySQL"
   Code utilise "PostgreSQL"
   → Mettre à jour CLAUDE.md

✅ README.md correct sur installation
   Aligner avec rewrite/guide-utilisateur.md

❌ docs/spec.md absent
   → Utiliser docs/rewrite/spec-technique.md

7. Rapport final

Rapport Strange :

=== Reverse Documentation Complète ===

✅ Phase 1 (Code scan)      : Détecté Next.js + TypeScript + Prisma
✅ Phase 2 (Cartographie)   : 8 services, 24 endpoints, 12 entités
✅ Phase 3 (Tests)          : 145 test files (Jest, Playwright)
✅ Phase 4 (Génération)     : 6 documents produits
✅ Phase 5 (Comparaison)    : 3 divergences trouvées

📄 Fichiers générés dans docs/rewrite/ :
  - spec-technique.md         (4.2 KB, architecture détaillée)
  - guide-utilisateur.md      (3.1 KB, getting started + features)
  - cahier-des-charges.md     (2.8 KB, objectifs métier)
  - user-stories.md           (1.9 KB, 18 stories)
  - glossaire.md              (1.4 KB, 32 termes)
  - architecture.md           (2.5 KB, diagrammes ASCII)

⚠️ Divergences avec docs/ existante :
  [ ] CLAUDE.md: "Database: MySQL" vs code uses PostgreSQL (UPDATE)
  [ ] README.md: outdated install steps (REVIEW)
  [ ] docs/spec.md: absent, utiliser rewrite/ (REPLACE)

Prochaines étapes :
  1. Vérifier docs/rewrite/ (ajuster si nécessaire)
  2. Remplacer docs/ existante ou fusionner
  3. Committter nouveau docs/
  4. Utiliser shuri (01) pour sync CLAUDE.md

Variantes

• Variante A — Code-first uniquement : Mode analyze lance Phase 1-4 seulement (sans comparaison existante).
• Variante B — Feature-specific : Mode feature=auth documente seulement la couche authentification.
• Variante C — Legacy revival via blackemperor : blackemperor mode=legacy appelle Strange pour reconstituer doc avant refactoring.
• Variante D — Merge avec existing : Après Strange, utiliser Shuri pour fusionner rewrite/ dans docs/ canonical.

Agents enchaînés

Flux typique : strange (16) reverse-doc → shuri (01) harmonise + sync → blackemperor (18) mode=audit validation.

Troubleshooting

Symptôme	Cause probable	Résolution
Documents trop génériques	Peu de code ou patterns opaques	Augmenter context limit, ajouter comments dans code
User stories sans detail	Tests insuffisants	Ajouter plus de test cases avec descriptions
Architecture diagram incorrect	Dépendances cachées ou dynamiques	Relire code manuellement, corriger diagramme
Glossaire incomplet	Termes métier en variable/function names	Ajouter JSDoc/docstrings au code avant re-run

Voir aussi

• agents/docs/16-strange.md — agent complet
• agents/docs/01-shuri.md — sync + harmonisation post-strange
• agents/orchestrators/18-blackemperor.md — mode=legacy pour projets legacy
• docs/guides/use-cases/14-shuri-spec-to-kanban.md — après strange, utiliser shuri pour affiner