Unfold

Que fait Unfold ?

Produit une page HTML autonome : une vue d'ensemble qui se déplie, niveau par niveau, dans les parties d'un système. Le moteur (assets/template.html) dessine, dispose, zoome, trace et édite. Votre travail consiste à comprendre le code et à écrire les données du diagramme (JSON), afin qu'un lecteur qui ne connaît rien du projet puisse au final l'expliquer.

À chaque niveau, la page répond à trois questions : ce qui entre, ce qui lui arrive, ce qui sort.

Barre de qualité

• Précis. Chaque nœud et arête est appuyé par du code que vous avez réellement consulté. Sa source indique où : path/file.py:symbol. Marquez confidence sur chaque nœud : read, peeked ou inferred. Tout ce qui est inféré est listé à l'utilisateur.
• Adapté à la base de code. Utilisez le vocabulaire du projet (noms de modules, noms de topics et de routes textuellement) et le type de diagramme qui convient à chaque partie (voir étape 4).
• Discret. Les libellés font 2 à 4 mots, les légendes une ligne, les notes 1 à 3 phrases, et rien d'autre. Les détails sont à un clic ou un survol, jamais sur le canevas.
• Navigable depuis zéro. meta.summary dit en une phrase à quoi sert le système. Un court meta.glossary définit le jargon du projet. Les notes commencent par une phrase qui sert d'info-bulle au survol.

Flux de travail

1. Cadrer la demande

L'intention vient en premier : à quoi sert la carte. Elle définit le périmètre, la profondeur, les types de niveaux, la visite, les médias et le glossaire ; references/intents.md contient les valeurs par défaut pour chaque intention.

• Ne demandez pas quand l'invite le dit déjà. « Explique-moi ce projet » signifie apprendre. « Comment fonctionne la logique de réessai ? » signifie expliquer. « Que change cette PR ? » signifie examiner. « Je présente ça vendredi » signifie démontrer.
• Sinon, posez une question avant d'analyser, avec ces options : Apprendre la base de code, Démontrer mon travail, Expliquer un détail spécifique, Examiner une modification, ou Autre (documenter ou transmettre, déboguer un chemin, planifier un refactoring, auditer le flux de données).
• Puis posez au plus deux questions de suivi, choisies pour cette intention dans references/intents.md. Ignorez celles auxquelles la conversation a déjà répondu.
• Enregistrez la réponse comme meta.intent et meta.audience. Lors de l'extension d'une page existante, réutilisez son meta.intent sans redemander.

Ensuite, depuis la conversation ou dans le même court lot, déterminez :

• scope : quel dépôt ou quelle partie ;
• audience : nouveau développeur, relecteur, responsable ou conférence ;
• focus : la partie la plus importante, qui reçoit le plus de profondeur ;
• confidentialité : les pages sont partagées, alors omettez les hôtes, secrets, noms de clients et plans non divulgués sauf indication contraire.

S'il n'y a pas de code, travaillez à partir de la description de l'utilisateur. N'inventez jamais de parties, de flux ou de chiffres.

2. Lire la base de code par étapes, dans un budget

Les grands dépôts ne tiennent pas dans le contexte, et parcourir des fichiers entiers le gaspille. Lisez par étapes et arrêtez-vous dès que le diagramme est ancré.

Étape	Commande	Ce que vous obtenez	Coût
Carte	python scripts/scan_repo.py REPO [--section NAME]	langages, structure, manifestes, points d'entrée, signaux d'E/S avec file:line, imports entre parties, une liste à lire en premier	petit, plafonné par --budget
Forme	python scripts/scan_repo.py REPO --outline [PREFIX]	chaque classe et fonction, avec signature et première ligne de docstring, sans corps	moyen, plafonné par --budget
Preuve	python scripts/peek.py REPO file:line file:symbol ...	uniquement les lignes autour de chaque référence, fusionnées, dans un budget fixe de lignes et de tokens	petit par appel
Profondeur	lire les fichiers entiers	seulement les 3 à 8 fichiers qui portent la logique centrale dans le domaine d'intérêt de l'utilisateur	grand

Comment travailler à travers les étapes :

• Commencez par le README, la documentation et la Carte.
• Utilisez le Outline sur les dossiers qui comptent. Pour un grand dépôt, exécutez-le par partie de haut niveau plutôt que sur tout.
• Utilisez peek pour chaque signal d'E/S et point d'entrée que vous prévoyez de dessiner, et pour la fonction derrière chaque niveau de processus.
• Lisez les fichiers entiers uniquement là où la logique est vraiment complexe.
• Tenez une liste de preuves courante (nœud → file:symbol). Elle deviendra les champs source.
• L'analyse est basée sur des expressions régulières : elle manque les branchements dynamiques et remonte quelques faux positifs, comme les motifs dans les chaînes. Confirmez avec peek avant de dessiner.

Budget de tokens. Chaque commande se termine par son coût (≈N tokens). Ne dépensez que ce dont la carte a besoin :

• Ne lisez jamais un fichier entier avant son outline. Utilisez peek file:symbol, pas de larges plages de lignes, et regroupez les références en un seul appel peek.
• Une liste tronquée se termine par … N more; rerun with --section X. Ne la récupérez que si le diagramme en a besoin. Sur un gros dépôt, outlinez une partie à la fois avec --outline PREFIX.
• Arrêtez de lire dès que chaque nœud que vous prévoyez de dessiner a une source.
• Vérifiez avec unfold.py check et outline ; ne relisez pas le JSON ou la page. Corrigez diagram.json avec de petites modifications ; ne le réimprimez jamais en entier.

Coûts, cache d'analyse et ce qui est ignoré : references/reading-code.md (Budget de tokens).

3. Fixer la frontière du système

Listez les entrées (requêtes, topics souscrits, arguments CLI, fichiers lus, capteurs, configuration) et les sorties (réponses, topics publiés, fichiers écrits, commandes, écritures en BDD). Marquez-les avec "role": "input" ou "role": "output" à chaque niveau architecture et processus.

4. Choisir le diagramme pour chaque niveau

La vue d'ensemble est toujours architecture : 4 à 10 parties, stockages et externes, avec les entrées à gauche et les sorties à droite. Chaque partie qui mérite d'être ouverte reçoit le type enfant que son code appelle :

Le code à l'intérieur est…	type	Dessine
Plusieurs parties qui s'appellent ou s'envoient des messages	architecture	parties rounded, stockages cylinder, externes cloud
Une séquence d'étapes sur une entrée : un handler, pipeline, job ou algorithme	process	début/fin pill, étapes rect, décisions diamond avec branches étiquetées, boucles de retour en tireté
Une interaction entre parties dans le temps : un cycle de vie de requête, une poignée de main, un objectif d'action	sequence	participants comme nœuds de gauche à droite ; messages comme arêtes dans l'ordre ; en tireté pour les retours
Comportement piloté par des états et événements : machine d'état, gestionnaire de mode, connexion, statut d'arbre de comportement	state	marqueurs initial et final, états pill, arêtes étiquetées avec l'événement ou la garde
Structures de données, schémas, modèles ORM, définitions de messages	data	nœuds table avec fields ("id: int PK"), arêtes étiquetées avec la cardinalité
Classes et leurs relations : modèle objet, hiérarchie de plugins	class	nœuds class avec fields et methods ; arêtes avec rel (inherits, implements, composition, …)
Le système dans son monde : utilisateurs, systèmes voisins, la tech de chaque conteneur	c4	person pour les personnes, parties avec tech, externes cloud, groupes comme frontières
Ce qui tourne où : hôtes, dispositifs, clusters, conteneurs	deployment	machines node3d, groupes pour environnements, tech sur chacun
Imports de modules ou paquets	dependency	modules rect, arêtes de l'importateur vers l'importé
Un arbre de comportement (py_trees, BehaviorTree.CPP, Nav2)	behaviour	nœuds avec bt (sequence, selector, parallel, decorator, action, condition) ; arêtes parent → enfant dans l'ordre d'exécution
Une hiérarchie : arbre de config, menu, documentation, topics	tree	arêtes parent → enfant, dans l'ordre
Versions, migrations, ordre de démarrage ou de boot	timeline	nœuds dans l'ordre avec une date chacun

Allez plus loin là où le code le fait, et arrêtez-vous là où une note suffirait. N'ouvrez une partie que si son intérieur a 3 éléments significatifs ou plus. Gardez chaque niveau à environ 12 nœuds ; au-delà, imbriquez. references/reading-code.md contient des motifs pour les services web, ROS 2, pipelines, CLI, firmware, frontends et monorepos.

5. Ajouter des visuels là où le code en a

Si le dépôt contient des captures d'écran, des images d'architecture, des GIFs de démonstration ou des vidéos (regardez dans docs/, assets/ et le README), attachez-les avec "media": {"src": "relative/path.png", "caption": "…"}, ou une liste pour donner plusieurs médias à une partie. Tout nœud avec média affiche un badge miniature et ouvre un visualiseur ; un nœud avec "shape": "image" montre l'image sur le canevas. Pour démontrer, demandez à l'utilisateur des captures d'écran des parties que vous montrez.

unfold.py build intègre les fichiers locaux. Les pages publiées sur claude.ai bloquent les images distantes, alors préférez les fichiers locaux.

6. Écrire les mots

• meta.summary : une phrase sur ce que le système fait pour qui.
• meta.glossary : jusqu'à 8 termes du projet, chacun avec une définition de 10 mots ou moins.
• caption par niveau : une ligne sur le but, par ex. « Chaque objectif est vérifié pour son accessibilité avant que le bras ne bouge ».
• note sur un nœud : sa première phrase est affichée au survol, donc elle doit se suffire à elle-même ; jusqu'à deux phrases supplémentaires vont dans la carte de détail.
• Étiquettes d'arête : ce qui circule, en 1 à 3 mots.

7. Écrire une visite

Pour apprendre et démontrer (et quand la carte a plus de deux niveaux), ajoutez une entrée meta.tours : 5 à 9 étapes dans l'ordre qu'un développeur utiliserait pour l'expliquer, des entrées aux sorties. Chaque étape nomme un path (les identifiants de nœuds à ouvrir, depuis la vue d'ensemble) et optionnellement un node à mettre en avant, avec un title et une ou deux phrases de text. Pour démontrer, ajoutez des notes pour l'orateur. Pour apprendre, terminez par une étape quiz ({"q", "answer": node id, "explain"}). La page génère aussi une visite quand aucune n'est écrite, donc sautez cette étape pour une petite carte à un seul niveau.

8. Vérifier, revoir, construire

python scripts/unfold.py check   diagram.json     # les erreurs échouent ; lisez chaque avertissement
python scripts/unfold.py outline diagram.json     # tout l'arbre sur un écran
python scripts/unfold.py drift   diagram.json --repo REPO   # chaque source se résout toujours
python scripts/unfold.py build   diagram.json page.html --repo REPO   # fixe meta.repo au commit

Gardez une copie de ce que vous avez généré comme diagram.generated.json à côté de diagram.json ; le re-mapping en a besoin.

Lisez le plan comme si vous étiez le nouveau venu :

• Pouvez-vous expliquer le système à partir de lui ?
• Chaque niveau répond-il entrée → traitement → sortie ?
• Chaque enfant est-il du bon type ?

Si un outil d'automatisation de navigateur comme Playwright est disponible, prenez une capture d'écran de la vue d'ensemble et d'un niveau intérieur de chaque type, et corrigez les chevauchements ou croisements.

9. Livrer

Sur claude.ai avec l'outil Artifact, publiez page.html depuis /mnt/user-data/outputs/ avec capabilities: {"artifact": {}, "downloads": true}, ce qui active Sauvegarder et Exporter. Ailleurs, remettez le fichier ; il fonctionne hors ligne.

Puis dites à l'utilisateur, en quelques lignes :

• ce que montre la vue d'ensemble ;
• quelles parties sont inférées ;
• comment lire la page : cliquer pour ouvrir, survoler pour tracer, Échap ou zoom arrière pour revenir, / pour chercher, Visite ou T pour la visite guidée, P pour présenter, et Éditer pour modifier les choses ;
• que Exporter donne PNG, SVG, PDF, Mermaid, draw.io et Excalidraw, pour les diapos, README et autres outils.

Si l'utilisateur a ensuite modifié la page, continuez depuis python scripts/unfold.py extract page.html diagram.json, pas depuis votre ancienne copie.

Pour re-mapper après des changements de code, scannez avec --changed-since <meta.repo.commit>, mettez à jour une copie de diagram.generated.json avec les mêmes identifiants, puis unfold.py merge l'intègre dans la carte éditée pour que les modifications manuelles survivent. Étapes : references/reading-code.md (Re-mapping).

Référence

• references/intents.md : ce que chaque intention change, et ses questions de suivi.
• references/schema.md : chaque champ, type de niveau, forme et couleur.
• references/reading-code.md : transformer le code en niveaux, avec des motifs par écosystème.
• Ne modifiez pas assets/template.html pour un seul diagramme. Les changements du moteur appartiennent au dépôt, avec des tests.