name: systematic-debugging version: 2.0.0 description: 4-phase root cause debugging. Never guess, find the cause. Based on real production debugging methodology. Trigger on: 'bug', 'error', 'not working', 'broken', 'debug', 'fix this'. emoji: 🔍

Systematic Debugging 🔍

4 phases. No guessing. Find root cause.

The 4 Phases

Phase 1: OBSERVE    → What exactly is wrong? (Gather evidence)
Phase 2: ISOLATE    → Where does it go wrong? (Narrow scope)
Phase 3: HYPOTHESIZE → Why does it go wrong? (Form theory)
Phase 4: VERIFY     → Is it actually fixed? (Prove it)

Phase 1: OBSERVE (Don't Skip This)

Before touching any code, answer these:

□ What is the expected behavior?
□ What is the actual behavior?
□ When did it start? (What changed?)
□ Is it reproducible? (100%? Intermittent?)
□ What's the exact error message / log output?
□ What environment? (OS, version, dependencies)

Common mistake: Jumping to "I think it's because..." without observing first.

What to do:

• Read the actual error (copy-paste, don't paraphrase)
• Check logs (recent ones first)
• Reproduce the issue (if possible)
• Document what you see

Phase 2: ISOLATE (Narrow the Scope)

Binary search for the bug:

1. Is the problem in my code or external?
   → Comment out my code. Still broken? External.

2. Is it in the input, processing, or output?
   → Print/log at each stage.

3. Is it in one specific file/function?
   → Remove files/functions one by one.
   → Bug disappears? That's where it is.

4. Is it a specific condition?
   → Test with different inputs.
   → Pattern emerges? Root cause narrows.

Techniques:

• git bisect — Find the commit that introduced the bug
• Print statements at boundaries
• Comment out code sections
• Test with minimal reproduction

Phase 3: HYPOTHESIZE (Form a Theory)

Write your hypothesis BEFORE fixing:

I believe [X] is broken because [Y].

Evidence supporting:
- [Observation 1]
- [Observation 2]

Evidence against:
- [Observation 3]

If I change [Z], the fix should:
- Make [test case] pass
- Not break [other thing]

Common mistake: Fixing without understanding. You might "fix" the symptom, not the cause.

Anti-patterns:

• ❌ "Let me try changing this..." (random fixing)
• ❌ "This usually works..." (cargo cult debugging)
• ❌ "It's probably a race condition" (vague guess)

Phase 4: VERIFY (Prove It)

Before claiming "fixed":

□ Original test case now passes
□ Edge cases tested
□ No new regressions introduced
□ Error no longer appears in logs
□ Fix makes sense given the hypothesis

Verification checklist:

# Run the failing test
npm test -- --grep "failing test"
# Check logs for errors
tail -f /var/log/app.log
# Test edge cases
[try empty input, huge input, unicode, etc.]
# Run full test suite
npm test

Real Example

Bug: "User login sometimes fails"