Systematic Debugging

Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.

Phase 1: Reproduce & Isolate

• Reproduce the failure reliably before anything else
• Isolate the smallest failing case
• If you can't reproduce it, you can't fix it
• Record the exact command, input, and output that demonstrates the failure

Phase 2: Gather Evidence

Before forming hypotheses, collect facts:

• Read the actual code path from input to failure point. Don't guess from memory.
• Check recent changes:

  git log --oneline -10 -- <file>

• Add temporary logging or assertions at key points to trace data flow
• Collect the full error message, stack trace, and relevant log output
• If a stack trace exists, trace backward through the call chain to the origin

Known bug patterns — check these first:

undefined is not a function

NoMethodError

NoneType

If the bug matches a known pattern, state which one and focus investigation there.

Phase 3: Hypothesize & Test

• Form a specific hypothesis: "The root cause is X because evidence Y"
• Predict the outcome BEFORE running each test
• Test one variable at a time
• If your prediction is wrong, update your mental model — don't just try the next thing

"5 Whys" drill-down — when the cause isn't obvious, ask why iteratively:

1. Why did the request fail? → The handler returned null
2. Why did it return null? → The query returned no rows
3. Why did the query return no rows? → The ID was from a different tenant
4. Why was the ID from a different tenant? → The session wasn't scoped to tenant
5. Why wasn't the session scoped? → Root cause: middleware ordering

Keep asking why until you reach something you can fix directly.

Phase 4: Fix & Verify

1. Write a regression test that fails without the fix and passes with it. This is not optional.
2. Fix the root cause, not the symptom
3. Keep the diff minimal — only change what's needed to fix the bug
4. Run the original failing test to confirm the fix
5. Run the full test suite to check for regressions

Three-Strikes Rule

If 3 hypotheses have failed, STOP. You are likely wrong about the root cause.

• Go back to Phase 2 and re-read the code path from scratch
• Question your assumptions about the architecture
• Use AskUserQuestion to escalate: describe what you've tried, what you've ruled out, and where you're stuck
• Optionally WebSearch for the error message or pattern — someone may have hit this before

Escalation is not failure. Bad work is worse than no work. Stop guessing.

Red Flags

If you catch yourself thinking any of these, STOP:

• "Let me just try..." — You're guessing, not tracing.
• "Maybe if I..." — Form a hypothesis and predict the outcome first.
• "This might work..." — Why would it work? What's your evidence?
• "It's probably this..." — Probably based on what? State the evidence.

Anti-Rationalization Table

Debug Report

After resolution, output a structured report:

═══════════════════════════════════════════
DEBUG REPORT
═══════════════════════════════════════════
Status: DONE / DONE_WITH_CONCERNS / BLOCKED
Symptom: [what was observed]
Root Cause: [what was actually wrong]
Pattern: [known pattern match, if any]
Fix: [what was changed and why]
Regression Test: [test name and what it verifies]
Evidence: [how you confirmed the fix addresses the root cause]
Hypotheses Tested: N (list failed ones if >1)
═══════════════════════════════════════════

• DONE — Root cause identified, fix applied, regression test passes, full suite green
• DONE_WITH_CONCERNS — Fixed, but related issues discovered. Note them for follow-up.
• BLOCKED — Cannot resolve. Document what was tried and what's needed to proceed.

If the root cause was non-obvious, save debugging insights to auto-memory.

Evolved from obra/superpowers systematic-debugging skill with patterns from garrytan/gstack and community best practices.