process-diagram

/process-diagram

What it does

Produces a Mermaid diagram for a named workflow (the flow of /security-review, how a hook intercepts a Bash call, how the SessionStart bare-repo-nudge decision tree resolves, etc.) and optionally inserts it into a target markdown file between idempotent markers:

<!-- process-diagram:<name>:start -->

sequenceDiagram ...

<!-- process-diagram:<name>:end -->

Workflow

1. Parse arguments.
2. First positional arg: the workflow name (snake_case). Becomes the

diagram's identifier in the markers.

• --into <path>: target markdown file to insert into. If omitted,

just print the diagram to the user.

• --type sequence|flowchart: override the auto-pick. Default rule:

sequence diagrams for inter-component flows (actors talking to each other), flowcharts for decision logic / state transitions.

1. Resolve the workflow. Three sources, in order:
2. If a SKILL.md or command file with the workflow's name exists in

skills/ or commands/, Read it for the participants and steps.

• If the user describes the workflow in conversation, use that.
• Otherwise, ask the user for participants and the 3–10 steps. Do not

hallucinate a flow.

1. Generate the mermaid.
2. For sequenceDiagram: list participants first (participant U as User,

participant M as Main session, …), then the message arrows. Use ->> for sync, -->> for response, Note over for annotations.

• For flowchart: use flowchart LR (or TB if the user prefers).

Wrap labels containing special characters (parens, colons, slashes) in double quotes — Mermaid's parser bails on bare ones (per the known issue documented in docs/specs/research/research_visualization.md).

• Avoid Mermaid reserved IDs: end, class, subgraph. Pick

descriptive IDs (User, MainSession, SecurityReviewer).

1. Validate with mmdc if available.
2. Write the mermaid to a temp file (mktemp).
3. Run mmdc -i <tmp.mmd> -o <tmp.svg> 2>&1.
4. If non-zero: read the error message, fix the specific issue, retry.

Cap at 3 retries — if still failing, surface the mermaid + error to the user and let them decide.

• If mmdc is not on PATH: skip validation with a one-line warning.

1. Insert or print.
2. With --into <path>: scan the target for existing markers with the

same <name>. If found: Edit to replace the entire block atomically (both markers stay byte-identical, body changes). If not found: append after the first H1 heading.

• Without --into: print the fenced mermaid block to the user.

Examples

/process-diagram security-review
/process-diagram bare-repo-nudge --into hooks/README.md
/process-diagram stack-check-pipeline --type flowchart --into docs/specs/2026-05-24-pivot/05-stack-freshness.md

Hard rules

• Never overwrite content outside the markers. Idempotence is the

whole point of the markers.

• Never silently change marker IDs. If the user says

/process-diagram security-review and the existing block is <!-- process-diagram:security-flow:start -->, ask which one to update; do not duplicate.

• Refuse to invent a flow. If the user gives only a workflow name and

no description, and you cannot find a SKILL/command file to read for it, ASK for the participants and steps. Hallucinated diagrams are worse than no diagram.

• Cap retries at 3. If mmdc keeps complaining, surface to the user

rather than burning a context window on infinite tweak loops.

Common mermaid traps (and how to avoid)

| Failure | Fix | |---------|-----| | Label has (parens) and parser bails | Wrap label in "..." | | Label has : or / | Wrap label in "..." | | Node ID is end or class | Pick a different ID (e.g., EndNode) | | Arrow type mismatch (-->> in flowchart) | Sequence uses ->> / -->>; flowchart uses --> / -.-> | | Stale syntax (graph TB instead of flowchart TB) | Prefer flowchart for new diagrams |

What this skill does NOT do

• Generate diagrams from code AST. That's /repo-map territory

(architecture overview from directory structure + AGENTS.md hints), or dedicated tools (madge for JS/TS dep graphs).

• Auto-update existing diagrams when code changes. Run the skill

explicitly when the workflow shifts; the docs-sync skill can flag drift.