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/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:

• 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/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.