fix-flaky-test
Fix a flaky test
Stop the most tempting non-fix in software: re-running a test until it goes green, calling it
fixed, and shipping the bug. A flaky test fails non-deterministically — green sometimes, red
sometimes, usually worse under CI load than locally. The flake is a real signal about the
system: ordering, timing, shared state, or a leaking resource. The only acceptable resolution is to
reproduce it, name the nondeterminism, fix the cause, and prove the fix by looping the same test
under the conditions in which it failed. This guide adds the flake discipline on top of the base
implement-task rules. These are conventions the review packet inspects — nothing enforces them at
edit time.
A test that fails 100% of the time after a change is an ordinary defect — load write-fix.
Authoring new tests is write-testing. This guide stabilizes a test that already exists and
already named itself flaky.