name: dot-graph-intelligence description: Use when you need programmatic graph structure analysis — reachability, cycles, critical paths, and diffs without spending LLM tokens on structural questions code can answer

DOT Graph Intelligence

Overview

Structural questions about graphs — "is this node reachable?", "are there cycles?", "what changed?" — are code problems, not language model problems. Graph analysis tools answer these in milliseconds with zero ambiguity. Reserve LLM reasoning for interpretation, not computation.

Core principle: Code answers structural questions — that is code's judgment to make. LLMs interpret what the answers mean. Use the right tool for each layer.

When to Use

digraph when_to_use {
    label="When to Use Graph Intelligence"
    labelloc=t
    rankdir=TB
    node [shape=diamond style="rounded,filled" fillcolor="#FFF9C4" fontname="Helvetica"]
    edge [fontname="Helvetica" fontsize=10]

    Q1 [label="Is the question\nstructural?\n(reachability, cycles,\npaths, counts)"]
    Q2 [label="Does it require\nunderstanding\nmeaning or context?"]

    node [shape=box style="rounded,filled"]
    UseCode [label="Use graph analysis\noperations" fillcolor="#C8E6C9"]
    UseLLM  [label="Use LLM reasoning\nwith graph as context" fillcolor="#E8F0FE"]
    UseBoth [label="Run analysis first,\nthen interpret results\nwith LLM" fillcolor="#FFF9C4"]

    Q1 -> UseCode [label="yes — pure structure"]
    Q1 -> Q2      [label="no"]
    Q2 -> UseLLM  [label="yes — meaning only"]
    Q2 -> UseBoth [label="both structure\nand meaning"]
}

Operations Reference

The Analysis Loop

A 7-step process for structured graph investigation:

1. Define the question — write it as a structural query before running any tool ("are there cycles in the dependency graph?")
2. Select the operation — match the question to the operations table above
3. Run the operation — use graph analysis tooling, not manual inspection
4. Capture raw output — save the result before interpreting it
5. Interpret with context — bring the result to LLM reasoning with the original diagram and question
6. Update the diagram — if the analysis reveals a structural issue, fix the diagram to reflect reality
7. Re-run to verify — confirm the fix resolves the original query

Interpretation Guide

When analysis returns results, apply these patterns:

Cycles detected:

• In a dependency graph: circular dependency — likely a design problem
• In a state machine: valid if expected (loop states), invalid if unexpected
• In a data flow: data is being written back to a source it reads from — check for corruption risk

Unreachable nodes found:

• Dead code path — the node was never connected or was disconnected during refactoring
• Orphaned component — a service or module with no callers
• Forgotten placeholder — an intended node that was never wired up

High density (edges >> nodes):

• Everything-talks-to-everything pattern — high coupling, hard to isolate for testing
• Missing abstraction layer — consider introducing a coordinator or message bus

Multiple disconnected components:

• Expected if diagram covers independent subsystems
• Unexpected if diagram is supposed to show a single connected system — something is missing

Code vs LLM Decision Matrix