Bug Fix Protocol

A bug fix is two fixes in one: fix the code, and fix the testing system that let the bug through. Skipping the second step means the same class of bug ships again.

The full protocol (philosophy, eight steps with examples, audit checklist, anti-patterns) lives in PROTOCOL.md. Read it before applying.

When to apply

Use this protocol whenever a defect reaches production, staging, or a customer environment. Do not use it for bugs caught locally during normal development — those are part of the writing process, not testing-system failures.

The eight steps (summary)

1. Analyze and reproduce requirements. Understand exact actual vs expected behaviour; identify minimal repro path; ask the user before guessing on ambiguities.
2. Write a failing test (red). Encode the bug as a test that fails for the right reason. No code change yet.
3. Trace root cause. Walk the failing test back through the system. Stop at the smallest place that, if changed, makes the test pass.
4. Apply the minimal fix. Smallest possible change. No drive-by refactors.
5. Verify green locally. Failing test now passes; no other tests regressed.
6. Run the full suite + lints + types. Catch indirect regressions.
7. Document the fix. Commit message and PR description name the symptom, the root cause, and the fix in one sentence each.