mermaid-helper

name	mermaid-helper
description	USE WHEN the user wants to draw an architecture diagram, sequence diagram, flowchart, ER diagram, or state machine. Picks the right mermaid type, writes correct syntax, validates before returning.

mermaid-helper — draw the right diagram in mermaid

Pick the right diagram type

Want to show	Use
Box-and-arrow architecture	flowchart TD
Who calls whom across time	sequenceDiagram
Step-by-step process	flowchart LR
Entity relationships (DB schema)	erDiagram
State transitions	stateDiagram-v2
Class structure	classDiagram
Gantt / project timeline	gantt
Pie chart of percentages	pie title …
Git branch flow	gitGraph

If unsure, default to flowchart TD (top-down) for static structure and sequenceDiagram for temporal interactions.

Common gotchas

• Spaces in node names must be quoted: A["Order Service"], not A[Order Service] (the latter works but breaks if the label has punctuation).
• HTML in labels needs & escapes: A & B → A & B.
• Edge labels: A -->|publishes event| B, the pipes are required.
• Subgraphs need explicit end: subgraph X\n A\n B\nend.
• classDef for styling: classDef warn fill:#fee,stroke:#900; then class A,B warn;.
• Sequence diagrams: use participant A as Alice to give friendly names; use Note over A: text for inline annotations.

Validation checklist (before returning)

• Every opening [ ( { has a matching close
• Every subgraph has a corresponding end
• Arrow syntax is consistent (-->, ---, ==>, -.->)
• Quoted labels for anything with spaces, parentheses, or special chars
• First line declares the diagram type

Output

Return a fenced mermaid block:

```mermaid
flowchart TD
  …
```

After the diagram, one short paragraph explaining the key flow. Skip the explanation if the diagram is trivial.

Anti-patterns

• Don't make a flowchart with 50 nodes — split into multiple diagrams
• Don't use ASCII art "diagrams" inside the mermaid block
• Don't add color for decoration; only when it carries meaning
• Don't write a sequence diagram for static structure