Our review

Systematically diagnose bugs before proposing fixes, following a six-step process.

Strengths

Clear, reproducible structure for debugging.
Encourages hypothesis testing with evidence.
Prevents premature fixes by separating diagnosis from implementation.

Limitations

May be overly rigid for trivial or obvious bugs.
Requires prior understanding of the project context.

When to use it

Use this skill when a bug is reported and you need a methodical approach to find the root cause.

When not to use it

Do not use it when the fix is obvious and immediate, or for tasks that are not debugging.

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?"

Systematic Debugging

Recommended for