systematic-debugging

Systematic Debugging

From obra/superpowers

Core Principle

NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Random fixes create new bugs. Understanding must precede solutions.

The Four Phases

Phase 1: Root Cause Investigation

Before ANY fix attempt:

1. Read error messages carefully
2. Full stack traces
3. Error codes and descriptions
4. Timestamps and context

1. Reproduce consistently
2. Document exact steps
3. Identify triggers
4. Note environmental factors

1. Check recent changes
2. Recent commits
3. Dependency updates
4. Configuration changes

1. Gather diagnostic evidence
2. Add logging at component boundaries
3. Check input/output at each step
4. Trace data flow backward to source

Phase 2: Pattern Analysis

1. Find similar working code
2. Search codebase for related functionality
3. Look for existing patterns

1. Read reference implementations completely
2. Don't skim
3. Understand the full context

1. Compare working vs broken
2. What's different?
3. What assumptions changed?

1. Understand dependencies
2. What does this code rely on?
3. What relies on this code?

Phase 3: Hypothesis and Testing

1. Form a SINGLE, SPECIFIC hypothesis
2. "The error occurs because X"
3. Not "maybe it's A or B or C"

1. Test with minimal changes
2. One variable at a time
3. Don't combine fixes

1. Accept results
2. If hypothesis is wrong, form new one
3. Don't force-fit evidence

1. Ask for help when stuck
2. After genuine investigation
3. With evidence gathered

Phase 4: Implementation

1. Create a failing test case FIRST
2. Reproduces the bug
3. Will pass when fixed

1. Implement SINGLE fix
2. Address root cause only
3. Don't fix "nearby" issues

1. Verify the fix
2. Test case passes
3. No regressions
4. Issue is resolved

The 3-Fix Rule

If ≥3 fixes fail: STOP and question the architecture

Three consecutive failed fixes signal:

• Architectural problem, not implementation bug
• Wrong mental model of the system
• Need to step back and reassess

Do NOT attempt more fixes. Reassess the approach.

Critical Red Flags

STOP and restart investigation if you:

• Propose fixes before understanding the problem
• Add multiple changes simultaneously
• Skip investigation for "quick fixes"
• Make 3+ failed fix attempts
• Say "let's just try this"

Debugging Checklist

## Investigation
- [ ] Read full error message/stack trace
- [ ] Reproduced issue consistently
- [ ] Checked recent changes
- [ ] Added diagnostic logging
- [ ] Traced data flow

## Analysis
- [ ] Found similar working code
- [ ] Compared working vs broken
- [ ] Understood all dependencies

## Hypothesis
- [ ] Formed single specific hypothesis
- [ ] Tested with minimal change
- [ ] Accepted results honestly

## Fix
- [ ] Created failing test case
- [ ] Implemented single fix
- [ ] Verified fix works
- [ ] No regressions

Example Workflow

Issue: User login fails silently

Phase 1 - Investigation:
- Error: "null reference at AuthService.validate()"
- Reproduced: happens with specific user emails
- Recent change: added email normalization

Phase 2 - Analysis:
- Working logins use lowercase emails
- Failing logins have mixed case
- Normalization strips @ symbol incorrectly

Phase 3 - Hypothesis:
- "Email normalization regex is wrong"
- Test: log email before/after normalization
- Result: "Test@Example.com" → "testexample.com"
- Confirmed!

Phase 4 - Fix:
- Write test: normalize("Test@Example.com") == "test@example.com"
- Fix regex to preserve @
- Verify: test passes, logins work