systematic-debugging

Systematic Debugging

A structured approach to debugging that ensures consistent, reliable bug fixes with verification.

When to Use

Use this skill when:

• Encountering unexpected behavior or errors
• Investigating failing tests
• Debugging production issues
• Analyzing performance problems

The 4-Phase Framework

Phase 1: Reproduce the Issue

Goal: Create a minimal, reliable reproduction

Steps:

1. Identify the exact conditions that trigger the issue
2. Create a minimal test case or script
3. Verify you can reproduce it consistently
4. Document the reproduction steps

Evidence Format:

REPRODUCTION:
Environment: [OS, runtime version, dependencies]
Steps:
1. [step 1]
2. [step 2]
3. [step 3]
Expected: [what should happen]
Actual: [what actually happens]

Best Practices:

• Isolate the problem - remove unrelated code
• Use logging/debugging to narrow scope
• Check if issue is deterministic or intermittent
• Note any error messages, stack traces, or logs

Phase 2: Analyze Root Cause

Goal: Identify why the issue occurs

Steps:

1. Trace execution flow from reproduction
2. Examine relevant code with file:line references
3. Identify the specific line/condition causing the issue
4. Determine the underlying cause

Analysis Template:

ANALYSIS:
file:line - [description of problematic code]
ACTUAL: [what the code does]
EXPECTED: [what it should do]
ROOT CAUSE: [wrong input | wrong order | missing dep | config | logic | external]

EVIDENCE:
- [evidence point 1 with file:line]
- [evidence point 2 with file:line]
- [evidence point 3 with file:line]

Investigation Techniques:

• Binary search (comment out code to isolate)
• Check recent changes (git blame, git log)
• Compare with working version
• Review documentation/API specs
• Check for race conditions/timing issues
• Verify assumptions with assertions

Phase 3: Implement Fix

Goal: Apply minimal, targeted fix

Steps:

1. Design the simplest possible fix
2. Implement the fix with minimal changes
3. Consider edge cases
4. Add/update tests if applicable