microsoft/dot-graph-intelligence

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

| Operation | Question It Answers | Input | Output | |-----------|--------------------|---------|----| | reachability | Can node A reach node B? | source node, target node | yes/no + path | | unreachable | Which nodes are isolated or stranded? | graph | list of unreachable nodes | | cycles | Are there circular dependencies? | graph | list of cycle node sequences | | paths | What are all paths between two nodes? | source, target | list of paths | | critical_path | What is the longest path (bottleneck)? | graph (DAG) | ordered node list + length | | subgraph_extract | What is the subgraph reachable from a node? | root node | subgraph DOT | | diff | What changed between two versions? | graph A, graph B | added/removed nodes+edges | | stats | How large and dense is this graph? | graph | node count, edge count, density |

---

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

| Task | Use Code | Use LLM | |------|----------|---------| | Count nodes in a graph | ✓ | | | Check if path exists between two nodes | ✓ | | | Find all cycles | ✓ | | | Determine longest path | ✓ | | | List unreachable nodes | ✓ | | | Compare two graph versions (diff) | ✓ | | | Extract subgraph from root | ✓ | | | Calculate graph density | ✓ | | | Explain why a cycle is a design problem | | ✓ | | Suggest how to break a cycle | | ✓ |