dot-as-analysis

name	dot-as-analysis
description	Use when analyzing a system to surface hidden issues — draw what you believe exists, then reconcile against what actually exists

DOT as Analysis

Overview

DOT diagrams are not just documentation — they are analysis instruments. Drawing a system forces you to make structural claims. Those claims can be verified, and the gaps between belief and reality reveal bugs, missing paths, and hidden coupling.

Core principle: Completeness pressure is the mechanism. You cannot leave a box disconnected without asking why. You cannot draw a flow without tracing where it actually goes. The act of drawing forces reconciliation.

---

The Reconciliation Workflow

A 4-phase process for using diagrams to surface system truth:

Phase 1: Introspect

Write down what you believe the system does. List the components, the flows, the states. Do not look at the code yet. This captures your current mental model.

Phase 2: Represent

Draw your belief as a DOT diagram. Use the correct shape vocabulary (services as boxes, data stores as cylinders, decisions as diamonds). Every node must connect to something — floating nodes are a forcing function.

Phase 3: Reconcile

Read the actual code, configs, and logs. For each element in your diagram, verify it exists and behaves as drawn. Fill in the findings table:

Element	Believed	Actual	Status	Issue
Auth Service	validates JWT	delegates to external	WRONG	undocumented dependency
Retry logic	3 attempts	no retry	MISSING	silent data loss possible
DB connection	pooled	new conn per request	WRONG	performance risk
Event queue	async	synchronous call	WRONG	blocking main thread
Cache layer	present	not implemented	MISSING	latency assumption invalid
Error path	logged	swallowed	WRONG	debugging blind spot

Phase 4: Surface

Update the diagram to reflect reality. The delta between Phase 2 and Phase 4 is your finding report. Each discrepancy is a candidate bug, design debt, or documentation gap.

---

Anti-Rationalization Table

When reconciling, these thoughts will arise. Resist them:

Rationalization	Correction
"That path probably exists, I'll add it anyway"	Only draw what you can verify. Unverified paths are hypotheses, not facts.
"The diagram is close enough"	Close enough hides the discrepancy. Draw the delta explicitly.
"It works in practice so the diagram doesn't matter"	If it works differently than drawn, the diagram is wrong. Fix the diagram or document the reason.
"That component is internal, I don't need to show it"	Hidden internals are where bugs live. Show it.
"The error path is obvious, I'll skip it"	Error paths are where the interesting failures happen. Draw them explicitly.
"That's just infrastructure, not worth diagramming"	Infrastructure failures are system failures. Include it.
"I'll add the legend later"	Legends are added before sharing, not after. A diagram without a legend is ambiguous.

---

When to Use

High value (use this skill):

• Debugging a system you haven't touched in months
• Onboarding to an unfamiliar codebase
• Pre-incident review — mapping what you assume before an outage changes your assumptions
• Architecture review — validating that the implementation matches the design
• Before refactoring — drawing the current state reveals coupling you'd otherwise miss

Low value (skip this skill):

• Simple single-function scripts
• Well-understood systems with up-to-date documentation
• UI-only changes with no service interactions
• Throwaway scripts

---

Example: Reconciliation-Driven Bug Discovery

Scenario: A developer believed a payment service retried failed transactions. They drew the believed flow:

digraph believed_payment_flow {
    label="Payment Flow (Believed)"
    labelloc=t
    rankdir=LR
    node [shape=box style="rounded,filled" fillcolor="#E8F0FE" fontname="Helvetica"]

    Request  [label="Payment\nRequest"]
    Validate [label="Validate"]
    Charge   [label="Charge\nGateway"]
    Retry    [label="Retry\n(3 attempts)" fillcolor="#FFF9C4"]
    Record   [label="Record\nTransaction"]
    Done     [label="Done" shape=ellipse fillcolor="#C8E6C9"]
    Failed   [label="Failed" shape=ellipse fillcolor="#FFCDD2"]

    Request -> Validate -> Charge
    Charge  -> Record   [label="success"]
    Charge  -> Retry    [label="failure" color="#E57373"]
    Retry   -> Charge   [label="attempt again" style=dashed]
    Retry   -> Failed   [label="exhausted"]
    Record  -> Done
}

After reconciliation: The retry node did not exist. Charge failures went directly to a log entry and returned an error to the caller. The caller had no retry either. The discrepancy revealed that a production outage during a transient gateway failure had silently dropped transactions.

Outcome: The diagram delta — one missing retry node and two missing edges — became the bug report. The fix was targeted because the analysis was precise.