Mermaid Diagrams

Try it: /pm-skills:utility-mermaid-diagrams "Your context here"

Create effective, syntactically valid mermaid diagrams for product documents.

When to Use

Creating mermaid diagrams for PRDs, specs, roadmaps, or stakeholder presentations
Choosing which of 15 diagram types fits a specific communication need
Debugging mermaid code that won’t render or renders incorrectly
Reviewing diagrams for clarity, accuracy, and accessibility

When NOT to Use

Exporting diagrams to image files (PNG/SVG) - that’s a rendering tool concern
Using non-mermaid diagramming tools (Figma, Lucidchart, draw.io)
Creating purely decorative visuals with no informational purpose
Producing a full customer-journey artifact (stages, touchpoints, emotional curve, pain points) rather than a standalone diagram - use discover-journey-map, which composes this skill for its timeline or flowchart section

How to Use

Invoke the skill by name (/pm-skills:utility-mermaid-diagrams on Claude Code, $utility-mermaid-diagrams on Codex):

/pm-skills:utility-mermaid-diagrams "Your context here"

Or reference the skill file directly: skills/utility-mermaid-diagrams/SKILL.md

Instructions

Identify what you’re communicating - What relationship, flow, hierarchy, or proportion needs to be visible? Who is the audience?
Apply the cardinal rule - Confirm a diagram adds value over a list or table
Select a diagram type - Use the selection guide above, browse references/pm-use-cases.md by task, or browse references/diagram-catalog.md by type
Plan the diagram - Fill out the planning worksheet in references/TEMPLATE.md: purpose, audience, node inventory, type rationale
Write the mermaid code - Follow references/syntax-guide.md rules; start with the minimal syntax example from references/diagram-catalog.md and expand
Validate - Run through the quality checklist below
Embed - Place the validated mermaid code block in your document

The Cardinal Rule

Don’t diagram what a list can say.

Diagrams earn their place when they reveal relationships, branching, or flow that prose flattens. Before creating any diagram, ask:

Does this show branching, relationships, or flow that a list or table would flatten?

Yes → proceed with a diagram
No → use a numbered list, bullet list, or table instead

A 5-step linear process is a list. A 5-step process with two decision points and a retry loop is a diagram.

Diagram Selection Guide

I need to show…	Use	Also consider
A decision or approval process	Flowchart	State
Multi-service or multi-party interactions	Sequence	Flowchart
Feature lifecycle or status transitions	State	Flowchart
Work stages or pipeline status	Kanban	State
Release or sprint timeline with dependencies	Gantt	Timeline
Version history or chronological milestones	Timeline	Gantt
2D prioritization (effort/impact, risk/value)	Quadrant	-
Allocation breakdown or composition	Pie	Treemap
Problem decomposition or brainstorming	Mindmap	-
Domain models or data relationships	ER	Class
API or object contracts	Class	ER
System topology or infrastructure	Architecture	Flowchart
Flow quantities or budget allocation	Sankey	Pie
Hierarchical proportional data	Treemap	Pie
Trends or time-series metrics	XY-Chart	-

For worked examples organized by PM task, see references/pm-use-cases.md. For full syntax and options per type, see references/diagram-catalog.md.

Syntax Validity Principles

Six rules that prevent most rendering failures:

Quote labels - Any label containing spaces, parentheses, brackets, colons, commas, or reserved words must be quoted with double quotes
Escape special characters - Characters with mermaid or markdown meaning (>, <, - at line start, #) need escaping or quoting
Declare before referencing - Define a node before using it in an edge; referencing an undeclared node causes silent failures in some types
Respect limits - Each diagram type has a maximum node/participant count beyond which readability collapses (see references/diagram-catalog.md for per-type limits)
Comment your intent - Use %% comments to document non-obvious choices (why this layout direction, why this grouping)
Test before shipping - Paste into a mermaid renderer (mermaid.live, VS Code preview, or your target environment) and verify it renders correctly

For the complete syntax reference, see references/syntax-guide.md.

Output Contract

Planning artifact: A completed diagram planning worksheet (references/TEMPLATE.md)
Final output: A syntactically valid mermaid code block embedded in the target document
Quality gate: All items in the quality checklist pass

References

File	Purpose
`references/TEMPLATE.md`	Diagram planning worksheet - fill out before writing mermaid code
`references/EXAMPLE.md`	Worked example: PM creating 4 diagrams for a product launch
`references/diagram-catalog.md`	All 15 diagram types: syntax, PM examples, limits, pitfalls
`references/pm-use-cases.md`	PM task → diagram type mapping with mini worked examples
`references/syntax-guide.md`	Complete syntax validity rules, escaping, styling, and validation checklist

Output Template

Mermaid Diagram Planning Worksheet

1. Diagram Purpose

What I’m showing: Audience: Where this will appear:

2. Cardinal Rule Check

This shows branching, relationships, or flow that a list would flatten
A numbered list or table would NOT communicate this more clearly

If both boxes are not checked, use a list or table instead.

3. Diagram Type Selection

Selected type: Why this type: Considered alternatives:

4. Node Inventory

Node/Entity	Role/Label	Notes

Total node count: ___ (check against type limit in diagram-catalog.md)

5. Draft Mermaid Code

%% MEANING: [Why this diagram exists]
%% Type: [selected type]
%% Direction: [TD/LR/BT/RL if applicable]

6. Validation Checklist

Example Output

Worked Example: Diagrams for Pulse Analytics v2.0 Launch

This example walks through four diagrams a PM would create while preparing Pulse Analytics v2.0 for launch. Each diagram follows the planning worksheet from TEMPLATE.md before writing any mermaid code.

Example 1: Flowchart — Feature Approval Workflow

Context: The PRD needs a visual showing how new feature requests move through the approval process. Stakeholders keep asking “what happens after I submit a request?” and a text description has not stuck.

Filled Worksheet

What I’m showing: The decision path a feature request follows from submission to approval, deferral, or rejection. Audience: Engineering leads and business stakeholders reading the PRD. Where this will appear: Pulse Analytics v2.0 PRD, “Process” section.

Cardinal Rule Check:

This shows branching, relationships, or flow that a list would flatten
A numbered list or table would NOT communicate this more clearly

There are two decision points (strategic fit, feasibility) and a retry loop (spike). A list would hide the branching.

Selected type: Flowchart Why this type: Multiple decision diamonds with branching outcomes — flowcharts are built for this. Considered alternatives: State diagram (possible, but the focus is on the process, not lifecycle states).

Node Inventory:

Node/Entity	Role/Label	Notes
request	New Feature Request	Entry point
strategic	Strategic Fit?	Decision diamond
feasibility	Engineering Feasibility?	Decision diamond
scoring	Priority Scoring	Process step
approved	Approved	Terminal — goes to backlog
deferred	Deferred	Terminal
spike	Spike Scheduled	Loops back to feasibility
rejected	Rejected with Rationale	Terminal

Total node count: 8 (within flowchart limit of 12)

Resulting Diagram

%% MEANING: Feature approval workflow for Pulse Analytics v2.0 PRD
flowchart TD
    request["New Feature Request"]
    strategic{"Strategic Fit?"}
    feasibility{"Engineering Feasibility?"}
    scoring["Priority Scoring"]
    approved["Approved"]
    deferred["Deferred"]
    spike["Spike Scheduled"]
    rejected["Rejected with Rationale"]

    request --> strategic
    strategic -- "Yes" --> feasibility
    strategic -- "No" --> rejected

    subgraph review ["Review Phase"]
        feasibility -- "Feasible" --> scoring
        feasibility -- "Needs Spike" --> spike
        spike -- "Re-evaluate" --> feasibility
    end

    feasibility -- "Not Feasible" --> rejected
    scoring -- "High Priority" --> approved
    scoring -- "Low Priority" --> deferred

What this communicates: The diagram reveals that feature approval is not a straight line — it has two independent gates (strategic and technical) and a retry loop for spikes. Stakeholders can immediately see that “needs spike” is not a rejection, it feeds back into the process. This branching structure would collapse into ambiguity in a numbered list.

Example 2: Gantt — Launch Timeline

Context: The roadmap presentation needs a timeline showing the 8-week path to GA release, with dependencies visible so leadership can see which delays would cascade.

Filled Worksheet

What I’m showing: The 8-week launch timeline for Pulse Analytics v2.0 with task dependencies and critical path. Audience: Leadership team and cross-functional partners in the roadmap review. Where this will appear: Roadmap deck, “Timeline” slide.

Cardinal Rule Check:

This shows branching, relationships, or flow that a list would flatten
A numbered list or table would NOT communicate this more clearly

Parallel tracks (dev, QA, launch) with dependencies between them — a list cannot show which tasks block others.

Selected type: Gantt Why this type: Time-based schedule with parallel tracks and dependencies. Gantt charts are purpose-built for this. Considered alternatives: Timeline (good for milestones, but does not show task duration or dependencies).

Node Inventory:

Node/Entity	Role/Label	Notes
backend	Backend API	3 weeks
frontend	Frontend Dashboard	4 weeks, starts week 2
pipeline	Data Pipeline	2 weeks
integration	Integration Testing	1 week, after backend + frontend
uat	UAT	1 week, after integration testing
perf	Performance Testing	3 days, parallel to UAT
docs	Documentation	1 week
marketing	Marketing Prep	1 week
ga	GA Release	Milestone

Total node count: 9 tasks (within Gantt limit of 20)

Resulting Diagram

%% MEANING: Pulse Analytics v2.0 launch timeline with dependencies
gantt
    title Pulse Analytics v2.0 Launch Timeline
    dateFormat YYYY-MM-DD
    axisFormat %b %d

    section Development
    Backend API           :crit, backend, 2026-05-04, 3w
    Frontend Dashboard    :crit, frontend, 2026-05-11, 4w
    Data Pipeline         :pipeline, 2026-05-04, 2w

    section Quality
    Integration Testing   :crit, integration, after frontend, 1w
    UAT                   :crit, uat, after integration, 1w
    Performance Testing   :perf, after integration, 3d

    section Launch
    Documentation         :docs, after uat, 1w
    Marketing Prep        :marketing, after uat, 1w
    GA Release            :milestone, ga, after docs, 0d

What this communicates: The Gantt chart exposes the critical path: Backend API must finish before Integration Testing can start, and any delay in that chain pushes GA. It also shows that Data Pipeline and Performance Testing are off the critical path — they have slack. A bullet list of tasks with dates would hide these dependency relationships entirely.

Example 3: Sequence — Webhook Integration Flow

Context: The technical spec needs to show how webhook delivery works across five services, including the async handoff and retry behavior. Engineers reviewing the spec need to see the exact message flow.

Filled Worksheet

What I’m showing: The multi-service interaction flow for webhook event delivery, including async processing and retry logic. Audience: Backend engineers and integration partners reading the technical spec. Where this will appear: Pulse Analytics v2.0 Technical Spec, “Webhook Architecture” section.

Cardinal Rule Check:

This shows branching, relationships, or flow that a list would flatten
A numbered list or table would NOT communicate this more clearly

Five participants exchanging messages with async boundaries, a retry loop, and conditional behavior (success vs. failure). This is inherently a multi-party interaction.

Selected type: Sequence Why this type: Multi-party message exchange with async boundaries and conditional flows — sequence diagrams show this precisely. Considered alternatives: Flowchart (would work for the overall flow, but loses the participant swimlanes that make service responsibilities clear).

Node Inventory:

Node/Entity	Role/Label	Notes
CustomerApp	Customer App	External caller
PulseAPI	Pulse API	Entry point, sync response
EventProcessor	Event Processor	Async processing
WebhookService	Webhook Service	Delivery + retry
CustomerEndpoint	Customer Endpoint	External receiver

Total node count: 5 participants (within sequence limit of 6)

Resulting Diagram

%% MEANING: Webhook delivery flow showing async handoff and retry logic
sequenceDiagram
    participant CustomerApp as Customer App
    participant PulseAPI as Pulse API
    participant EventProcessor as Event Processor
    participant WebhookService as Webhook Service
    participant CustomerEndpoint as Customer Endpoint

    CustomerApp->>PulseAPI: Send Event
    PulseAPI->>PulseAPI: Validate Payload
    PulseAPI-->>CustomerApp: 202 Accepted

    PulseAPI-)EventProcessor: Queue Event (async)
    EventProcessor->>EventProcessor: Process + Enrich
    EventProcessor-)WebhookService: Dispatch Webhook

    loop Retry (max 3 attempts)
        WebhookService->>CustomerEndpoint: POST webhook payload
        alt Success
            CustomerEndpoint-->>WebhookService: 200 OK
            WebhookService->>WebhookService: Mark Delivered
        else Delivery Failure
            CustomerEndpoint-->>WebhookService: 5xx / Timeout
            WebhookService->>WebhookService: Backoff + Retry
        end
    end

What this communicates: The sequence diagram makes three things visible that prose obscures. First, the sync/async boundary: the customer gets 202 immediately while processing happens in the background. Second, the retry loop with backoff is a distinct phase, not buried in a paragraph. Third, the alt block shows that success and failure are handled differently at the same interaction point. Engineers can trace the exact message flow between services without reading paragraphs of text.

Example 4: Quadrant — Feature Prioritization

Context: The planning meeting needs a visual to drive prioritization discussion. Eight candidate features need to be evaluated on two dimensions: engineering effort and user impact.

Filled Worksheet

What I’m showing: Relative positioning of 8 candidate features on effort vs. impact dimensions to guide prioritization. Audience: Product and engineering leads in the quarterly planning meeting. Where this will appear: Planning meeting deck, “Prioritization” slide.

Cardinal Rule Check:

This shows branching, relationships, or flow that a list would flatten
A numbered list or table would NOT communicate this more clearly

Two-dimensional positioning reveals clusters and outliers that a sorted list on a single dimension would miss. Features in the “quick wins” quadrant are only visible when both dimensions are plotted.

Selected type: Quadrant Why this type: Two-axis comparison with labeled quadrants — purpose-built for 2D prioritization. Considered alternatives: None — no other mermaid type handles 2D scatter positioning.

Node Inventory:

Node/Entity	Role/Label	Notes
Dashboard Export	Quick Win	Low effort, high impact
Custom Alerts	Strategic Bet	High effort, high impact
Dark Mode	Low Priority	Low effort, low impact
API Rate Limits	Near boundary	Medium effort, medium impact
SSO Integration	Strategic Bet	High effort, high impact
Bulk Import	Quick Win	Low effort, high impact
Audit Log	Near boundary	Medium effort, medium impact
Mobile App	Strategic Bet	Very high effort, very high impact

Total node count: 8 data points (within quadrant limit of 10-12)

Resulting Diagram

%% MEANING: Feature prioritization for Pulse Analytics v2.0 planning meeting
quadrantChart
    title Feature Prioritization Matrix
    x-axis "Low Effort" --> "High Effort"
    y-axis "Low Impact" --> "High Impact"
    quadrant-1 "Strategic Bets"
    quadrant-2 "Quick Wins"
    quadrant-3 "Low Priority"
    quadrant-4 "Reconsider"
    "Dashboard Export": [0.2, 0.8]
    "Custom Alerts": [0.7, 0.85]
    "Dark Mode": [0.3, 0.4]
    "API Rate Limits": [0.5, 0.6]
    "SSO Integration": [0.8, 0.7]
    "Bulk Import": [0.15, 0.65]
    "Audit Log": [0.6, 0.5]
    "Mobile App": [0.9, 0.9]

What this communicates: The quadrant chart instantly reveals that Dashboard Export and Bulk Import are quick wins — high impact, low effort — while Mobile App demands the most investment for the highest payoff. The spatial clustering makes trade-offs visible: API Rate Limits and Audit Log sit near the center, suggesting they need further analysis before committing. A ranked list sorted by impact alone would hide the effort dimension that makes prioritization actionable.

Key Takeaways

The worksheet prevents false starts. Inventorying nodes before writing code catches missing participants, states, or data points early — not mid-diagram when restructuring is expensive.
The cardinal rule check saved work. If any of these examples had been a simple linear sequence, the worksheet would have redirected to a list before any mermaid code was written.
Diagram type selection is a design decision. Each example considered alternatives and chose the type that best matched the communication need, not the one the PM was most familiar with.
Context around the diagram matters. The mermaid code block alone is not enough — the “What this communicates” framing helps the audience know what to look for in the diagram.

Real-World Examples

See this skill applied to three different product contexts:

Storevine (B2B): Storevine B2B ecommerce platform . mermaid flowchart for Campaigns email send approval workflow

Prompt:

utility-mermaid-diagrams

I need a flowchart showing the Campaigns email send approval workflow. When a merchant clicks "Schedule Send," the campaign goes through content validation, compliance checks (CAN-SPAM), optional manager approval (for merchants on the Enterprise plan), and then queues for send. If any check fails, the merchant gets sent back to the editor with specific errors. I want to show this in the Campaigns PRD.

Output:

Mermaid Diagram Planning Worksheet

Mermaid Diagrams

When to Use

When NOT to Use

How to Use

Instructions

The Cardinal Rule

Diagram Selection Guide

Syntax Validity Principles

Output Contract

References

Output Template

Mermaid Diagram Planning Worksheet

1. Diagram Purpose

2. Cardinal Rule Check

3. Diagram Type Selection

4. Node Inventory

5. Draft Mermaid Code

6. Validation Checklist

Example Output

Worked Example: Diagrams for Pulse Analytics v2.0 Launch

Example 1: Flowchart — Feature Approval Workflow

Filled Worksheet

Resulting Diagram

Example 2: Gantt — Launch Timeline

Filled Worksheet

Resulting Diagram

Example 3: Sequence — Webhook Integration Flow

Filled Worksheet

Resulting Diagram

Example 4: Quadrant — Feature Prioritization

Filled Worksheet

Resulting Diagram

Key Takeaways

Real-World Examples

Mermaid Diagram Planning Worksheet

Quality Checklist