Design Doc Diagrams

The skill assumes diagrams are a TOOL, not the goal. Many docs (Jira tickets, short ADRs, runbook steps) need no diagram at all.

The decision tree is suggestive, not prescriptive — ask the user what venue the doc lives in (Confluence, Jira, GitHub, code repo, Slack) before picking the shape.

**Summary** (one sentence — what the work is)

**Why now / context**
[1-3 lines of background. Link the parent epic if one exists.]

**Acceptance criteria**
- [ ] Specific, observable outcome 1
- [ ] Specific, observable outcome 2
- [ ] Tests added / updated

**Out of scope**
[Anything a reviewer might assume is in but isn't.]

**Notes / links**
- Related PRs:
- Related Jira: PBAT-...
- Slack thread:

Skip diagrams in tickets unless the work is intrinsically visual (e.g. a new sequence between services). If the ticket is being filed from a design doc, link the design doc — don't restate it.

Before creating: GREP the epic / sibling tickets for already-shipped overlapping work (from feedback-grep-epic-before-filing).

# <Title>

## Context
Why this exists. What problem we're solving. Link prior art.

## Goals
Bulleted, observable success conditions.

## Non-goals
What this explicitly does NOT solve. Prevents scope creep in review.

## Proposed design
The actual decision + how it works. THIS is where diagrams usually go.

## Alternatives considered
Each alternative + why it lost. One paragraph each — not a survey.

## Risks / open questions
Honest list. Open questions belong here, not in chat.

## Migration / rollout
If applicable: stages, kill switches, rollback plan.

## Verification
How we'll know it worked — metrics, tests, monitors.

Keep alternatives honest — reviewers smell straw-man comparisons. Cite real evidence (links to issues, PRs, benchmark runs) rather than asserting tradeoffs.

Default workflow:

1. Decide diagram type (see <diagram_type_decision_tree>)
2. Generate Mermaid source applying the patterns + styling rules below
3. Call mcp__drawio__open_drawio_mermaid with that source — DO NOT paste it as a Markdown fence first
4. Also keep the Mermaid source in the design doc (or under ./diagrams/<name>.mmd) so it's diff-able in git

If the user explicitly asks for "just the Mermaid", skip step 3. If the doc has no diagrams (Jira ticket, short ADR), skip this whole block.

Activity Diagram (Workflows)

flowchart TD
    Start([Start]) --> Process[Process Data]
    Process --> Check{Valid?}
    Check -->|Yes| Save[Save]
    Check -->|No| Error[Error]
    Save --> Complete([Complete])

Architecture Diagram (Components)

graph TB
    Client[User] --> LB[Load Balancer]
    LB --> App1[App Server 1]
    LB --> App2[App Server 2]
    App1 --> DB[(Database)]
    App1 --> Cache[(Redis)]

Sequence Diagram (API Flows)

sequenceDiagram
    participant C as Client
    participant A as API
    participant D as Database
    C->>A: POST /login
    A->>D: Verify credentials
    D-->>A: User record
    A-->>C: JWT token

Deployment Diagram (Infrastructure)

graph TB
    subgraph Cloud[Cloud Provider]
        LB[Load Balancer]
        subgraph Compute[Compute]
            App1[Container 1]
            App2[Container 2]
        end
        DB[(Database)]
        Queue[Message Queue]
    end
    LB --> Compute
    Compute --> DB
    Compute --> Queue

Rules:

• Light background → Dark text color
• Always specify color: in every classDef
• One diagram = one concept (single responsibility)
• Avoid emoji/Unicode symbols in node labels — draw.io's Mermaid import handles them inconsistently across themes. Use text labels and let classDef carry the visual semantics.

1. Identify framework — Look for routing patterns, decorators, annotations
2. Map architecture — Controllers → Services → Repositories → Database
3. Extract flows — Follow method call chains for sequence diagrams
4. Find business logic — Conditionals and loops → activity diagrams
5. Map infrastructure — Docker/K8s/cloud configs → deployment diagrams

Generate multiple diagram types from a single codebase when appropriate.

Quick checks:

• Every node referenced in an edge is defined somewhere
• Subgraph names don't collide with node IDs
• classDef names referenced via class actually exist
• Pasted into https://mermaid.live renders without error

Only after the source validates, call mcp__drawio__open_drawio_mermaid. NEVER add a Mermaid fence to a Markdown doc until you've round-tripped it through validation.

The draw.io plugin renders the diagram in the browser — you don't need to also produce a .png. If the user wants a static image, ask them to export from inside draw.io (File → Export As → PNG/SVG) so the export carries the embedded XML for later editing.