| name | debug |
| description | Root-cause a bug or a failed fix with evidence, not guesses - brainstorm causes, research them in parallel, confirm one with logs before changing code. Use when a reported behavior needs root-causing or a fix attempt has failed. |
Debug with evidence, not guesses
A plausible-looking cause is not enough. Turning a symptom into a fix by pattern-matching wastes a commit and loses trust. Confirm the real cause with evidence before you edit code.
- Brainstorm causes. List several plausible root causes (more for a hard bug, fewer for an obvious one). Do not commit to the first idea.
- Research in parallel. When the causes sit in different areas, spawn one subagent per area (a subagent is a separate agent you launch with the Agent tool) to trace that suspected code path and report whether it can actually produce the reported behavior. This keeps the files they read out of your own context. Give each subagent one focused question.
- Rank the causes, most likely first. Order the surviving causes by how well they fit the evidence so far.
- Confirm one with targeted logs, in that order. For the top cause, add a log line (or a breakpoint, or a small test) that would prove or disprove it, run the failing path, and read the output. Move to the next cause only after the current one is disproven. Never change logic on a theory you have not confirmed.
- Match the fix to the confirmed cause. Fix exactly what the evidence points to. If the change you want to make does not address the confirmed symptom, say so and ask first; do not slip a "nice-to-have" in as a bug fix.
- Broaden if every theory fails. The same symptom can come from outside the obvious code: a stale browser cache or a stale CDN copy (
marked loads from the esm.sh CDN, and both JSON fetches and markdown-to-HTML results are cached in Map objects and by the browser), generated SEO artifacts out of sync with data/ (sitemap.xml and the <!-- BEGIN GENERATED:... --> blocks in index.html and web-projects/index.html; regenerate with bun scripts/generateSitemap.js and bun scripts/generateSeoBlocks.js, see root ADR 0010), stale localStorage state in a web-project (root ADR 0007), no stale compiled output to suspect since this repo has no build step, and less-obvious code paths. Keep investigating; do not stop at the first dead end.
Remove the logs you added once the cause is confirmed.
