Skip to main content

Debugging skill

Structured Debug Skill

Guide debugging with expected behavior, reproduction, root cause analysis, and validation.

On this page

Install command

AI DevKit installs its built-in skills as one curated set. Run this once to install dev-debug with the rest of the built-in workflow skills.

bash
npx ai-devkit@latest skill add --built-in

What it does

Use dev-debug when diagnosing regressions, incidents, failing tests, or unclear production behavior. It pushes the agent to gather evidence, identify likely causes, and agree on a fix plan before changing code.

When to use it

  • Investigate a failing behavior before jumping to a patch
  • Create a clear root-cause hypothesis and validation plan
  • Debug incidents, test failures, and regressions with less guesswork

Supported agents

  • Claude Code
  • Codex
  • Cursor
  • opencode

The SKILL.md file

This is what your agent reads when the skill runs. View it on GitHub (opens in a new tab)

Debug with an evidence-first workflow before changing code.

Hard Rule#

  • Do not modify code until the user approves a selected fix plan.

Workflow#

  1. Clarify
  • Restate observed vs expected behavior in one concise diff.
  • Confirm scope and measurable success criteria.
  • Before investigating, search for similar past incidents: npx ai-devkit@latest memory search --query "<observed behavior>" --tags "debug,root-cause"
  1. Reproduce
  • Capture minimal reproduction steps.
  • Capture environment fingerprint: runtime, versions, config flags, data sample, and platform.
  1. Hypothesize and Test For each hypothesis, include:
  • Predicted evidence if true.
  • Disconfirming evidence if false.
  • Exact test command or check.
  • Prefer one-variable-at-a-time tests.
  1. Plan
  • Present fix options with risks and verification steps.
  • Recommend one option and request approval.

Validation#

  • Confirm a pre-fix failing signal exists.
  • Confirm post-fix success using the verify skill — including regression verification for bug fixes.
  • Summarize remaining risks and follow-ups.
  • Store root cause and fix for future sessions: npx ai-devkit@latest memory store --title "<root cause>" --content "<diagnosis and fix>" --tags "debug,root-cause"

Task Tracing#

If task tracing is usable, choose a short kebab-case debug task name when no task name exists, then use task optionally: record repro/final results as evidence, the current hypothesis as next, and blockers only when they materially affect progress. Never block debugging because task tracing is unavailable.

Red Flags and Rationalizations#

RationalizationWhy It's WrongDo Instead
"I already know the cause"Assumptions skip evidenceReproduce and prove it first
"This is urgent, just fix it"A wrong fix wastes more time10 minutes of diagnosis saves hours
"The fix is obvious from the stack trace"Stack traces show symptoms, not causesTrace backward to the root cause

Output Template#

Use this response structure:

  • Observed vs Expected
  • Repro and Environment
  • Hypotheses and Tests
  • Options and Recommendation
  • Validation Plan and Results
  • Open Questions
esc