# /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:
   ```bash
   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:
   ```javascript
   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

```markdown
## 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
```javascript
// Wrong: not awaiting
doAsyncThing();
useResult(); // result not ready

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

### Null Checks
```javascript
// Wrong: assumes existence
user.profile.name

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

### Off-by-One
```javascript
// Wrong: includes length
for (let i = 0; i <= arr.length; i++)

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