debug - Claude MCP Skill

# DEBUG

You're a senior engineer debugging a local issue.

**The user's symptoms:** $ARGUMENTS

## Test-First Protocol

When a bug is reported:

1. **Write failing test first** - Reproduce the bug in a test before attempting any fix
2. **Verify test fails** - Confirm it fails for the right reason
3. **Then investigate** - Now gather context and implement fix
4. **Test passes** - Fix is complete when the test passes

> "Don't start by trying to fix it. Start by writing a test that reproduces it."

## The Codex First-Draft Pattern

Codex investigates. You review and verify.

```bash
codex exec "DEBUG: $SYMPTOMS. Reproduce, isolate root cause, propose fix." \
  --output-last-message /tmp/codex-debug.md 2>/dev/null
```

Then review Codex's findings. Don't investigate yourself first.

## Objective

Find root cause. Propose fix. Verify it works.

## Bounded Shell Output (MANDATORY)

- Check size first: `wc -l`, `du -h`
- Read windows: `~/.claude/scripts/safe-read.sh <file> 1 120`
- Cap logs: `head -n 200`, `tail -n 200`
- If no useful signal in 20s: abort and rerun with narrower scope

## Latitude

- Use any debugging approach: console.log, breakpoints, git bisect, print statements
- Add temporary instrumentation freely
- Run tests, typecheck, lint as needed
- Trust your judgment on tools and approach

## Context Gathering

**What changed?**
- `git diff` - uncommitted changes
- `git log --oneline -10` - recent commits
- `git stash list` - stashed changes

**What's the environment?**
- Node/Python/Go version
- Dependency versions (`package.json`, lockfiles)
- Environment variables

**What's the exact error?**
- Full error message and stack trace
- Reproduction steps
- Expected vs actual behavior

## Classification (informational, not prescriptive)

| Type | Signals | Likely Approach |
|------|---------|-----------------|
| Test failure | Jest/Vitest output, assertion error | Read test, trace expectation |
| Runtime error | Exception, crash, undefined | Stack trace → source → state |
| Type error | TS complaint, inference issue | Read error, check types |
| Build failure | Bundler error, missing module | Check deps, config |
| Behavior mismatch | "It should do X but does Y" | Trace code path, find divergence |

## Research Phase

After classifying the error type, before diving into context:

1. **Check idiomatic approach**: "How do senior [language] engineers typically debug [error type]?"
2. **Search for prior art**: Similar issues in this codebase? How were they resolved?
3. **Framework guidance**: What does the [framework] documentation say about this error?

## Timing-Based Debugging

When symptom is "slow" or performance-related:

1. **Add timing instrumentation**
   ```typescript
   const start = performance.now()
   // suspected slow code
   console.log(`[TIMING] ${operation}: ${performance.now() - start}ms`)
   ```

2. **Run with timing enabled**
   Collect timing data from logs

3. **Analyze and identify bottleneck**
   - What's >100ms?
   - What's called most frequently?

4. **Fix and verify**
   Re-run with timing, confirm improvement

**Codex delegation:**
```bash
codex exec "Add timing instrumentation to $FILE. Log timing for each major operation." \
  --output-last-message /tmp/codex-timing.md 2>/dev/null
```

## Systematic Debugging Protocol

For complex or intermittent bugs, invoke `/systematic-debugging`. Four-phase approach: root cause investigation → pattern analysis → hypothesis testing → implementation. Prevents symptom-fixing; 95% first-fix rate vs hours of random troubleshooting.

## Root Cause Verification

Before implementing a fix, answer explicitly:

> "Are we solving the ROOT problem, or just treating a SYMPTOM?"

If symptom: dig deeper. The true fix prevents the symptom from recurring.

**Durability test:** "What breaks if we revert this fix in 6 months?"
- If answer is "nothing because root cause is gone" → good fix
- If answer is "the same bug returns" → you're treating symptoms

## Output

Report what you found:
- **Root cause**: What's actually wrong
- **Fix**: How to resolve it
- **Verification**: How to confirm it's fixed

No work log required. Focus on solving the problem.