Fix bug

fix-bug

A symptom patched on a guess just moves the bug. The discipline isn't the fix — it's refusing to change code until you can prove the cause, and finding the real owner of the broken behaviour before you touch anything. For new behaviour use implement-feature; for a structural change, make-improvement; for the regression test itself, test-code; to open the PR, create-pr.

When this applies

A failing test, a reported bug, flaky behaviour, a crash, or an error you don't yet understand. Run the loop in order — skipping a step is how a symptom-patch ships and the bug comes back.

Write a note first

Invoke write-notes and answer this form before you change a line:

• Symptom & repro: Describe the exact observed behaviour and the smallest deterministic way to reproduce it.
• Expected vs actual: Describe what should happen instead and where exactly the two diverge.
• Root cause: Describe the cause and the evidence that proves it (a log, the data, a breakpoint) — and how you ruled out a guess.
• The owner: Describe which function or code path actually owns the broken behaviour, and how that differs from where the symptom surfaces.
• Fix & regression test: Describe the minimal change to the cause and the test that will fail on the old code and pass on the new.
• Risks & unknowns: Could this be a symptom of something deeper, or could the fix affect other callers? Describe where you might be wrong.

Gate A — before you write code

Tick every box, or N/A with a reason — an unticked box means not done.

• Note — the form above is answered and written first (write-notes).
• Intent — expected vs actual restated, and where exactly the two diverge stated, not assumed.
• Status quo — reproduced reliably: the smallest deterministic trigger, with the exact error, stack, and inputs captured — and traced to the real owner of the broken behaviour, not the first place the symptom surfaces. If you can't reproduce it, you can't know you fixed it.
• Cause proved — a specific, falsifiable hypothesis confirmed or killed on a minimized case by a log line, the real backend's logs/data, the browser console/network, or a breakpoint, before changing code. A fix on a hunch just relocates the bug.
• Blast radius — if the cause sits in shared code, the other callers are enumerated (search-codebase sweep).

Fix the cause, minimally

• Change the cause, not the symptom — the smallest change that removes it. A drive-by refactor or cleanup you noticed along the way is a separate task and a separate commit.
• Match the file you're fixing — discover its conventions and mirror them; a fix that looks foreign is a tell that you didn't read enough.

Gate B — before you call it done

Tick every box, or N/A with a reason — an unticked box means not done.

• Regression test — fails on the old code, passes on the new, and you watched it do both. This is the deliverable, not an extra.
• Sweep — every caller enumerated at Gate A is checked or explicitly ruled out (search-codebase).
• Definition of done — walk create-pr's shared checklist now, not at PR time: the surrounding suite still green, docs or error wording updated for anything a user sees.
• Observed — the fix watched working on the original repro (test-code), never a green typecheck alone.

Then take it to a clean PR with create-pr.

Patterns

• Rule out the environment before "fixing" a flaky test. CPU starvation, fake-timer sensitivity, or a mock returning a fresh object per render can all masquerade as a logic bug. A flake "fixed" by changing code that was never broken is two bugs now.
• Stuck after two honest hypotheses? Widen the lens — re-read the surrounding subsystem — or ask. Don't thrash on a third guess.