mermaid-diagrams

What this skill does

# Mermaid Diagrams Skill

This skill helps create clean, well-organized Mermaid diagrams for software engineering and architecture visualization.

<when_to_use>
Use this skill specifically for creating, editing, fixing, or improving Mermaid diagrams:
- **Create** new Mermaid diagrams
- **Edit** existing Mermaid diagrams
- **Fix** broken or incorrect diagram syntax
- **Improve** diagram organization or readability
- **Visualize** software architecture or technical concepts

For simply reading or interpreting existing diagrams, proceed directly without this skill.
</when_to_use>

<diagram_types>

This skill supports all major Mermaid diagram types for software engineering:

1. **Flowcharts** - Process flows, algorithms, decision trees
2. **Sequence Diagrams** - API interactions, service communication, workflows
3. **Class Diagrams** - Object models, domain design, relationships
4. **ER Diagrams** - Database schemas, data models
5. **State Diagrams** - State machines, workflow states, lifecycle
6. **C4 Diagrams** - Software architecture (context, container, component)
7. **Git Graphs** - Branching strategies, version control workflows
</diagram_types>

<references>
**Parallel Loading:** When creating diagrams, read `references/gotchas.md` AND the relevant syntax reference file simultaneously. Load multiple template files in parallel when creating complex diagrams.

### Quick Reference Priority

When creating or editing diagrams, consult references in this order:

**For all diagrams first:**
1. **`references/gotchas.md`** - Common errors, special characters, reserved keywords
2. **`references/styling.md`** - Themes, colors, formatting

**Then consult the specific syntax reference:**
- `references/syntax-flowchart.md`
- `references/syntax-sequence.md`
- `references/syntax-class.md`
- `references/syntax-er.md`
- `references/syntax-state.md`
- `references/syntax-c4.md`
- `references/syntax-git.md`

**For architectural patterns:**
- `references/patterns.md` - Common software architecture patterns

### When to Load References

**Always load gotchas.md when:**
- Creating complex diagrams
- Fixing syntax errors
- Dealing with special characters or reserved words

**Load styling.md when:**
- User requests specific colors or themes
- Creating presentation-quality diagrams
- Need to emphasize specific elements

**Load specific syntax reference when:**
- Creating a diagram type for the first time
- User asks about specific features
- Need to verify correct syntax

**Load patterns.md when:**
- Visualizing software architecture
- User mentions specific patterns (microservices, hexagonal, CQRS, etc.)
- Creating system design diagrams
</references>

<templates>

Pre-built, well-commented templates are available in `assets/templates/`:

- `flowchart-template.md` - Organized flowchart with sections
- `sequence-template.md` - Sequence diagram with best practices
- `class-template.md` - Domain model class diagram
- `er-template.md` - Database schema ER diagram

**Use templates when:**
- Starting a new complex diagram
- User wants a well-organized structure
- Creating diagrams that will grow over time
</templates>

<best_practices>

### 1. Clean Code Organization

Use the same principles as code:
- **Comment liberally** - Use `%%` to explain sections
- **Group related items** - Keep related nodes/classes together
- **Separate concerns** - Define structure first, styling last
- **Use descriptive names** - Make IDs and labels meaningful

**Example:**
```mermaid
flowchart TB
    %% =================================================================
    %% USER AUTHENTICATION FLOW
    %% =================================================================
    
    %% -----------------------------------------------------------------
    %% Entry Point
    %% -----------------------------------------------------------------
    Start[User enters credentials]
    
    %% -----------------------------------------------------------------
    %% Validation
    %% -----------------------------------------------------------------
    Validate[Validate input format]
    CheckDB{Credentials valid?}
    
    %% ... rest of diagram
```

### 2. Make Diagrams Navigable

For large diagrams:
- Use clear section headers in comments
- Group logically related elements
- Keep consistent indentation in the code
- Add blank lines between sections

**Structure pattern:**
```
%% Section 1: Definition
[define elements]

%% Section 2: Connections
[define relationships]

%% Section 3: Styling
[define styles]
```

### 3. Handle Complexity

When diagrams get large:
- Break into multiple smaller diagrams
- Use subgraphs for logical grouping
- Link between diagrams with notes
- Consider creating an overview diagram

### 4. Avoid Common Pitfalls

Before finalizing any diagram, check:
- [ ] No reserved keywords as node IDs
- [ ] Special characters properly escaped or quoted
- [ ] All brackets/parens balanced
- [ ] All blocks (subgraph, loop, alt) properly closed
- [ ] Unique IDs for all elements
- [ ] Consistent quote style throughout
</best_practices>

<workflow>

### Step 1: Understand Requirements
- What concept needs visualization?
- Which diagram type is most appropriate?
- What's the target audience?

### Step 2: Choose Diagram Type
- **Process/Algorithm** → Flowchart
- **Time-based interactions** → Sequence diagram
- **Object relationships** → Class diagram
- **Data model** → ER diagram
- **State management** → State diagram
- **System architecture** → C4 diagrams
- **Git workflow** → Git graph

### Step 3: Start Simple
Begin with basic structure:
```mermaid
flowchart LR
    A --> B
    B --> C
```

### Step 4: Add Details Incrementally
- Add more nodes/relationships
- Add labels and descriptions
- Group into subgraphs if needed
- Add comments for clarity

### Step 5: Apply Styling (Optional)
- Choose appropriate theme
- Add colors for semantic meaning
- Highlight important elements
- Ensure accessibility

### Step 6: Review and Refine
- Test the diagram renders correctly
- Check for syntax errors
- Verify it communicates the intended message
- Add comments for future maintainability
</workflow>

<syntax_reference>

### Escaping Special Characters
```mermaid
%% Use quotes for special characters
A["Function with (parentheses)"]
B["Text with [brackets]"]

%% Or use HTML entities
C[getData#40;#41;]  %% getData()
```

### Common Relationship Patterns

**Flowcharts:**
- `-->` solid arrow
- `-.->` dotted arrow
- `==>` thick arrow

**Class diagrams:**
- `<|--` inheritance
- `*--` composition
- `o--` aggregation
- `-->` association
- `..>` dependency

**ER diagrams:**
- `||--||` one-to-one
- `||--o{` one-to-many
- `}o--o{` many-to-many
</syntax_reference>

<use_cases>

### API Documentation
Use sequence diagrams to show request/response flows:
```mermaid
sequenceDiagram
    Client->>API: POST /users
    API->>Database: INSERT user
    Database-->>API: User created
    API-->>Client: 201 Created
```

### Database Schema
Use ER diagrams with full attribute details:
```mermaid
erDiagram
    USER {
        uuid id PK
        string email UK
    }
    ORDER {
        uuid id PK
        uuid user_id FK
    }
    USER ||--o{ ORDER : places
```

### System Architecture
Use C4 diagrams for different abstraction levels:
```mermaid
C4Context
    Person(user, "User")
    System(sys, "System")
    Rel(user, sys, "Uses")
```

### Process Documentation
Use flowcharts with clear decision points:
```mermaid
flowchart TB
    Start --> Check{Valid?}
    Check -->|Yes| Process
    Check -->|No| Error
```
</use_cases>

<troubleshooting>

### Diagram Won't Render

1. Check for unbalanced quotes or brackets
2. Look for reserved keywords as IDs
3. Verify all blocks are closed (end statements)
4. Check for special characters - escape them
5. Ensure proper syntax for diagram type

### Common Error Fixes

**"Parse error"**
→ Check syntax matches diagram type

**"Syntax error in text"**
→ Escape special characters or use quotes

**Blank out