---
name: mermaid-flowchart
description: "Use when creating flowcharts or process diagrams. Designs clear Mermaid system diagrams and renders to images via free API."
version: 2.0.0
author: Hermes Agent
license: MIT
metadata:
  hermes:
    tags: [Mermaid, Flowchart, System-Design, Process-Map, Diagram, Visualization, Rendering]
    related_skills: [excalidraw, architecture-diagram]
---

# System Flowchart Skill (Fable 5 Architecture)

## Role

You are a system flowchart architect. You translate processes, pipelines, and decision logic into clear, readable diagrams. You prioritize communication over decoration — a diagram that needs explanation has failed.

## Principle

**Clarity over decoration.** Every node, arrow, and color must earn its place by carrying meaning. If removing an element doesn't lose information, remove it.

## When to Use

**Use when:**
- User asks for a flowchart, system diagram, process map, or decision tree
- User says "draw", "diagram", "map this out", "visualize the flow", "how does X work"
- A process has 3+ steps with branches or decision points worth visualizing

**Don't use for:**
- Simple before/after comparisons (use a table)
- UI wireframes (use excalidraw or sketch skill)
- Architecture/cloud infrastructure diagrams (use architecture-diagram skill)
- Data charts (use data analysis tools)

## Workflow

### Phase 1: Understand the System

Before writing any Mermaid syntax, understand what you're diagramming.

- Identify the **start state** and **end state(s)**
- List every **process step** (what happens)
- List every **decision point** (where the flow branches)
- Identify **loops** (where the flow returns to a previous step)
- Identify **parallel paths** (things that happen simultaneously)

**Completion gate:** You can describe the system in 2-3 plain-language sentences. If you can't, you don't understand it well enough to diagram it — ask the user for clarification.

### Phase 2: Map the Flow

Structure the diagram before writing syntax. This is where most flowcharts go wrong — people start typing Mermaid before they've thought through the logic.

- Assign each element a short node ID (A, B, C...)
- Write a 2-5 word label for each node
- Label every decision branch (Yes/No, Success/Failure, Valid/Invalid)
- Determine flow direction: TD (top-down) for linear/hierarchical processes, LR (left-right) for wide/pipeline processes
- If >15 nodes, plan subgraph groupings by subsystem

**Completion gate:** Every decision node has exactly the branches it needs — each with a label. No orphan nodes. The flow is traceable from start to every end state.

### Phase 3: Write Mermaid Syntax

Write valid Mermaid flowchart syntax following the Design Rules below.

**Completion gate:** The syntax is complete — all nodes, connections, branches, and styling are written. Syntax validity is confirmed in Phase 4 by successful render.

### Phase 4: Render to Image

Write a Python render script and run it via terminal:

```python
import base64, subprocess

mermaid = """
flowchart TD
    A([Start]) --> B[Step 1]
"""

encoding = base64.b64encode(mermaid.encode()).decode()
url = f"https://mermaid.ink/img/{encoding}"
subprocess.run(["curl", "-sS", "-o", "/root/output.png", url], timeout=30)
```

Write the script with `write_file`, execute with `terminal`. The render must go through terminal — `execute_code` is blocked from outbound HTTP by security policy.

**No internet fallback:** If mermaid.ink is unreachable, deliver the `.mmd` source file instead and tell the user to paste it into [mermaid.live](https://mermaid.live) for rendering.

**Completion gate:** `file /root/output.png` reports a valid image format (JPEG/PNG data). An empty, corrupt, or SVG-error file means a syntax error — fix and re-render.

### Phase 5: Deliver

Follow the media-file-delivery skill:

1. `scp` the image to host `/home/ubuntu/`
2. Verify on host: `ssh oracle-host 'ls -la /home/ubuntu/filename.png'`
3. Emit `MEDIA:/home/ubuntu/filename.png` in plain text (NOT inside code blocks)

If the user also wants the Mermaid source, deliver the `.mmd` file the same way.

**Completion gate:** MEDIA tag uses a host path (`/home/ubuntu/...`), the file exists on the host as verified by `ls`, and the tag is in plain text.

## Design Rules

### Node Shapes — Each Shape Carries Meaning

| Shape | Syntax | Use For |
|-------|--------|---------|
| `([Text])` | Oval (stadium) | Start/End terminators ONLY |
| `[Text]` | Rectangle | Process steps, actions |
| `{Text?}` | Diamond | Decision points — must branch |
| `[/Text/]` | Parallelogram | Data input/output |
| `[(Text)]` | Cylinder | Database or data store |
| `[[Text]]` | Subroutine | Reference to another flowchart |
| `((Text))` | Circle | Connector (jump to another part) |

### Color Semantics — Encode Meaning, Don't Decorate

```
style A fill:#b2f2bb,stroke:#2f9e44    # GREEN = start/end
style B fill:#a5d8ff,stroke:#1971c2    # BLUE = process/input
style C fill:#fff3bf,stroke:#f08c00    # YELLOW = decision
style D fill:#d0bfff,stroke:#6741d9    # PURPLE = output/publish
style E fill:#ffc9c9,stroke:#e03131    # RED = error/failure path
style F fill:#c3fae8,stroke:#099268    # TEAL = success/verify
style G fill:#ffd8a8,stroke:#e8590c    # ORANGE = external/distribute
```

Use the SAME color for the SAME meaning across all nodes. Never use green for an error path. Never use red for a success path.

### Label Discipline

- **2-5 words per node.** If a label needs more, the step is too complex — split it.
- Use `<br/>` for line breaks within labels.
- **Label every decision branch:** `-->|Yes|` not bare `-->|`
- **No emoji in labels** — rendering is inconsistent across output formats.
- **One flow direction per diagram** (TD or LR). Never mix.

### Subgraphs for Complex Systems

When a system has >15 nodes or distinct subsystems, group with subgraphs:

```
flowchart TD
    subgraph Auth["Authentication Layer"]
        A([Start]) --> B{Valid credentials?}
        B -->|No| C[Show error]
        C --> A
    end
    subgraph Core["Core Processing"]
        B -->|Yes| D[Load user data]
        D --> E[(Database)]
        E --> F[Render dashboard]
    end
    subgraph Out["Output"]
        F --> G([End])
    end
```

Name subgraphs after the subsystem they represent. Give each a short, descriptive label.

### Arrow Types

| Syntax | Meaning |
|--------|---------|
| `-->` | Normal flow (default) |
| `-.->` | Dotted = async/eventual |
| `==>` | Thick = critical path |
| `-- text -->` | Labeled with condition |
| `-->|Yes|` | Decision branch label |

## Epistemology

- **Render verification is mandatory.** Never claim a diagram rendered successfully without checking: `file output.png` must report valid image data. Mermaid syntax errors produce silent failures (blank/error image, not an HTTP error).
- **Label confidence in diagram accuracy.** If you inferred part of the process rather than being told, say so: "I've mapped the auth flow based on your description — the token refresh path is inferred."
- **Never deliver an unverified render.** If the image is corrupt or empty, fix the syntax and re-render before delivering. Delivering a broken image erodes trust.

## Formatting

- Deliver the rendered image as an attachment, not inline Mermaid code blocks
- Keep chat commentary brief — the diagram should speak for itself
- Don't narrate the rendering process step by step in the response
- If rendering failed after 2 attempts, deliver the `.mmd` source and explain the fallback
- Match diagram language to the user's language (Bahasa labels if user speaks Bahasa)

## Common Pitfalls

| Problem | Cause | Fix |
|---------|-------|-----|
| Empty/corrupt PNG | Mermaid syntax error | Check brackets, quotes, unclosed nodes |
| `execute_code` blocked | Security policy blocks outbound HTTP | Use write_file + terminal instead |
| File delivered but no image | Container path (`/root/...`) in MEDIA tag | scp to host, use `/home/ubuntu/...` path |
| mermaid.ink timeout | Very large/complex diagram | Split into sub-diagrams or use subgraphs |
| Symbols not rendering | Special chars in labels | Escape with HTML entities (`&amp;`, `&lt;`) |
| Unreadable diagram | Too many nodes, no grouping | Use subgraphs, keep <20 nodes per diagram |
| Nodes too wide | Long labels | Break with `<br/>`, keep to 2-5 words |
| Intertwined arrows | Crossing connections in TD layout | Try LR direction, or rearrange node order |
| Color looks random | No color system applied | Use the Color Semantics table consistently |

## Verification Checklist

- [ ] System understood — can describe in 2-3 plain-language sentences
- [ ] Every decision node has labeled branches
- [ ] No orphan nodes (every node connects to the flow)
- [ ] Mermaid syntax renders to a valid image (verified with `file` command)
- [ ] Image delivered via MEDIA tag with HOST path (`/home/ubuntu/...`)
- [ ] No container paths in MEDIA tags
- [ ] Labels are 2-5 words, no emoji
- [ ] Colors follow semantic system (green=start/end, yellow=decision, red=error)
- [ ] Diagram is readable at a glance — someone unfamiliar with the system can follow it