---

name: debug version: 1.0.0 changelog: Initial debug skill with systematic diagnosis description: Diagnose bugs systematically before proposing fixes. Use when something is broken, failing, erroring, or not working as expected. allowed-tools: Read, Grep, Glob, Bash, Task temperature: 0.2 # Mostly systematic, slight exploration

Debug Phase

Diagnose systematically before proposing fixes.

Task

$ARGUMENTS

Instructions

Output: ## Debug Phase

State: At phase start, update STATE.md:

• Set task: from $ARGUMENTS (if STATE.md is idle/complete or task is "None")
• Set phase: debug
• Set status: in_progress

1. Reproduce

• Confirm the failure exists
• Identify exact error message/behavior
• Note environment conditions (versions, config, state)

2. Isolate

• Narrow to smallest reproducible case
• Identify which component fails
• Trace information flow to failure point
• Use targeted reads/greps, not broad exploration

3. Hypothesize

• List possible causes (most likely first)
• For each: what evidence would confirm/reject?
• Consider: recent changes, dependencies, environment

4. Test Hypotheses

• Gather evidence systematically
• Update hypothesis ranking as evidence arrives
• Stop when root cause is confirmed

5. Produce Diagnosis

Use the diagnosis template:

## Symptom
[What's failing — exact error or behavior]

## Root Cause
[Why it's failing — the actual problem]

## Evidence
- `file:line` — observation
- Command output — what it showed

## Fix Options
1. Option A: [approach] — tradeoffs
2. Option B: [approach] — tradeoffs

## Recommended
[Which option and why]

Context Budget

• Target: complete diagnosis under 30% context
• Use subagents for exploration if needed
• Keep evidence concise — excerpts, not full files

6. Checkpoint

Update STATE.md incrementally:

• Set phase: debug
• Add root cause and fix decision to ## Decisions
• Add investigated files to ## Key Files
• Update ## Next Steps with recommended fix

Run /checkpoint if context is heavy or taking a break.

Constraints

• Do not fix yet — diagnosis first
• If fix is obvious (<5 lines, isolated), may proceed with approval
• Otherwise, get approval before implementing
• Don't guess — verify with evidence

Exit Criteria

Root cause identified with evidence. Fix approach clear and approved.

Gate: "Here's the diagnosis. Approve fix approach?"