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. For user-flow bugs, make the repro a dev-smoke check that fails before the fix and passes after.
• 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.
• Offer dev-retro to prevent recurrence; run only if the user agrees.
• 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