Skill Entscheidungsflussdiagramm-Generator
Liest eine SKILL.md, extrahiert strukturierte Daten nodes.json und generiert deterministisch ein Flussdiagramm als HTML.
Arbeitsteilung
| Phase | Wer | Warum |
|---|---|---|
| SKILL.md → nodes.json | KI | SKILL.md ist natürliche Sprache, semantisch instabil, die KI versteht den Kontext |
| nodes.json → HTML | Script | Koordinatenberechnung muss deterministisch, reproduzierbar und pixelgenau sein |
Die KI gibt nur strukturierte Daten aus, niemals Koordinaten oder SVG; das Script macht nur Geometrie, niemals Semantik.
Ausführungsschritte
1. SKILL.md lesen
Liest die vom Benutzer angegebene SKILL.md. Falls nicht gefunden, fragt es nach dem Pfad.
2. KI extrahiert nodes.json
Gibt JSON nach folgendem Schema aus. Jede ausgehende Kante muss explizit das Feld side enthalten – dies ist die semantische Entscheidung der KI, das Script rät nicht.
Top-Level-Struktur
{
"title": "Skill-Name",
"subtitle": "Optionale Beschreibung",
"nodes": [ ... ],
"edges": [ ... ],
"loops": [ ... ],
"legend": [ ... ]
}
nodes: Pflicht, Knoten-Arrayedges: Pflicht, Array gerichteter Kantenloops: Optional, Rückkopplungsschleifen gestrichelt (siehe unten)legend: Üblich[](leer), Standardlegende wird verwendet
Knoten type
| type | Bedeutung | Form |
|---|---|---|
entry | Startpunkt | Abgerundetes Rechteck |
decision | Entscheidungspunkt (Ja/Nein, Vorhanden/Nicht vorhanden) | Raute |
process | Verarbeitungsschritt | Abgerundetes Rechteck |
output | Bericht/Datei-Ausgabe | Abgerundetes Rechteck |
terminal | Beenden/Fehler-Abbruch | Abgerundetes Rechteck |
Knoten role (Farbgebung)
| role | Bedeutung | fill / stroke |
|---|---|---|
ai | KI-Schlussfolgerung / LLM-Aufruf | #E6F1FB / #185FA5 |
output | Bericht / Datei-Ausgabe | #EEEDFE / #534AB7 |
decision | Entscheidungspunkt | #FAEEDA / #854F0B |
script | Skriptausführung | #E1F5EE / #0F6E56 |
terminal | Beenden / Fehler | #FCEBEB / #A32D2D |
Ein Knoten darf nur eine role haben. Enthält ein Schritt Arbeiten unterschiedlicher Art (entsprechend verschiedenen roles), muss er in mehrere Knoten aufgeteilt werden. Beispielsweise kann „Script holt Basis + KI ergänzt Analyse“ nicht zu einem Knoten mit role=ai zusammengefasst werden, sondern muss in Knoten mit role=script und role=ai aufgeteilt werden.
Kanten side (entscheidend!)
| side | Bedeutung | Layout-Verhalten |
|---|---|---|
bottom | Hauptfluss nach unten | Ziel in nächster Ebene, cx wird von Quelle geerbt |
left | Linker Ast der Entscheidung / Abzweigung links | Entscheidung → gleiche Ebene horizontal; Normal → nächste Ebene orthogonale Knicklinie |
right | Rechter Ast der Entscheidung / Abzweigung rechts | Wie links, umgekehrte Richtung |
Die semantische Entscheidung von side wird von der KI getroffen:
- Entscheidungsrauten (type=decision) mit
left/right→ gleiche Ebene wie die Quelle, horizontale Linie - Normale Rechtecke (type=process/output) mit
left/right→ nächste Ebene, orthogonale Knicklinie (senkrecht → waagerecht → senkrecht, keine Diagonalen)
loops (Rückkopplungsschleifen, optional, gestrichelt)
Werden verwendet, wenn der Fluss zu einem vorherigen Schritt zurückkehrt, z. B.:
- Nach Reparatur erneut prüfen (
apply_fix → entry) - Wiederholen (
retry → checkpoint) - Schleife bis Bedingung erfüllt (
recheck → validate)
{ "from": "apply_fix", "to": "entry", "label": "Nach Reparatur erneut prüfen", "path": "left_edge" }
Feldbeschreibung:
from: Startknoten der Schleife (meist der letzte Schritt)to: Zielknoten der Schleife (meist der Startpunkt oder ein Prüfpunkt)label: Bezeichnung der Schleife, wird neben der gestrichelten Linie angezeigtpath: Fest auf"left_edge"(Routing entlang des linken Randes)
Hinweis:
- Zwischen Start und Ziel der Schleife darf in edges keine weitere Kante gezeichnet werden, sonst kommt es zu doppelter Darstellung
- Knoten in loops from/to nehmen nicht an der depth-Berechnung teil
legend
Üblich leer [], das Script verwendet die standardmäßige 5-Farben-Legende. Für benutzerdefinierte Legende:
[
{ "label": "KI-Ausführung", "fill": "#E6F1FB", "stroke": "#185FA5" },
{ "label": "Ausgabe/Bericht", "fill": "#EEEDFE", "stroke": "#534AB7" },
{ "label": "Entscheidungspunkt", "fill": "#FAEEDA", "stroke": "#854F0B" },
{ "label": "Script", "fill": "#E1F5EE", "stroke": "#0F6E56" },
{ "label": "Beenden", "fill": "#FCEBEB", "stroke": "#A32D2D" }
]
3. Script aufrufen, HTML generieren
python3 <skill_verzeichnis>/scripts/flowchart.py <nodes.json> --out docs/decision-flowchart.html
Das Script wird:
- id-Eindeutigkeit, Gültigkeit von side/type/role sowie Gültigkeit von from/to-Referenzen prüfen
- Ebenen automatisch berechnen (Seitenäste der Entscheidung gleiche Ebene / normale Abzweigungen nächste Ebene / Zusammenführung = max( eingehende Kanten ) + 1)
- x (durch side bestimmt) und y (nach Ebene + Knotenhöhe) automatisch berechnen
- Verbindungslinien rendern (horizontale Seitenäste / orthogonale Knicklinien / vertikaler Hauptfluss / dreiteilige Zusammenführung / gestrichelte Rückkopplungsschleifen)
- viewBox automatisch + Legende unten
- Eigenständiges HTML ausgeben
nodes.json-Beispiele
docs/halucatch-v2-nodes.json— Vollständiges Beispiel (mit loop-Schleife, Dreifach-Verzweigung, Zusammenführung)docs/halucatch-nodes.json— Einfaches Beispieldocs/security-review-nodes.json— Beispiel mit mehreren Entscheidungspunktendocs/self-nodes.json— Minimalbeispiel (9 Knoten)
Checkliste zur Selbstprüfung
- Eintrittsknoten type=entry ganz oben
- Jede Kante hat das Feld side (bottom/left/right)
- Entscheidungsrauten mit side=left/right sind Seitenäste (gleiche Ebene, horizontale Linie)
- Normale Rechtecke mit side=left/right sind Abzweigungen (nächste Ebene, orthogonale Knicklinie)
- Ein Knoten, eine role; gemischte Schritte wurden aufgeteilt
- Zusammenführungspunkte (mehrere eingehende Kanten zum selben Knoten) benötigen keine spezielle Behandlung, das Script erkennt sie automatisch
- Rückkopplungsschleifen nutzen das Feld loops, nicht edges
- Alle Knoten-ids werden in from/to der Kanten referenziert (keine isolierten Knoten)
- Legende leer
[]
Häufige Fragen
F: Was tun, wenn sich Knoten überlappen?
Prüfen, ob das Feld side fehlt. Entscheidungszweige müssen side (left/right/bottom) haben, sonst erben die beiden Zielknoten dieselbe Position.
F: Die gestrichelte Rückkopplungsschleife wird nicht angezeigt?
Die Schleife muss im Array loops deklariert werden (nicht in edges), und from/to dürfen in edges nicht wiederholt werden. path ist fest auf "left_edge" gesetzt.
F: Das Script meldet JSON-Formatfehler? JSON unterstützt keine Kommentare und keine einfachen Anführungszeichen. Häufige Probleme: fehlende Kommas, überflüssige Kommas (am Array-Ende), einfache Anführungszeichen.
Weitere Fragen siehe docs/FAQ.md.