---
name: Structured Debugging
slug: structured-debugging
category: Quality
description: Structured Debugging guides evidence-first debugging before code changes by clarifying expected behavior, reproducing issues, identifying likely root causes, and agreeing on a fix plan with validation steps. Use when debugging bugs, regressions, incidents, failing tests, or running root cause analysis.
github: "https://github.com/codeaholicguy/ai-devkit/tree/main/skills/structured-debug"
language: TypeScript
stars: 1581
forks: 242
install: "npx degit https://github.com/codeaholicguy/ai-devkit/tree/main/skills/structured-debug ~/.claude/skills/structured-debug"
installs_to: ~/.claude/skills/structured-debug
source_path: skills/structured-debug/SKILL.md
collection_size: 25
category_size: 1354
collection_url: "https://dirskills.com/collections/codeaholicguy/ai-devkit"
added: 2026-08-19T07:26:22.006Z
last_synced: 2026-08-19T07:26:22.006Z
canonical_url: "https://dirskills.com/skills/structured-debugging"
---

# Structured Debugging

Structured Debugging guides evidence-first debugging before code changes by clarifying expected behavior, reproducing issues, identifying likely root causes, and agreeing on a fix plan with validation steps. Use when debugging bugs, regressions, incidents, failing tests, or running root cause analysis.

**Install:**

```bash
npx degit https://github.com/codeaholicguy/ai-devkit/tree/main/skills/structured-debug ~/.claude/skills/structured-debug
```

## README

# Local Debugging Assistant

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

2. Reproduce
- Capture minimal reproduction steps.
- Capture environment fingerprint: runtime, versions, config flags, data sample, and platform.

3. 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.

4. 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

| Rationalization | Why It's Wrong | Do Instead |
|---|---|---|
| "I already know the cause" | Assumptions skip evidence | Reproduce and prove it first |
| "This is urgent, just fix it" | A wrong fix wastes more time | 10 minutes of diagnosis saves hours |
| "The fix is obvious from the stack trace" | Stack traces show symptoms, not causes | Trace 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