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: Structure is flat (no branches, decisions, or relationships) AND content is 10 items or fewer -- a list or table suffices. Runtime observability. Text-only documentation.

Invariant Principles

1. Source-Grounded Nodes: Every node traces 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 too complex for one diagram, decompose into linked diagrams.
3. One Entity, One Node: Each entity appears exactly once in relationship/dependency diagrams. Multiple connections use multiple edges, 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

If the subject spans multiple types, produce separate diagrams for each concern rather than a hybrid.

1.2 Scope the Traversal

Define boundaries BEFORE reading source material. Confirm with user; in autonomous mode, use default depth.

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.

1.3 Select Format

Default: Mermaid unless complexity indicators from the table above 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

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

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

    content = read(current.source_location)

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

    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)

Extract from each source file/section:

• 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

• 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

Node label guidelines:

• Max 5 words per line
• 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, use a single edge with multiplicity in the label: -->|"x3: per-task, comprehensive, pre-PR"| FC. Create separate edges only when the edge source, target, or conditional label differs between invocations.

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

Include color meanings if using classDef or fill colors. For Graphviz, add subgraph cluster_legend.

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, 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

• 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.

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

Mermaid in Markdown Files

When writing mermaid diagrams inside markdown files, use <br> for newlines within node labels. Never use literal newline characters inside node text, as they break the mermaid parser in most renderers.

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"];

    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"];

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

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

Common Mistakes

Rationalization Counters

Update Mode (Default)

When updating existing diagrams (the default path), the system classifies source changes before deciding how to proceed:

Tier 1: STAMP (Non-Structural)

Changes that don't affect the workflow diagram are stamped as fresh without regeneration.

• Adding/modifying XML tags (e.g., <BEHAVIORAL_MODE>, <ROLE>, <CRITICAL>)
• Changing prose, descriptions, or explanations within existing steps
• Fixing typos, rewording instructions
• Adding/removing FORBIDDEN or REQUIRED items
• Changing code examples within steps

Tier 2: PATCH (Surgical Update)

Small structural changes trigger targeted edits to the existing diagram rather than full regeneration.

• Adding or removing a single step within an existing phase
• Renaming a phase or step
• Adding a new quality gate
• Reordering 1-2 steps

When patching, preserve ALL existing diagram structure, styling, and layout. Only modify the specific nodes, edges, or subgraphs affected by the change.

Tier 3: REGENERATE (Full)

Major structural changes fall through to the full 4-phase generation workflow above.

• Adding or removing entire phases
• Major reorganization of step ordering
• Changing flow/branching logic
• Adding new parallel tracks or decision points

Invocation

• generate_diagrams.py --interactive uses smart classification by default
• generate_diagrams.py --force-regen bypasses classification for full regeneration
• On any classification or patching error, falls back to full regeneration automatically

<FINAL_EMPHASIS> Every node traces to source. Every diagram renders. Every phase executes. Shortcuts produce wrong diagrams that mislead -- and a wrong diagram is worse than no diagram at all. </FINAL_EMPHASIS>