Structured Debug

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

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

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

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

• 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