mav-systematic-debugging

Systematic Debugging

Find root cause before attempting fixes. Random fixes waste time, create new bugs, and mask underlying issues.

The Iron Law

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

If you have not completed Phase 1, you cannot propose fixes.

When to Use

Use for any technical issue encountered during implementation:

• Test failures
• Build errors
• Unexpected behaviour
• Integration issues
• Performance problems

Use this especially when:

• A fix attempt has already failed
• The issue seems "obvious" (obvious issues still have root causes)
• You are under pressure to move to the next step
• You do not fully understand the failure

The Four Phases

Complete each phase before proceeding to the next.

digraph debugging {
    "Phase 1: Root Cause Investigation" [shape=box];
    "Root cause identified?" [shape=diamond];
    "Phase 2: Pattern Analysis" [shape=box];
    "Phase 3: Hypothesis and Test" [shape=box];
    "Hypothesis confirmed?" [shape=diamond];
    "Phase 4: Fix and Verify" [shape=box];
    "Fix works?" [shape=diamond];
    "Done" [shape=box];
    "Attempts >= 3?" [shape=diamond];
    "Escalate — question architecture" [shape=box];

    "Phase 1: Root Cause Investigation" -> "Root cause identified?";
    "Root cause identified?" -> "Phase 2: Pattern Analysis" [label="yes"];
    "Root cause identified?" -> "Phase 1: Root Cause Investigation" [label="no — gather more evidence"];
    "Phase 2: Pattern Analysis" -> "Phase 3: Hypothesis and Test";
    "Phase 3: Hypothesis and Test" -> "Hypothesis confirmed?";
    "Hypothesis confirmed?" -> "Phase 4: Fix and Verify" [label="yes"];
    "Hypothesis confirmed?" -> "Phase 3: Hypothesis and Test" [label="no — new hypothesis"];
    "Phase 4: Fix and Verify" -> "Fix works?";
    "Fix works?" -> "Done" [label="yes"];
    "Fix works?" -> "Attempts >= 3?" [label="no"];
    "Attempts >= 3?" -> "Phase 1: Root Cause Investigation" [label="no — re-investigate"];
    "Attempts >= 3?" -> "Escalate — question architecture" [label="yes"];
}