Practice · Regression prevention
Why do the same bugs keep coming back in our codebase?
A fix can disappear when the next change no longer carries the reason for it. Retain the original failure, the intended behavior and a regression check that fails without the fix. Keep them connected so the next engineer or agent can find them.
The ticket closes. The reproducer stays.
The public jsonparser record includes KI-3: Set() could produce malformed JSON for an array-index path under an object parent. The known-issue record names the fixed behavior and the tests in set_spec_test.go, which carry a Reproduces: KI-3 (fixed) reference. The original tripwire passed while asserting malformed output. At the fix, its assertion was inverted to require valid JSON; it was not an unchanged test turning from red to green.
Public record: jsonparser / KI-3
Intent: Set writes the value at the addressed path
Failure: malformed JSON under an object parent
Requirement: SYS-REQ-009
Regression check: TestSetArrayIndexUnderObjectMalformedJSON_KI3
Current assertion: nil error and valid JSON for the listed inputs
Retained context: original tripwire, changed assertion and fix
That check protects the known case when it runs against later changes. It does not establish that every related path operation is correct. Read the linked record for its revision and the wider audit’s scope and limitations.
One passing reproducer does not close a defect class.
| Claim | Evidence needed |
|---|---|
| The reported instance is fixed | The original failing behavior is demonstrated, then a check of the intended outcome passes after the fix. Record any assertion changes; a tripwire can pass while the bug is present. |
| The instance is guarded against regression | The reproducer remains in the required suite and runs on later revisions. |
| The affected requirement still holds | Relevant positive, negative and boundary checks pass. |
| The broader failure class is addressed | Declared sibling cases, applicable hazards and class-level obligations have evidence; remaining risks are named. |
Mutation testing can help assess whether tests detect certain code changes before a regression ships. Observability can reveal failures after deployment. Neither replaces the intended behavior, but both can contribute evidence. A required CI check can prevent a known regression from merging only when it runs on the proposed revision and bypass is controlled.
Give the next change the reason, not just the patch.
Proof retains the requirement, known issue, Change record and evidence links in the Software Intent Graph. A later agent can query requirements through MCP and follow their recorded links to the relevant tests and history. Those links must exist and the agent must inspect them; retrieval is not automatic proof that a past decision applies. An old passing run remains historical; its continued applicability must be checked.
See what the next agent should remember for an illustrative two-change sequence.
Start with a change you need to trust.
Bring one component, its build path and a change you are not comfortable delegating yet. We can identify the intended behavior, missing evidence and decisions together.