08-debug — Claude Code skill: reproduce bugs, validate hypotheses
08-debug — a bug-fixing skill with three routes: reproduce a known failure and patch it with a test, chase an unknown cause through hypotheses, or reopen a stalled hunt.
MIT ★ 571 updated 2026-10-29
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-dev@aidd-frameworkWhat 08-debug does
The skill runs bug work down one of three paths. 01 reproduce takes a failure you already know and carries it to a fix: reproduce, write the test, patch, branch, PR. 02 debug handles the case where nothing is obvious yet: it lists hypotheses, tests each one, and keeps the confirmed cause. 03 reflect-issue is for a hunt that stalled or a patch that did not hold; it reopens the search and adds logging before anything else.
Wording picks the path. Ask to reproduce and fix, you get 01; ask why something breaks, you get 02; say you are stuck, you get 03. No silent default — with a vague request the skill asks one question first. A run follows a single action, and it opens that action's file under actions/ instead of working from the summary table.
Hypotheses go into assets/task-template.md as the debug action fills it. Diagnostic actions stop once the cause is confirmed, so no patch lands on a guess. Whatever gets fixed stays inside the reported bug; unrelated cleanups are left out.
What it helps with
- reproduce a reported bug and land a fix with a test
- trace an unexplained failure through hypothesis checks
- restart a stalled investigation with fresh logging
- track each hypothesis in
assets/task-template.md - keep a patch scoped to the single bug it targets
Example prompts for the agent
- Reproduce this bug and fix it: saving the form returns 500. Cover it with a test.
- Why does the build break after the dependency bump?
- I'm stuck. Earlier patches didn't work, so reopen this and start over.
How to install 08-debug
1Plugin marketplace
/plugin marketplace add ai-driven-dev/framework/plugin install aidd-dev@aidd-frameworkThis installs the whole aidd-dev plugin with all its skills
2Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 08-debug -a claude-code3Manually: put the files in place
~/.claude/skills/08-debug/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/08-debug/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 08-debug -a codex2Manually: put the files in place
.agents/skills/08-debug/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 08-debug -a cursor2Manually: put the files in place
.cursor/skills/08-debug/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install ai-driven-dev/framework plugins/aidd-dev/skills/08-debug2Manually: put the files in place
.github/skills/08-debug/SKILL.md1Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 08-debug -a gemini-cli2Platform CLI
gemini skills install https://github.com/ai-driven-dev/framework --path plugins/aidd-dev/skills/08-debugManually: put the files in place
.devin/skills/08-debug/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add ai-driven-dev/framework --skill 08-debug -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about 08-debug
How do I install 08-debug in Claude Code?
Use the marketplace: run /plugin marketplace add ai-driven-dev/framework first, then /plugin install aidd-dev@aidd-framework.
What does 08-debug do?
It splits bug work into three actions: reproduce with a fix, hunt the cause through hypotheses, or restart a stalled investigation. Each action has its own file in actions/.
How is debug different from reproduce?
01 reproduce is for a known failure that has to be closed end to end. 02 debug applies when the cause is unclear: it validates hypotheses and stops at the confirmed one.
Source text
SKILL.md · MIT
--- name: 08-debug description: Reproduce and fix a known bug, or find an unknown root cause by hypothesis validation. Use when the user wants to fix a bug, find why something breaks, or reopen a stuck investigation. Not for building a feature or reviewing a diff. argument-hint: bug | symptom --- # Skill: debug Diagnose and fix issues through structured hypothesis validation, root-cause analysis, and a test-driven fix. ## Actions | # | Action | When to use | | --- | --------------- | ----------------------------------------------------------------------------- | | 01 | `reproduce` | A known bug must be fixed end to end: reproduce, test-driven fix, branch, PR | | 02 | `debug` | Root cause unknown: enumerate hypotheses, validate each, confirm the cause | | 03 | `reflect-issue` | Stuck or prior fixes failed: reopen the search space, instrument logs first | Pick the one action matching the intent; never default to `01`. Triggers like "reproduce and fix" route to `01`, "why does this happen" to `02`, "I'm stuck" or "previous fixes didn't work" to `03`. Ask one question when the intent is ambiguous. Before running an action, read its file in `actions/`, not only the table or assets. ## Transversal rules - One action per run: follow only the matching action file. - Scope each fix to its bug: never bundle drive-by refactors. - Confirm the root cause before fixing; the diagnostic actions stop at a confirmed cause. ## Assets - `assets/task-template.md`: the per-hypothesis tracking file the debug action fills. ## References - `references/mermaid-conventions.md`: the project's Mermaid conventions for the action-path flowchart.
© AI-Driven Dev · MIT · ai-driven-dev/framework