Generating Diagrams

Overview

Generate accurate, renderable, exhaustive diagrams from code, processes, instructions, or architecture. Every node justified by source material. Every reference traced to its deepest level. Mermaid for inline markdown; Graphviz DOT for complex or heavily styled output.

When to Use

• Visualizing process flows, decision trees, or multi-phase workflows
• Mapping dependency/invocation relationships between components
• Documenting state machines or lifecycle transitions
• Creating entity-relationship or class hierarchy diagrams
• Analyzing skill, command, or instruction structure visually
• Generating sequence diagrams for temporal interactions

When NOT to use: Simple lists or tables suffice. Runtime observability. Text-only documentation.

Invariant Principles

1. Source-Grounded Nodes: Every node in the diagram must trace to a specific source location (file:line, section heading, or code symbol). No invented nodes.
2. Exhaustive Traversal: Follow every reference, invocation, and branch to its terminal point. "..." and "etc." are forbidden. If something is too complex, decompose into linked diagrams.
3. One Entity, One Node: In relationship/dependency diagrams, each entity appears exactly once. Multiple connections use multiple edges to the same node, not duplicate nodes.
4. Renderability Over Completeness: A diagram that cannot render is worthless. Always verify. When too complex for one diagram, decompose.

Quick Reference

Workflow

Phase 1: Analysis

Before generating any diagram, identify: subject type, traversal scope, source material locations, and rendering format.

1.1 Identify Diagram Subject

Classify what you are diagramming:

If the subject spans multiple types (e.g., a workflow that also shows dependencies), produce separate diagrams for each concern rather than a hybrid.

1.2 Scope the Traversal

Define boundaries BEFORE reading source material:

ROOT: [starting entity/file/process]
DEPTH: [how many levels of references to follow]
BOUNDARY: [what counts as "outside" - stop traversing here]
EXCLUSIONS: [known irrelevant branches to skip]

Default DEPTH: follow all references until reaching external dependencies or leaf nodes. The user should confirm or adjust.

1.3 Select Format

Use this decision matrix:

Default: Mermaid unless complexity indicators suggest otherwise.

1.4 Plan Decomposition (if needed)

When estimated node count exceeds format limits:

1. Level 0 (Overview): High-level boxes with phase/component names. No internal detail. Include "see Diagram N" references.
2. Level 1 (Phase Detail): One diagram per major phase/component. Shows all internal steps and decision points.
3. Level 2 (Deep Dive): Optional. For phases that are themselves complex (e.g., a sub-skill with its own multi-phase workflow).

Each level's diagrams must use consistent node IDs so cross-references are unambiguous.

Phase 2: Content Extraction

2.1 Systematic Traversal Protocol

This is the critical phase that prevents handwaving. Execute a depth-first traversal:

QUEUE = [ROOT]
VISITED = {}
NODES = []
EDGES = []

while QUEUE not empty:
    current = QUEUE.pop()
    if current in VISITED: continue
    VISITED.add(current)

    # Read source material for current entity
    content = read(current.source_location)

    # Extract this entity's node
    NODES.append({
        id: sanitize(current.name),
        label: current.display_name,
        source: current.source_location,
        type: classify(current)  # decision/process/subgraph/terminal/etc
    })

    # Extract all outgoing references
    for each reference in content:
        target = resolve(reference)
        EDGES.append({
            from: current.id,
            to: target.id,
            label: reference.context,
            condition: reference.condition or null
        })
        if target not in VISITED:
            QUEUE.append(target)

For each source file/section, extract:

• Decision points (if/else, switch, routing logic)
• Subagent dispatches or skill invocations
• Data transformations (input -> output)
• Quality gates (pass/fail with consequences)
• Loop/retry logic
• Terminal conditions (exit, error, completion)
• Conditional branches (with the condition on the edge label)

2.2 Verify Completeness

After traversal, check:

• Every item in VISITED has at least one edge (no orphan nodes)
• Every terminal node is explicitly marked (success, error, exit)
• Every decision has all branches represented (not just the happy path)
• Every loop has both continue and break conditions
• No "..." or placeholder nodes exist

Phase 3: Diagram Generation

3.1 Generate Diagram Code

Apply these layout rules:

Node label guidelines:

• Max 5 words per line in a node label
• Use <br/> for line breaks in Mermaid, \n in Graphviz
• Put detail in edge labels or annotations, not node labels
• Reference skill/command names inline: Invoke: skill-name

Multiplicity annotation: When the same target is invoked multiple times from the same source (e.g., fact-checking invoked at 3 different phases), use a single edge with multiplicity in the label: -->|"x3: per-task, comprehensive, pre-PR"| FC. Do NOT create separate edges for each invocation from the same source node unless the conditions differ meaningfully.

3.2 Generate Legend

Every diagram MUST include a legend. For Mermaid, add a disconnected subgraph:

subgraph Legend
    L1[Process Step]
    L2{Decision Point}
    L3([Terminal])
    L4[/Input-Output/]
end

For Graphviz, use a separate subgraph cluster_legend.

Include color meanings if using classDef or fill colors.

3.3 Generate Cross-Reference Table

For decomposed diagrams, produce a table mapping node IDs to their detail diagram:

Phase 4: Verification

4.1 Syntax Check

• Mermaid: Paste into mermaid.live or a local renderer
• Graphviz: Run dot -Tsvg input.dot -o output.svg
• If no renderer available, perform manual syntax audit:
  1. Count opening/closing braces and brackets (must match)
  2. Verify every subgraph has a matching end
  3. Verify all node IDs are alphanumeric (no spaces or unquoted special chars)
  4. Verify all edge labels use correct quoting (|"label"| for Mermaid)
  5. Verify classDef names match class references
  6. Check for Mermaid reserved words used as node IDs (end, graph, subgraph)

4.2 Renderability Check

4.3 Completeness Check

Compare diagram against source material:

• Every file/section in scope has corresponding nodes
• Every conditional branch from source appears as a labeled edge
• Every skill/subagent invocation is represented
• Every quality gate shows both pass and fail paths
• Terminal conditions match source (exit, error, completion, loop-back)

If anything is missing, return to Phase 2 and re-traverse.

Mermaid Syntax Reference

flowchart TD
    A[Process] --> B{Decision}
    B -->|Yes| C[Action]
    B -->|No| D[Other Action]
    C --> E([Terminal])

    subgraph Group Name
        F[Step 1] --> G[Step 2]
    end

    style A fill:#4a9eff,color:#fff
    classDef gate fill:#ff6b6b,color:#fff
    class B gate

sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: Request
    B-->>A: Response
    alt Success
        A->>B: Confirm
    else Failure
        A->>B: Retry
    end

stateDiagram-v2
    [*] --> Idle
    Idle --> Processing: start
    Processing --> Complete: success
    Processing --> Failed: error
    Failed --> Idle: retry
    Complete --> [*]

erDiagram
    SKILL ||--o{ COMMAND : "invokes"
    SKILL {
        string name
        string description
    }
    COMMAND {
        string name
        string phase
    }

Graphviz DOT Reference

digraph G {
    rankdir=TD;
    node [shape=box, style=filled, fillcolor="#f0f0f0"];

    // Nodes
    start [label="Start", shape=oval];
    decision [label="Decision?", shape=diamond, fillcolor="#ff6b6b"];
    process [label="Process Step", fillcolor="#4a9eff", fontcolor=white];
    end_node [label="End", shape=doubleoctagon, fillcolor="#51cf66"];

    // Edges
    start -> decision;
    decision -> process [label="Yes"];
    decision -> end_node [label="No", style=dashed];
    process -> end_node;

    // Clusters
    subgraph cluster_phase1 {
        label="Phase 1";
        style=filled;
        fillcolor="#f8f9fa";
        a1 -> a2 -> a3;
    }
}

Common Mistakes

After generating any diagram, verify: every node traces to source, no placeholders remain, legend is present, syntax renders cleanly, and completeness check passes.

Rationalization Counters