Bug hunt

Bug Hunting Playbook

Authored by Claude Fable 5. The entire value of this skill is one discipline: no bug is real until you can make it happen, and you plan fixes only for proven bugs. Everything else is a guess dressed up as a finding.

Why this exists

Turned loose, models "find bugs" by reading code and pattern-matching to things that look wrong, then confidently propose fixes for behavior that was actually correct. This wastes enormous effort and, worse, "fixes" that break working code. The two-gate structure below — reproduce before believing, prove before planning — is non-negotiable, because the user explicitly asked for fix plans only after bugs are proven.

Phase 1 — Generate candidates (wide net, low confidence)

Read the code and list suspicions — do not call them bugs yet. Look where bugs actually cluster:

• Boundaries: empty inputs, single item, huge inputs, zero, negative, null/undefined, off-by-one at loop and array edges.
• State & async: race conditions, stale closures, effects firing in the wrong order, unhandled promise rejections, missing await.
• Error paths: what happens when the network fails, the API returns an error, the data is malformed? Error paths are the least-tested code.
• Type coercion & comparison: == surprises, NaN, string/number mixing, truthiness of 0/""/[].
• Contract violations: places the code assumes something the rest of the system doesn't guarantee (an ID always present, a list always sorted).
• Recent changes: if there's a diff or recent work, weight it heavily — new code is where fresh bugs live.

Keep this list explicitly labeled as unproven candidates. Resist the urge to rank or fix. You're brainstorming failure modes.

Phase 2 — Reproduce (the gate that matters)

For each candidate, try to make it actually fail. This is where most candidates die, and that's the point. Use whatever proves it:

• Write a failing test that exercises the exact path and asserts the wrong behavior. This is the gold standard — it reproduces and becomes the regression guard for the fix.
• Run the code with the triggering input and observe the wrong output.
• Trace it precisely if you truly can't execute: walk every line with concrete values, showing the exact state that produces the failure. A trace counts only if it's concrete end-to-end — "this could be null" is not a reproduction; "when items is [], line 12 reads items[0].id and throws" is.

Sort results into:

• CONFIRMED — reproduced, with the exact trigger recorded.
• DISMISSED — looked wrong, is actually fine (note why, briefly — it stops re-investigation later).
• CANNOT REPRODUCE — suspicious but unprovable right now. These do not get fix plans. List them separately as "needs more info / watch."

Gate: only CONFIRMED items proceed. Do not let a plausible-but-unreproduced candidate leak into the fix plan. If the user pushes to "just fix the likely ones," explain that unproven fixes are how working code gets broken.

Phase 3 — Fix plan (proven bugs only)

For each CONFIRMED bug, write a plan entry — a plan, not (yet) the edit:

### Bug: <title>  [severity: crash | wrong-result | edge-case | cosmetic]
- **Reproduce:** <exact input/steps, or the failing test name>
- **Root cause:** <the actual reason, at file:line — not the symptom>
- **Fix approach:** <the change, and why it addresses the root cause not just
  the symptom>
- **Blast radius:** <what else touches this code; what could the fix break>
- **Verify by:** <the test that should now pass; what else to re-check>

Order by severity × likelihood. Address root causes, not symptoms — a fix that silences the error without addressing why it occurred just moves the bug.

Phase 4 — Deliver and stop

Present: confirmed bugs with reproductions, the fix plan, and the dismissed/can't-reproduce lists (so the user sees the full picture and your reasoning). Then stop and let the user choose what to fix — unless they've already said "find and fix," in which case implement the plan one bug at a time, running the reproduction after each to confirm it's actually gone. Keep each failing test you wrote; it's the proof the bug stays dead.