| name | debug |
| description | Reproduce a bug, capture evidence to a cleared log, propose 2-3 fix options for the human to pick, implement, validate by re-running the repro, and add a regression test. Use when given a bug report, a Jam URL, a stack trace, asked to "debug", "fix this bug", "why is X broken", or chasing flaky behavior. |
Debug
Reproduce → diagnose → propose → fix → validate → guard. Never propose a fix you haven't reproduced. Never claim a fix without re-running the repro against a cleared log.
Produces
docs/bugs/{slug}.md using templates/bug.md. Evidence in tmp/debug/{slug}.log and tmp/debug/{slug}--{before,after}.png (gitignored).
Pick {slug} as kebab-case from the symptom — e.g. login-button-stuck-loading.
Reads
Whatever the user gives: bug report, Jam URL, error message, stack trace, screenshot. If repro details are missing, ask before doing anything else.
Steps
1. Reproduce
Pick the channel that matches the surface, and write all output to tmp/debug/{slug}.log:
- UI bug: Chrome DevTools MCP per
rules/visual-check.md. Capture list_console_messages + list_network_requests after the failing action; screenshot to tmp/debug/{slug}--before.png.
- API/endpoint bug:
curl the failing request with -i. Append status, headers, body.
- Backend bug: start the dev server with
run_in_background, trigger the bug, append the relevant stdout slice.
If you cannot reliably reproduce, stop and tell the user. You do not yet understand the bug.
2. Document
Write docs/bugs/{slug}.md from templates/bug.md. The reproduction steps must be precise enough that a teammate could follow them cold.
3. Instrument (only if needed)
If the captured logs don't explain the cause, add narrow console.log/server log statements at the suspected boundaries. Re-run the repro and append new evidence. Revert the instrumentation diff before the fix commit.
4. Propose 2-3 fix options
Draft 2-3 distinct approaches with tradeoffs (root-cause vs. workaround, blast radius, effort). Use AskUserQuestion so the human picks. Do not implement before the answer.
5. Implement
Apply the chosen fix. Keep the diff minimal — debug is not refactor. Per rules/scope-first.md, log adjacent-cleanup ideas to the bug doc; do not pick them up here.
6. Validate (with cleared log)
- Delete
tmp/debug/{slug}.log
- Re-run the exact repro from step 1
- Inspect the fresh log + screenshot
If the bug signature is gone, mark validation pass in the doc and capture --after.png. If it persists, loop back to step 3 with what changed appended to the doc.
7. Regression test
Per rules/tdd.md bug-fix clause: write a failing test that reproduces the bug, then confirm it passes after the fix. Reference the test path in the bug doc.
Skip only for pure visual/copy/config bugs (per rules/tdd.md).
NOT
- Does not propose a fix before a reliable reproduction. No repro = no diagnosis.
- Does not validate by reading code. Validation = re-run the repro against a cleared log.
- Does not refactor adjacent code. Minimal change. Anything else is a separate task.
- Does not skip the regression test for behavioral bugs.
- Does not commit the temporary instrumentation from step 3.
