Systematic Debugging

/systematic-debugging — Root Cause Before Fix

Orientation

Use when: root cause is unknown and premature fixes keep failing -- enforces observe -> hypothesize -> verify before touching code. Don't use when: root cause is already known (use /marshal to implement the fix); the bug is shallow and the stack trace is enough (use /do).

Protocol

Phase 1: OBSERVATION & REPRODUCTION

1. Read the error message, stack trace, or bug description
2. Reproduce the issue:
   • If it's a type error: run typecheck and read the full error
   • If it's a runtime error: identify the triggering conditions
   • If it's a behavioral bug: document expected vs actual behavior
3. Isolate the failing component/function:
   • What file? What function? What line?
   • What are the inputs when it fails?
   • Does it fail consistently or intermittently?

Output: A clear problem statement: "{Component} does {X} when it should do {Y}, triggered by {condition}"

Phase 2: HYPOTHESIS & VERIFICATION

1. Formulate up to 3 hypotheses for WHY the bug exists:

   • H1: {most likely cause} — because {evidence}
   • H2: {second candidate} — because {evidence}
   • H3: {third candidate} — because {evidence}

2. For each hypothesis, define a verification step:

   • Add a console.log / diagnostic read / breakpoint
   • Check a specific value at a specific point
   • DO NOT change any logic yet — only observe

3. Run the verification:

   • Which hypothesis was confirmed?
   • Which were eliminated?
   • If none confirmed: formulate new hypotheses with the new information

CRITICAL: Do not skip this phase. Do not "just try" a fix. Verify first.

Phase 3: ROOT CAUSE ANALYSIS

Once a hypothesis is confirmed:

1. Explain WHY the bug happens, not just WHERE:

   • Trace the data flow backward from the symptom to the source
   • Identify the specific incorrect assumption or logic error
   • Document the causal chain: "A calls B with X, B assumes X > 0, but A passes -1 when {condition}"

2. Check for related occurrences:

   • Is this pattern used elsewhere? Could the same bug exist in similar code?
   • Is there a systemic issue (e.g., missing validation at a boundary)?

Output: Root cause statement: "The bug occurs because {cause}. This happens when {trigger}."

Phase 4: IMPLEMENTATION

1. Write a failing test case that reproduces the bug (if test framework exists)
2. Apply the minimal fix — change only what's necessary to resolve the root cause
3. Verify the fix:
   • Test case now passes
   • Typecheck passes
   • No regressions in related functionality
4. If the root cause analysis revealed related occurrences, fix those too

Emergency Stop Rule

If a fix fails TWICE: STOP.

Do not try a third guess. The root cause analysis was wrong. Either:

• Go back to Phase 2 with new hypotheses
• Ask the user for more context about the system's intended behavior
• Check if there's a higher-level architectural issue

Three failed fixes in a row means you're guessing, not debugging.