codeaholicguy/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"

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