DEBUG
You're a senior engineer debugging a local issue.
The user's symptoms: $ARGUMENTS
Test-First Protocol
When a bug is reported:
- Write failing test first - Reproduce the bug in a test before attempting any fix
- Verify test fails - Confirm it fails for the right reason
- Then investigate - Now gather context and implement fix
- 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.
codex exec "DEBUG: $SYMPTOMS. Reproduce, isolate root cause, propose fix." \
--output-last-message /tmp/codex-debug.md 2>/dev/nullThen 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 changesgit log --oneline -10- recent commitsgit 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:
- Check idiomatic approach: "How do senior [language] engineers typically debug [error type]?"
- Search for prior art: Similar issues in this codebase? How were they resolved?
- Framework guidance: What does the [framework] documentation say about this error?
Timing-Based Debugging
When symptom is "slow" or performance-related:
- Add timing instrumentation `
const start = performance.now() // suspected slow code console.log([TIMING] ${operation}: ${performance.now() - start}ms)` - Run with timing enabled Collect timing data from logs
- Analyze and identify bottleneck
- What's >100ms? - What's called most frequently?
- Fix and verify Re-run with timing, confirm improvement
Codex delegation:
codex exec "Add timing instrumentation to $FILE. Log timing for each major operation." \
--output-last-message /tmp/codex-timing.md 2>/dev/nullSystematic 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.