Systematic Debugging
Four-phase debugging methodology emphasizing root cause investigation before fixes to prevent symptom-chasing and cascade failures.
Essential for developers who want to fix bugs permanently instead of applying patches that create new problems.
Core Principle
Root cause investigation MUST precede fix attempts.
Symptom fixes create cascading problems. Understanding why something broke prevents recurrence.
Four Phases
Systematic Process
Phase 1: Root Cause Investigation
- Analyze error messages and stack traces
- Reproduce the bug reliably
- Gather evidence systematically
Phase 2: Pattern Analysis
- Compare working vs. broken code
- Identify what changed
- Understand the failure pattern
Phase 3: Hypothesis Testing
- Form testable theories
- Verify hypotheses scientifically
- Rule out red herrings
Phase 4: Implementation
- Write test demonstrating bug
- Implement minimal fix
- Evaluate if architecture needs rethinking
Phase 1: Root Cause Investigation
Before ANY Fix Attempt:
-
Read Complete Error Messages
- Full stack traces
- Error codes
- Related warnings
-
Reproduce Reliably
- Minimal reproduction case
- Consistent steps
- Document environment
-
Gather Evidence
- Logs before/after failure
- State at failure point
- Related system behavior
Phase 2: Pattern Analysis
Compare States:
- What worked before?
- What changed since?
- What's different in working cases?
Example Tools:
git diff working-branch broken-branch
git log --oneline since-it-worked
git bisect start
Phase 3: Hypothesis Testing
Scientific Method:
Test Hypotheses
- Form Theory: "Bug occurs because X"
- Predict: "If X is true, then Y should happen"
- Test: Run experiment
- Evaluate: Does result match prediction?
- Iterate: Refine or reject hypothesis
Example:
Hypothesis: Empty string causes crash
Prediction: Passing empty string triggers error
Test: console.log before crash point
Result: Variable is undefined, not empty
Conclusion: Wrong hypothesis, investigate why undefined
Phase 4: Implementation
Test-Driven Fix:
- Write test reproducing bug
- Verify test fails
- Implement minimal fix
- Verify test passes
- Check for regressions
Architecture Warning:
If you've attempted 2+ fixes without success:
- STOP
- Discuss with team
- Architecture may be fundamentally wrong
- More patches won't help
Red Flags
Stop and Reset If:
- Trying "one more fix" after 2+ failures
- Not understanding why fix works
- Fix requires multiple unrelated changes
- Breaking other things to fix this
- "It works now" without explanation
Common Rationalizations
| Excuse | Reality |
|---|---|
| "Just need one more try" | You're guessing, not debugging |
| "Don't have time to investigate" | Symptom fixes take longer overall |
| "Too complex to understand" | Then how will you maintain it? |
| "Works in my environment" | That's not a fix |
Diagnostic Examples
macOS Code Signing Issue:
# Investigate keychain state
security list-keychains
# Check certificate validity
codesign --verify --verbose app.app
# Examine signing identity
security find-identity -v -p codesigning
Environment Variables:
// Log environment at failure point
console.error('DEBUG:', {
cwd: process.cwd(),
env: process.env.NODE_ENV,
path: __dirname
});
When to Use
Apply For:
- Any bug or test failure
- Unexpected behavior
- Performance issues
- Intermittent problems
Before:
- Changing code
- Adding workarounds
- Blaming external systems
- Giving up
About This Skill
This skill was created by obra as part of the Superpowers Skills Collection.
Explore the collection for complementary debugging and development workflow skills!
Four-phase debugging methodology prioritizing root cause investigation over symptom fixes to prevent cascading problems.