dot-as-analysis

microsoft/amplifier-bundle-dot-graphArchitecture & DesignAudit passedSnapshot e2531049ca80

Installs: 0

Summary

Use when analyzing a system to surface hidden issues — draw what you believe exists, then reconcile against what actually exists

SKILL.md

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

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.

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
}

dot-as-analysis

Summary

SKILL.md

DOT as Analysis

Overview

The Reconciliation Workflow

Phase 1: Introspect

Phase 2: Represent

Phase 3: Reconcile

Phase 4: Surface

Anti-Rationalization Table

When to Use

High value (use this skill):

Low value (skip this skill):

Example: Reconciliation-Driven Bug Discovery

Related skills