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:

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:

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.