The Regression Net
Before you replace the system nobody understands, record what it actually does.
The incident
The legacy pricing engine had no documentation, no tests, and one maintainer who'd retired. The rewrite matched the spec perfectly — the spec, it turned out, was fiction. The old system had twelve years of undocumented exceptions baked in, each one a customer promise somebody once made. The new system broke them all at once, correctly, according to a document nobody had followed since 2013.
Why the obvious approach fails
Legacy systems drift from their documentation until the behavior *is* the specification — every quirk load-bearing, every exception a promise. Rebuilding from the written spec reproduces what the system was supposed to do, and breaks what it actually does, which is what the business runs on. The only trustworthy spec is recorded reality: capture real inputs and outputs at the boundary, freeze them as an executable test net, and hold the replacement to byte-level parity — with every intentional difference reviewed as a decision, because each one is a customer-visible change someone must own.
The standard
- Before replacement work begins, boundary traffic is captured: real inputs, real outputs, sampled across time to catch periodic behavior (month-end, year-end, edge dates).
- The capture becomes an executable golden-master suite — the replacement runs the same inputs and diffs the outputs.
- Divergences are triaged explicitly: match required, or intentional-change with a named owner and a business sign-off. There is no third category.
- The net runs continuously during parallel operation (with the Strangler Fig), so drift between old and new is caught in hours, not at cutover.
- The suite outlives the migration as the new system's regression floor.
How Cortex validates it
At plan time
replacement Missions require a capture plan (boundaries, sampling windows, edge-period coverage) before build starts.
At validation
assert: golden_master.coverage includes edge_periodsassert: output_divergence → (match_fixed | signed_intentional_change)assert: unreviewed_divergences == 0 at cutoverAssertion syntax is illustrative.
At review
the approver sees the parity report: N recorded scenarios, match rate, and every intentional divergence with its sign-off attached.