/understand-onboard

Générer un guide complet d'onboarding à partir du graphe de connaissance du projet.

Référence de la structure du graphe

Le graphe de connaissance JSON a cette structure :

• project — {name, description, languages, frameworks, analyzedAt, gitCommitHash}
• nodes[] — chacun a {id, type, name, filePath?, summary, tags[], complexity, languageNotes?}
  • Types de nœuds de code : file, function, class, module, concept
  • Types de nœuds non-code : config, document, service, table, endpoint, pipeline, schema, resource
  • Types de nœuds domaine/connaissance : domain, flow, step, article, entity, topic, claim, source
  • Les IDs utilisent le type de nœud comme préfixe, ex. file:path, function:path:name, config:path, article:path
• edges[] — chacune a {source, target, type, direction, weight}
  • Types clés : imports, contains, calls, depends_on, configures, documents, deploys, triggers, contains_flow, flow_step, related, cites
• layers[] — chacune a {id, name, description, nodeIds[]}
• tour[] — chacune a {order, title, description, nodeIds[]}

Comment lire efficacement

1. Utilisez Grep pour chercher dans le JSON les entrées pertinentes AVANT de lire le fichier complet
2. Ne lisez que les sections dont vous avez besoin — ne videz pas tout le graphe dans le contexte
3. Les noms de nœuds et les résumés sont les champs les plus utiles pour comprendre
4. Les edges vous disent comment les composants se connectent — suivez les imports et calls pour les chaînes de dépendances

Instructions

1. Résolvez le répertoire de données $UA_DIR. Exécutez UA_DIR=$([ -d .understand-anything ] && echo .understand-anything || echo .ua) — c'est l'héritage .understand-anything/ quand il existe déjà, sinon le nouveau .ua/. Vérifiez que $UA_DIR/knowledge-graph.json existe. Sinon, demandez à l'utilisateur d'exécuter /understand d'abord.

2. Vérifiez la fraîcheur du graphe avant d'utiliser le contexte dérivé du graphe :

   • Lisez project.gitCommitHash depuis les métadonnées du graphe comme GRAPH_COMMIT_RAW. Résolvez-le comme un commit avant de l'utiliser dans un diff Git, puis comparez-le avec git rev-parse HEAD et inspectez les modifications committed et working-tree du projet depuis la racine du projet :

     GRAPH_COMMIT=$(git rev-parse --verify --end-of-options "${GRAPH_COMMIT_RAW}^{commit}" 2>/dev/null)
     git rev-parse HEAD
     git diff --name-only "$GRAPH_COMMIT" HEAD -- .
     git diff --cached --name-only -- .
     git diff --name-only -- .
     git ls-files --others --exclude-standard -- .

   • Le pathspec -- . est requis : les commits qui ne touchent qu'un projet sibling monorepo ne doivent pas rendre ce graphe obsolète. Une discordance de hash seule n'est pas obsolète quand le diff du projet est vide.
   • Ignorez le répertoire de données sélectionné (.ua/ ou héritage .understand-anything/) dans la sortie de chaque commande car il contient des artefacts de graphe générés, pas la dérive du source du projet.
   • Si le diff committed ou une commande working-tree rapporte des fichiers du projet, avertissez avant de générer le guide que le contenu d'onboarding peut omettre ces changements. Suggérez : Exécutez /understand pour rafraîchir le graphe.
   • Exécutez le diff de commit uniquement quand GRAPH_COMMIT_RAW se résout avec succès. Si le commit du graphe ou les métadonnées Git sont manquants, invalides ou indisponibles, donnez un bref avertissement au mieux et continuez au lieu de bloquer.

3. Lisez les métadonnées du projet — utilisez Grep ou Read avec une limite de lignes pour extraire la section "project" (name, description, languages, frameworks).

4. Lisez les layers — Grep pour "layers" pour obtenir le tableau complet des layers. Ceux-ci définissent l'architecture et structureront le guide.

5. Lisez le tour — Grep pour "tour" pour obtenir les étapes de la visite guidée. Celles-ci fournissent le parcours d'apprentissage recommandé.

6. Lisez uniquement les nœuds structurels au niveau fichier — utilisez Grep pour trouver des nœuds avec des types au niveau fichier (file, config, document, service, pipeline, table, schema, resource, endpoint) dans le graphe de connaissance. Ignorez les nœuds au niveau fonction et au niveau classe pour garder le guide de haut niveau. Extrayez pour chaque nœud : name, filePath, summary, et complexity.

7. Identifiez les hotspots de complexité — à partir des nœuds au niveau fichier, trouvez ceux avec les plus hautes valeurs de complexity. Ce sont les domaines que les nouveaux développeurs doivent aborder avec prudence.

8. Générez le guide d'onboarding avec ces sections :

   • Aperçu du projet : name, languages, frameworks, description (depuis les métadonnées du projet)
   • Couches d'architecture : name, description et fichiers clés de chaque couche (depuis les layers + file nodes)
   • Concepts clés : patterns importants et décisions de conception (depuis les résumés de nœuds et les tags)
   • Visite guidée : procédure pas à pas (depuis la section tour)
   • Plan des fichiers : ce que fait chaque fichier clé (depuis les file-level nodes, organisés par layer)
   • Hotspots de complexité : domaines à aborder avec prudence (depuis les valeurs de complexity)

9. Formattez en markdown propre

10. Proposez de sauvegarder le guide dans docs/UA_ONBOARDING.md du projet

11. Suggérez à l'utilisateur de le committer au repo pour l'équipe