/utils/diagram - Mermaid Diagram Utility

Skill Awareness: See skills/_registry.md for all available skills.

• Called by: /dev-scout, /dev-specs, /dev-arch for diagrams
• Related: /utils/docs-graph for document relationships
• Note: Utility skill, typically called by other skills

Create, validate, and fix Mermaid diagrams in markdown files.

Prerequisites

npm install -g @mermaid-js/mermaid-cli

Verify: mmdc --version

Usage

/utils/diagram validate path/to/file.md     # Validate diagrams in file
/utils/diagram validate                      # Validate file from context
/utils/diagram fix path/to/file.md          # Validate and auto-fix

Workflow

Validate Mode

1. Read the markdown file
2. Extract all mermaid code blocks
3. For each diagram, run: mmdc -i <temp-file> -o /tmp/mermaid-out.svg 2>&1
4. Report results:
   • Valid: Confirm with checkmark
   • Invalid: Show error, location, and what's wrong

Fix Mode

1. Validate first
2. For invalid diagrams:
   • Identify the error type (see references/common-errors.md)
   • Apply fix
   • Re-validate
3. Repeat until all diagrams pass
4. Update the file with fixes

Supported Diagram Types

Core Diagrams

Type	Keyword	Use For
Flowchart	flowchart	Process flows, decisions
Sequence	sequenceDiagram	API flows, interactions
State	stateDiagram-v2	Status lifecycle
ER Diagram	erDiagram	Database schema
Class	classDiagram	Object structures

Charts & Visualization

Type	Keyword	Use For
Pie	pie	Distribution
XY Chart	xychart-beta	Line/bar charts, trends
Quadrant	quadrantChart	Priority matrix, effort/impact
Sankey	sankey-beta	Flow visualization, funnels

Architecture & Systems

Type	Keyword	Use For
Architecture	architecture-beta	**AWS/...