aelena/bpmnemonic

Was macht bpmnemonic?

bpmnemonic — BPMN + Eselsbrücke. Verwandle ein Prozessdiagramm in ein Dokument, das du tatsächlich lesen, durchsuchen und versionieren kannst. Denn niemand öffnet um 2 Uhr morgens eine .bpmn-Datei im Editor, aber jeder liest Markdown.

Warum es das gibt

BPMN-Dateien enthalten reichhaltige Semantik — Akteure, Entscheidungen, Ausnahmepfade, Datenflüsse, Nachrichtenaustausche — aber nur, wenn du einen Viewer geöffnet hast. Sobald du Folgendes tun musst:

• den Prozess in einem PR-Review diskutieren,
• Anforderungen an einen Auftragnehmer senden,
• einen neuen Entwickler einarbeiten,
• oder den Prozess an ein Sprachmodell verfüttern,

…wird das Diagramm zu einem Hindernis. Du brauchst Text. Er muss exakt mit dem Diagramm übereinstimmen. Und du willst ihn nicht jedes Mal von Hand schreiben, wenn sich das Diagramm ändert.

Dieses Skill kodiert die Übersetzung von der BPMN-Struktur in eine von zwei Markdown-Formen:

• specs.md — eine technische Spezifikation für Entwickler. Nummerierte Schritte, vollständige Abläufe, Datenverträge, Abnahmekriterien.
• prd.md — ein Produktanforderungsdokument für Stakeholder. Problemstellung, Akteure, Benutzerreise, Erfolgskennzahlen, Umfang.

Beide werden aus demselben Diagramm abgeleitet. Sie unterscheiden sich in Zielgruppe, Wortschatz und der Hervorhebung bestimmter BPMN-Elemente.

Aufruf

Auslöser	Verhalten
/bpmnemonic oder /bpmn-to-spec oder /flow-to-doc	Standard — Datei analysieren, Format erfragen, dann generieren
/bpmnemonic spec [Pfad]	specs.md aus der BPMN-Datei generieren
/bpmnemonic prd [Pfad]	prd.md aus der BPMN-Datei generieren
/bpmnemonic both [Pfad]	Beide Dokumente generieren
/bpmnemonic analyze [Pfad]	scripts/analyze-bpmn.sh ausführen und Elementanzahl + Komplexität melden
Natürliche Sprache: „Konvertiere dieses BPMN in eine Spezifikation“, „Erstelle ein PRD aus diesem Diagramm“, „Dokumentiere diesen Workflow“	Gleich

Stoppen / Deaktivieren

Nicht sitzungsbasiert. Einmalig pro Datei.

Die Übersetzungsanleitung (5 Schritte)

Schritt 1: Analysieren und erfassen

Die .bpmn-Datei lesen (es ist nur XML). Ein Inventar erstellen:

• Prozess-Name, ID und eventuelle Dokumentation
• Teilnehmer (bpmn:participant) — werden zu „Akteuren“ oder „externen Systemen“
• Bahnen (bpmn:lane innerhalb von bpmn:laneSet) — werden zu „Rollen“ oder „Verantwortlichkeiten“
• Aufgaben (bpmn:task, bpmn:userTask, bpmn:serviceTask, bpmn:sendTask, bpmn:receiveTask, bpmn:scriptTask, bpmn:businessRuleTask, bpmn:manualTask) — werden zu nummerierten Schritten
• Ereignisse (bpmn:startEvent, bpmn:endEvent, bpmn:intermediateThrowEvent, bpmn:intermediateCatchEvent, bpmn:boundaryEvent) — Auslöser, Beendigungen, Fehlerfänge, Zeitüberschreitungen
• Gateways (bpmn:exclusiveGateway, bpmn:parallelGateway, bpmn:inclusiveGateway, bpmn:eventBasedGateway) — Verzweigungspunkte
• Sequenzflüsse (bpmn:sequenceFlow) — die Pfeile
• Nachrichtenflüsse (bpmn:messageFlow) — Kommunikation zwischen Pools, Integrationspunkte
• Datenobjekte (bpmn:dataObject, bpmn:dataObjectReference) — Dokumente, Datensätze, Nutzlasten
• Unterprozesse (bpmn:subProcess, bpmn:callActivity) — verschachtelte Komplexität

Wenn scripts/analyze-bpmn.sh ausgeführt wird, erstellt es dieses Inventar automatisch.

Schritt 2: Die lineare Erzählung aufbauen (der Happy Path)

Die Sequenzflüsse von jedem Startereignis zu jedem Endereignis entlanggehen und den Pfad wählen, der an keinem Gateway abweicht (d. h. der Pfad mit der höchsten Erfolgswahrscheinlichkeit). Dies ist der „Happy Path“ — er wird das Rückgrat sowohl der Spezifikation als auch des PRD sein.

Formatiere ihn als nummerierte Schritte. Jeder Schritt benennt den Akteur (aus der Bahn) und die Aktion (aus dem Aufgabennamen).

Schritt 3: Verzweigen (alternative Abläufe)

Für jedes Gateway auf dem Happy Path werden die anderen Zweige zu alternativen Abläufen in der Spezifikation oder Randfällen im PRD. Nummeriere sie nach dem Hauptablauf.

Schritt 4: Ausnahmen abfangen

An Aufgaben angebundene Boundary Events (bpmn:boundaryEvent) — Fehlerereignisse, Timer-Ereignisse, Eskalationsereignisse — werden zu Ausnahmeabläufen. Diese fehlen oft im PRD, sind aber entscheidend für Spezifikationen.

Schritt 5: Kommunikation zwischen Pools identifizieren

Nachrichtenflüsse zwischen Pools werden zu Integrationspunkten. In der Spezifikation sind dies externe API-Verträge. Im PRD sind sie „dies hängt ab von“-Abschnitte.

Ausgabeformat auswählen

Wenn der Benutzer kein Format angibt, frage nach. Verwende andernfalls diese Heuristiken:

Diagramm hat...	Vorschlag
1 Pool, meist Benutzeraufgaben, < 10 Elemente insgesamt	PRD — klein genug für eine Funktionsbeschreibung
Mehrere Pools, Nachrichtenflüsse, Fehlerereignisse	specs.md — die Technik braucht die Details
Unterprozesse oder Call Activities	specs.md + empfehle, jeden Unterprozess separat zu übersetzen
Ein „Entscheidungstabellen“-Gateway (DMN)	beide — PRD beschreibt die Regel, die Spezifikation erfasst die Tabelle
Bei Unsicherheit	beide — sie verweisen aufeinander

Ausführungsablauf (Was Claude tut)

1. Lese die .bpmn-Datei (es ist XML — verwende das Read-Tool, dann analysieren mental oder via scripts/parse-bpmn.sh).
2. Erfasse die Elemente gemäß Schritt 1.
3. Schlage das Format vor, falls nicht angegeben. Hole Bestätigung.
4. Gehe den Happy Path entlang; baue die lineare Erzählung auf.
5. Identifiziere alternative Abläufe (Gateway-Verzweigungen), Ausnahmeabläufe (Boundary Events) und Integrationspunkte (Nachrichtenflüsse).
6. Rendere die gewählte Vorlage aus playbook/templates.md und fülle echte Inhalte ein.
7. Zeige dem Benutzer eine Vorschau vor dem Schreiben der Datei. Frage nach Bestätigung.
8. Schreibe nach ./specs.md und/oder ./prd.md. Wenn eine Datei existiert, zeige einen Diff und bestätige vor dem Überschreiben.

Sicherheitsvorkehrungen

• Nur-Lesen für die Quelle. Die .bpmn-Datei niemals ändern. Nur Markdown ausgeben.
• Original-IDs beibehalten. BPMN-Element-IDs als Kommentare im generierten Markdown referenzieren, damit zukünftige Aktualisierungen nachvollzogen werden können. (<!-- from bpmn:userTask id="UserTask_1a2b3c" -->)
• Niemals Abläufe erfinden. Wenn das Diagramm keinen Pfad zeigt, keinen schreiben. Wenn etwas mehrdeutig ist, stelle es als offene Frage im Dokument dar, anstatt zu raten.
• DMN-Tabellen nicht inline übersetzen, es sei denn, sie sind trivial klein. Auf sie verweisen, die Regel zusammenfassen und ein separates Entscheidungstabellen-Dokument empfehlen.
• Fehlende Elementnamen kennzeichnen. Eine bpmn:task id="Task_42" ohne name-Attribut ist ein Diagrammfehler. Gib sie im Output als [unbenannte Aufgabe — benötigt Bezeichnung] aus, anstatt einen Namen zu erfinden.
• Bestehende specs.md / prd.md niemals ohne Vorschau + Bestätigung überschreiben. Sie können manuelle Ergänzungen enthalten.

Dateien in diesem Skill

• SKILL.md — diese Datei
• playbook/elements.md — BPMN-Element-Referenz (was jedes Tag bedeutet)
• playbook/extraction.md — wie man eine .bpmn XML-Datei liest: Tagnamen, Attribute, Flussverfolgung
• playbook/templates.md — Zielstruktur für specs.md und prd.md
• playbook/pitfalls.md — häufige Fehler beim Erzählen eines Prozessdiagramms
• examples/01-approval.md — kleiner Ausgabengenehmigungsablauf → beide Ausgaben
• examples/02-loan.md — Kreditantrag mit mehreren Bahnen und Gateways → Spezifikation
• examples/03-errors.md — Auftragsabwicklung mit Timer-/Fehlerereignissen → Spezifikation
• scripts/analyze-bpmn.sh — BPMN-Elemente zählen, Komplexitätsbewertung geben
• scripts/parse-bpmn.sh — strukturierte Informationen aus einer .bpmn-Datei extrahieren (bestmöglich, verwendet xmlstarlet falls verfügbar)
• README.md — Installation + Schnellstart