Skip to main content

/debugging

Source: ~/.claude/skills/debugging/SKILL.md

name: debugging description: Systematic debugging workflow for finding and fixing issues. Use when user reports a bug, tests are failing, or unexpected behavior occurs. Walks through reproduce → isolate → investigate → hypothesize → test → fix → document.

Debugging

Systematic debugging workflow for finding and fixing issues.

When to Use

  • When user reports a bug
  • When tests are failing
  • When unexpected behavior occurs

Process

Phase 1: Reproduce

  1. Get exact steps to reproduce
  2. Identify expected vs actual behavior
  3. Note any error messages verbatim

Phase 2: Isolate

  1. Find the smallest reproducible case
  2. Identify which component/file is involved
  3. Check recent changes to that area: 
    git log --oneline -10 -- [file]
git diff HEAD~5 -- [file]

Phase 3: Investigate

  1. Read the relevant code
  2. Trace the execution path
  3. Add strategic logging if needed: 
    console.log('[DEBUG] functionName:', { input, state });
  4. Check for common issues:
    • Null/undefined values
    • Off-by-one errors
    • Async timing issues
    • Type mismatches
    • Missing error handling

Phase 4: Hypothesize

List possible causes ranked by likelihood:

  1. [Most likely cause]
  2. [Second possibility]
  3. [Third possibility]

Phase 5: Test Hypothesis

For each hypothesis:

  1. Make minimal change to test
  2. Verify if it fixes the issue
  3. Verify it doesn't break other things

Phase 6: Fix

  1. Implement the fix
  2. Remove debug logging
  3. Add test to prevent regression
  4. Document root cause

Output Format

## Debug Report: [issue description]

### Reproduction
- Steps: [numbered steps]
- Expected: [what should happen]
- Actual: [what happens]

### Root Cause
[Explanation of why the bug occurred]

### Fix Applied
[Description of the fix]
- File: [path:line]
- Change: [what was changed]

### Prevention
- [ ] Added test: [test name]
- [ ] Related areas checked: [yes/no]

### Verification
- [ ] Bug no longer reproduces
- [ ] Existing tests pass
- [ ] No new issues introduced

Common Patterns

Async Issues

// Wrong: not awaiting
doAsyncThing();
useResult(); // result not ready

// Right: await
await doAsyncThing();
useResult();

Null Checks

// Wrong: assumes existence
user.profile.name

// Right: optional chaining
user?.profile?.name

Off-by-One

// Wrong: includes length
for (let i = 0; i <= arr.length; i++)

// Right: excludes length
for (let i = 0; i < arr.length; i++)
Back to top