Systematic Debugging

Source: obra/superpowers

Overview

This skill provides a structured approach to debugging that prevents random guessing and ensures problems are properly understood before solving.

4-Phase Debugging Process

Phase 1: Reproduce

Before fixing, reliably reproduce the issue.

Reproduction Steps

1. [Exact step to reproduce]
2. [Next step]
3. [Expected vs actual result]

Reproduction Rate

• Always (100%)
• Often (50-90%)
• Sometimes (10-50%)
• Rare (<10%)

Phase 2: Isolate

Narrow down the source.

Isolation Questions

• When did this start happening?
• What changed recently?
• Does it happen in all environments?
• Can we reproduce with minimal code?
• What's the smallest change that triggers it?

Phase 3: Understand

Find the root cause, not just symptoms.

Root Cause Analysis

The 5 Whys

1. Why: [First observation]
2. Why: [Deeper reason]
3. Why: [Still deeper]
4. Why: [Getting closer]
5. Why: [Root cause]

Phase 4: Fix & Verify

Fix and verify it's truly fixed.

Fix Verification

• Bug no longer reproduces
• Related functionality still works
• No new issues introduced
• Test added to prevent regression

Debugging Checklist

Before Starting

• Can reproduce consistently
• Have minimal reproduction case
• Understand expected behavior

During Investigation

• Check recent changes (git log)
• Check logs for errors
• Add logging if needed
• Use debugger/breakpoints

After Fix

• Root cause documented
• Fix verified
• Regression test added
• Similar code checked

Common Debugging Commands

Recent changes

git log --oneline -20 git diff HEAD~5

Search for pattern

grep -r "errorPattern" --include="*.ts"

Check logs

pm2 logs app-name --err --lines 100

Anti-Patterns

❌ Random changes - "Maybe if I change this..." ❌ Ignoring evidence - "That can't be the cause" ❌ Assuming - "It must be X" without proof ❌ Not reproducing first - Fixing blindly ❌ Stopping at symptoms - Not finding root cause