Compétence Générateur de diagrammes de flux décisionnels
Lit un fichier SKILL.md, extrait les données structurées nodes.json, et génère de manière déterministe un diagramme de flux HTML via un script.
Répartition
| Étape | Qui fait | Pourquoi |
|---|---|---|
| SKILL.md → nodes.json | IA | SKILL.md est en langage naturel, la sémantique est instable ; l'IA comprend le contexte |
| nodes.json → HTML | Script | Les calculs de coordonnées doivent être déterministes, reproductibles et alignés sur les pixels |
L'IA ne produit que des données structurées, jamais de coordonnées ou de SVG ; le script ne fait que de la géométrie, il ne devine jamais la sémantique.
Étapes d'exécution
1. Lire SKILL.md
Lire le SKILL.md spécifié par l'utilisateur. S'il n'est pas trouvé, demander à l'utilisateur de fournir le chemin.
2. L'IA extrait nodes.json
Produire un JSON selon le schéma ci-dessous. Chaque arête sortante doit explicitement annoter le champ side — c'est le jugement sémantique de l'IA, le script ne le devine pas.
Structure racine
{
"title": "Nom de la compétence",
"subtitle": "Description optionnelle",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes: obligatoire, tableau de nœudsedges: obligatoire, tableau d'arêtes orientéesloops: optionnel, boucles de rétroaction en pointillés (voir ci-dessous)legend: généralement laissé vide[], utilise la légende par défaut
Type de nœud
| type | Signification | Forme |
|---|---|---|
entry | Point d'entrée du flux | Rectangle arrondi |
decision | Point de décision (oui/non, présent/absent) | Losange |
process | Étape de traitement | Rectangle arrondi |
output | Rapport / sortie de fichier | Rectangle arrondi |
terminal | Terminaison / sortie sur erreur | Rectangle arrondi |
Rôle du nœud (couleur)
| role | Signification | fill / stroke |
|---|---|---|
ai | Inférence IA / appel LLM | #E6F1FB / #185FA5 |
output | Rapport / sortie de fichier | #EEEDFE / #534AB7 |
decision | Point de décision | #FAEEDA / #854F0B |
script | Exécution de script | #E1F5EE / #0F6E56 |
terminal | Terminaison / erreur | #FCEBEB / #A32D2D |
Un nœud ne peut avoir qu'un seul rôle. Si une étape implique plusieurs types de travaux de nature différente (correspondant à des rôles différents), elle doit être divisée en plusieurs nœuds en série. Par exemple, « Script de récupération de base + analyse complémentaire par IA » ne peut pas être fusionné en un seul nœud role=ai ; il doit être divisé en un nœud role=script et un nœud role=ai.
Côté de l'arête (critique !)
| side | Signification | Comportement de mise en page |
|---|---|---|
bottom | Flux principal vers le bas | La cible est au niveau inférieur du from, cx hérité de from |
left | Branche gauche de décision / bifurcation gauche | Décision → même niveau, connexion horizontale ; Normal → niveau inférieur, ligne brisée orthogonale |
right | Branche droite de décision / bifurcation droite | Idem, direction opposée |
Le jugement sémantique de side est effectué par l'IA :
- Losange de décision (type=decision) avec
left/right→ même niveau que la décision, connexion horizontale - Rectangle normal (type=process/output) avec
left/right→ niveau inférieur, ligne brisée orthogonale (vertical → horizontal → vertical, pas de diagonale)
Boucles (loops, optionnel, pointillés)
Utilisé lorsqu'il y a une logique de « retour à une étape précédente », par exemple :
- Révision après correction (
apply_fix → entry) - Nouvelle tentative (
retry → checkpoint) - Boucle jusqu'à satisfaction de condition (
recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Révision après correction", "path": "left_edge" }
Description des champs :
from: ID du nœud de début de boucle (généralement la dernière étape)to: ID du nœud de fin de boucle (généralement le point d'entrée ou un point de contrôle)label: Étiquette de la boucle, affichée à côté des pointilléspath: fixé à"left_edge"(routage le long du bord gauche du diagramme)
Remarque :
- Ne pas dupliquer l'arête entre le début et la fin de la boucle dans
edges, sinon elle sera rendue deux fois - Les nœuds from/to dans
loopsne participent pas au calcul de la profondeur (depth)
Légende
Généralement laissée vide [], le script utilisera la légende par défaut à 5 couleurs. Pour une personnalisation :
[
{ "label": "Exécution IA", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "Sortie/Rapport", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "Point de décision", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "Script", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "Terminaison", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. Appeler le script pour générer le HTML
python3 <skill_dir>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
Le script va :
- Valider l'unicité des ID, la validité de side/type/role, et la validité des références from/to
- Calculer automatiquement les niveaux (branche latérale de décision au même niveau / bifurcation normale au niveau inférieur / point de jonction = max(arêtes entrantes)+1)
- Calculer automatiquement x (déterminé par side) et y (selon le niveau + hauteur du nœud)
- Rendre les connexions (branches latérales horizontales / lignes brisées orthogonales / flux principal vertical / jonction en trois segments / boucles en pointillés)
- Ajuster automatiquement le viewBox + légende en bas
- Produire un HTML autonome
Exemples de nodes.json
docs/halucatch-v2-nodes.json— Exemple complet (avec boucle loop, branchement à trois voies, point de jonction)docs/halucatch-nodes.json— Exemple de basedocs/security-review-nodes.json— Exemple avec plusieurs points de décisiondocs/self-nodes.json— Exemple minimal (9 nœuds)
Liste de vérification
- Le nœud d'entrée type=entry est tout en haut
- Chaque arête a un champ side (bottom/left/right)
- Les side=left/right d'un losange de décision sont des branches latérales (connexion horizontale au même niveau)
- Les side=left/right d'un rectangle normal sont des bifurcations (ligne brisée orthogonale au niveau inférieur)
- Un seul rôle par nœud, les étapes mixtes ont été divisées
- Les points de jonction (plusieurs arêtes entrantes vers le même nœud) n'ont pas besoin de traitement spécial, le script les reconnaît automatiquement
- Les boucles sont déclarées dans le champ loops, pas dupliquées dans edges
- Tous les ID de nœuds sont référencés dans les from/to des edges (pas de nœud isolé)
- Légende laissée vide
[]
Questions fréquentes
Q : Que faire si les nœuds se chevauchent ?
Vérifiez si le champ side manque. Les branches de décision doivent avoir un side (left/right/bottom), sinon les deux nœuds cibles hériteront de la même position.
Q : La boucle en pointillés ne s'affiche pas ?
Les boucles sont déclarées dans le tableau loops (pas dans edges), et les nœuds from/to ne doivent pas être dupliqués dans edges. Le path est fixé à "left_edge".
Q : Le script signale une erreur de format JSON ? Le JSON ne supporte pas les commentaires ni les guillemets simples. Problèmes courants : virgules manquantes, virgules supplémentaires (en fin de tableau), guillemets simples.
Pour plus de questions, voir docs/FAQ.md.