Skip to main content
skill CX Codex

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

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add ai-driven-dev/framework
/plugin install aidd-dev@aidd-framework
Open on GitHub

What 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-framework

This 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-code

3Manually: put the files in place

~/.claude/skills/08-debug/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/08-debug/

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

Similar skills

All skills for Testing and QA →

From the same set80

The whole set →
02-pull-request 02-pull-request collects changes from the current branch and opens a draft pull or merge request. Use it when you want a review request prepared without publishing it as ready. CX Codex +1 ★ 571repo stars 02-user-stories 02-user-stories turns an epic, product brief or PRD into ordered user stories with acceptance criteria, then checks whether they are ready to build. CX Codex +1 ★ 571repo stars release-video release-video plans scenes for newly shipped features and renders an announcement video with background music and UI audio. CX Codex +1 ★ 571repo stars 01-acceptance-qa 01-acceptance-qa is a Claude Code skill that checks browser-visible behavior against acceptance criteria and records evidence videos. It verifies changes that have already been reviewed. CX Codex +1 ★ 571repo stars executor executor turns an approved task scope into working, validated code. Useful when a spec needs implementation without planning drift or self-judging. CX Codex +1 ★ 571repo stars 02-backlog The 02-backlog skill guides product backlog work, from sorting incoming requests to checking artifact relationships. Use it to review, order, or refine backlog items. CX Codex +1 ★ 571repo stars 01-usage 01-usage is a Claude Code skill that reports token use by period or task, split by day, model, agent or ticket, from a local aidd telemetry report. CX Codex +1 ★ 571repo stars 01-sdlc 01-sdlc orchestrates changes from contract framing to a draft pull request across Frame, Deliver, and Check zones. Use it for end-to-end tasks instead of single-step code edits. CX Codex +1 ★ 571repo stars

Project sponsors

Companies that keep this analytics open