codeaholicguy 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
verifyskill — 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