Mermaid Flowchart Builder

---
name: mermaid-flowchart-builder
description: Use when generating a Mermaid flowchart for a process or decision flow. Triggers on "flowchart", "process diagram", "Mermaid graph", "draw the flow", or pasted process steps.
---

# Mermaid Flowchart Builder

Generate a Mermaid `graph` diagram that a reader can grok in under 10 seconds. Most process diagrams fail by trying to capture every edge case in one chart — be ruthless about scope. If it doesn't fit, split it.

## Required inputs

1. **The process or decision flow** — prose, bullets, or a verbal description
2. **Direction preference** — top-down (`TD`) for hierarchies and short flows, left-right (`LR`) for pipelines and timelines
3. **Audience** — engineers tolerate denser charts; execs want 5-7 nodes max
4. **Start and end states** — every flow needs a clear entry and at least one terminal node

If the user describes a flow with more than ~15 logical steps, push back: "This will be unreadable as one chart. Want me to split it into [proposed sub-flows]?"

## Mermaid syntax to use

Default to `graph TD` (top-down). Use rectangles for actions, diamonds for decisions, rounded boxes or stadiums for start/end states. Label every edge that comes out of a decision diamond — unlabeled branches are the #1 readability killer.

\`\`\`mermaid
graph TD
    Start([Refund request received]) --> Check{Within 30 days?}
    Check -->|No| Deny[Deny + send policy link]
    Check -->|Yes| Amount{Under $50?}
    Amount -->|Yes| Auto[Auto-approve]
    Amount -->|No| Manager[Manager review]
    Manager --> Decision{Approved?}
    Decision -->|Yes| Auto
    Decision -->|No| Deny
    Auto --> End([Refund issued])
    Deny --> End2([Case closed])
\`\`\`

Use `classDef` to color terminal states (green for success, red for denial) when the audience benefits — but skip it for short charts where one accent feels overdesigned.

## Layout principles

- **One concept per node.** If a node label needs "and" twice, split it.
- **Decisions are diamonds, actions are rectangles.** Don't mix.
- **Label every decision branch** with the answer (Yes/No/Approved/Rejected) — the diamond itself is the question.
- **Terminal states are stadiums** `([...])` — visually distinct from intermediate steps.
- **Direction matches reading order.** TD for "first do A, then B." LR for pipelines that imply time flowing left to right.
- **Keep edge labels short** (1-3 words). If you need a sentence, the decision is too complex — split it.

## Anti-patterns

- **50 boxes in one chart** — anything over 15 nodes is unreadable. Split by phase or by actor.
- **Crossing edges everywhere** — usually means the direction is wrong. Try `LR` instead of `TD`.
- **Decision diamonds with 4+ branches** — refactor into nested decisions or a lookup table.
- **No terminal node** — every path must end. "TBD" is not an end state; "Escalate to legal" is.
- **Mermaid colors used decoratively** — color encodes meaning (success/failure/external) or it's noise.

## Rendering hints

- **GitHub, Notion, Slack, Obsidian** render Mermaid natively in markdown code fences. Just paste.
- **Mermaid Live Editor** (mermaid.live) for interactive editing and PNG/SVG export.
- **mermaid.ink** for embedding as an image URL in tools that don't render Mermaid: `https://mermaid.ink/img/<base64>`.

## Output

Return the Mermaid block in a ```mermaid code fence, plus a 1-line summary of what the chart shows and the node count. If you split into multiple charts, label each one and explain the split.