fix-bug

Fix a bug — reproduce, isolate, fix the cause, guard

A bug fix is a claim: "this behaviour was wrong, and now it is right." The only proof a reviewer can check is a test that fails on the old code for the reported reason and passes on the new. Debugging is a search, so run it like an experiment: one hypothesis, one change, one observation at a time.

Steps

1. Extract the facts; distrust the diagnosis. From get_ticket, write down the input, the expected result, the actual result, the environment, and how often it happens. The reporter's theory of the cause is a hint, not a conclusion. Call search_lore for known gotchas in this area — many bugs are a documented gotcha resurfacing.
2. Reproduce it before changing anything. Drive the failing path with a scratch test or a command until you SEE the wrong behaviour. Then shrink the reproduction: remove inputs, steps and setup until removing one more makes the bug disappear. A minimal reproduction usually points straight at the cause.
   • Intermittent / "sometimes loses data" / "500 under load": assume shared state. Reproduce deterministically — fire two concurrent calls at the same resource (a barrier or Promise.all), fix the clock with a fake timer, or pause one party past a timeout (a lock holder that stalls past its lease). Guessing at a race is not a fix.
   • "This used to work": find the introducing commit with git bisect start <bad> <good> then git bisect run <test command> (keep the reproduction script untracked inside the worktree, never outside it — the hook blocks writes there; untracked files survive each bisect checkout — and delete it before your git add -A commit, or it ships in the diff). Always finish with git bisect reset and check git branch --show-current is the delivery branch again — the runner fails a delivery left on any other HEAD. The introducing diff names the cause.
3. Write the regression test first. Encode the minimal reproduction as a permanent test at the lowest level that exposes it (unit for a function, integration if it needs the wiring). Name it after the behaviour, not the ticket number. Run it and confirm it FAILS for the reported reason — the assertion about the wrong result, not an import error, a missing fixture, or a timeout. Keep that output; it is half your evidence.
4. Find the cause, not the symptom. Trace from the failing assertion back to the decision the code got wrong: a missing guard, an off-by-one boundary, an unhandled state, a non-atomic read-modify-write, a stale assumption about an API. Form one hypothesis, change one thing, re-run. If a change does not move the result, revert it before trying the next — stacked speculative edits hide the real fix.
5. Fix minimally. Change only what the cause requires (the minimalism skill). A try/catch that hides the error, a special case for the reporter's exact input, or a retry around a race is a symptom patch, not a fix.
6. Look for siblings. grep for the same call, the same boundary arithmetic, the same unguarded shared write. Fix identical instances only if they are the same bug; list the others as findings in your evidence rather than widening this diff.
7. Prove it. Run the regression test (now passes), then the surrounding suite and lint once. For a concurrency or timing bug, run the new test in a loop (for i in {1..20}; do <cmd> || break; done) — a single green run proves nothing about a race.
8. Guard the class. If a type, assertion, or validation would have made this bug impossible, add it when it is small and in the same code.