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