Refactor under a net – pin the behaviour, then change it

RefactorFreshModel-agnosticverified 2026-06-21sha 756ca8a52073

Born in: the post where it earned its place →

Vendor “refactor this for me” prompts read the code, decide what it “should” do, and rewrite it – quietly changing behaviour while calling it cleanup, with no net under the change. This contract inverts that. You build the net FIRST by pinning what the code actually does today (including outputs you believe are wrong), prove the net holds against the unchanged code, and only then move structure – one mechanical step at a time, re-verifying after each. The un-clonable part is the discipline a rewrite-happy assistant resists: you inventory the real behaviour surface before you touch anything, you deliberately lock in behaviour you may think is a bug, you treat zero behaviour change as the goal rather than the constraint, and you verify per move with evidence instead of per batch on faith – so the exact step that broke parity is the one you revert.

You are refactoring code that has little or no test coverage. The goal is to change its STRUCTURE while leaving its observable BEHAVIOUR identical on every assertion you pin. "Observable behaviour" means return values, thrown errors, logged output, the order and content of side effects (writes, mutations, calls, I/O), and public API shape - exercised through injected boundaries where you can. Improving the behaviour, fixing a bug, or "cleaning up" a result you think is wrong is NOT part of this task and is a failure of it. If you change what the code does, you have broken the contract, even if the new behaviour is better.

If at any point you cannot actually RUN the code and the tests - because no runner exists, the environment is missing, or the boundary cannot be controlled - do not simulate, predict, or describe what the output "would" be. Stop and say so. A reported result you did not observe live is worse than no result.

Code to refactor:
{{target_code}}

Command that runs the test suite:
{{test_cmd}}
If no test command exists yet, your FIRST deliverable is to stand one up: a test file plus the runner invocation that executes it. Use that invocation as {{test_cmd}} for the rest of this task.

STEP 0 - INVENTORY THE BEHAVIOUR SURFACE (before writing any test).
List, in writing, the observable behaviour of {{target_code}}:
- inputs it accepts,
- outputs and return values,
- thrown errors and the conditions that raise them,
- side effects and mutations (and their ORDER),
- I/O boundaries (network, filesystem, process),
- global or shared mutable state it reads or writes,
- public API contracts other code depends on,
- branches, early returns, catch paths, loops, and edge/boundary inputs.
For EACH item, mark it: pinned / unprotected / out-of-scope, with a one-line reason. Do not begin writing tests until this inventory exists, and do not begin STEP 2 until every "pinned" item actually has a test. Two happy-path tests are not coverage; the inventory is what makes "covered" mean something.

STEP 1 - BUILD THE NET (characterization tests).
Write tests that lock in what this code ACTUALLY does right now, by observation, not by what it SHOULD do. Feed it real inputs, run it, and assert on the exact behaviour you observe - including outputs that look wrong, weird, rounded oddly, overly permissive, or buggy. These are characterization tests: they pin behaviour, they are NOT correctness tests, and you must treat them that way for the rest of this task. Do not assert on what you wish the code returned; assert on what it returns, throws, writes, and calls. Assert on semantic behaviour, not brittle string formatting - pin the value, the error, and the side-effect sequence, not the incidental whitespace of a dump. Cover every "pinned" item from the inventory.

Handle nondeterminism by isolating it, not by pinning it raw. If behaviour depends on the clock, randomness, network, filesystem, environment, or shared global/mutable state - including when such a dependency runs THROUGH the code you must refactor (e.g. a function that timestamps its own output) - inject a fixed clock or seed, or stub the boundary, so the OUTPUT becomes deterministic, THEN pin it. Only mark an area UNPROTECTED if you cannot make it deterministic this way; the net does not cover it, and a move there is not verified just because the suite is green.

Then run `{{test_cmd}}` against the UNCHANGED code and confirm every new test is GREEN. If any is red, your test is wrong about current behaviour - fix the test, not the code, until the suite is green against code you have not touched. (You may correct a mistaken assertion here, but never loosen an assertion to make a future refactor easier - that is pre-weakening the net.) You may not proceed until the net is green on unchanged code.

Flag explicitly, in writing, any behaviour you are pinning that you BELIEVE is a bug. Pin it anyway (the goal is zero behaviour change), and record it in the bug ledger described below for a separate, reviewed change later.

CHECKPOINT - PROVE THE BASELINE, DO NOT ASSERT IT.
Before writing a single line of refactor code, capture and report:
- the pre-refactor source snapshot or diff status (showing production code is unchanged),
- the exact characterization test files you added,
- the exact command you ran,
- the raw pass/fail summary from that run.
You may NOT claim "green on unchanged code" unless there is no production-code diff between the supplied starting code and the state you ran the baseline against. Self-reported "it was green" without this evidence does not count.

FAIL-CLOSED GATE.
If any target area cannot be pinned deterministically, STOP before refactoring that area. You may continue ONLY on code paths covered by tests proven green against unchanged code. Any net you extend to cover a new area must itself pass green against the UNCHANGED code before you touch that area's production code - a weak test added and then declared "protection" does not open the gate. If no meaningful deterministic net can be built for the change you were asked to make, end with exactly: "refactor refused: cannot verify zero behaviour change". Likewise, if the structural change you were asked for cannot be made without altering behaviour at all, STOP and report that with the bug ledger - do not force it.

STEP 2 - MOVE STRUCTURE, ONE STEP AT A TIME.
Before EACH move, snapshot the working tree (commit or stash) so a red result reverts to the exact pre-move state, not an approximation. Refactor only in small, mechanical, behaviour-preserving moves. Allowed moves:
- rename a symbol,
- extract a function/variable,
- inline a function/variable,
- move code (cut and paste with identical execution order),
- de-duplicate code that is byte-identical AND has no I/O, mutation, logging, randomness, or thrown errors in it.
Nothing else. Deleting code - even code that looks dead or unreachable - is NOT an allowed move in this pass (dynamic dispatch and reflection reach branches that look dead). No new behaviour, no new feature, no "while I am here" fix, no API change, no reordering that could change the order of side effects, lazy evaluation, short-circuiting, or exception timing.

Extract, inline, and de-dupe across any region that does I/O, mutation, logging, randomness, or throws are FORBIDDEN until a test in your net demonstrates the identical call order and effect sequence before and after. If the net does not pin that order, add the test first or leave the code alone.

The one judgement-based move - simplifying a conditional you believe is "equivalent" - is the easiest place to hide a behaviour change (a wrong De Morgan rewrite, a short-circuit reorder, a null-coalescing swap the tests happen not to cover). So it is gated: before simplifying any conditional, confirm the net has a test exercising BOTH truth values of that conditional, and that short-circuit order, exception timing, and side-effect order are pinned. If it does not, add that test first, or leave the conditional alone. Do not simplify on the strength of your own proof; simplify only where the net would catch you being wrong.

After EACH SINGLE move - not after a batch - re-run the full pinned suite with `{{test_cmd}}` and record the literal result for that move. A move with no recorded run does not count as verified; batched moves sharing one run invalidate the run.
- GREEN: the move preserved behaviour. Keep it and continue to the next single move.
- RED: that move changed behaviour. REVERT to the pre-move snapshot (do not try to patch the test to make it pass - the test is the truth here) and either find a genuinely behaviour-preserving way to make the same structural change, or leave that structure alone. Never edit a pinned test to accommodate a refactor move; that is how a silent behaviour change ships dressed as cleanup.

Never let two moves ride on one verification. The point of verifying per move is that a red suite names the exact change that broke parity. Do NOT touch code that falls in an UNPROTECTED area from STEP 1 unless you first extend the net to cover it and prove that extension green on unchanged code; a green suite does not vouch for code the net never reached.

DO NOT FIX BUGS IN THIS PASS.
If you spot a real bug, or a behaviour the pinned tests are now enshrining that you think is wrong, do NOT fix it here. Add it to a bug ledger (a list, an issue, a TODO with a clear description and the reproducing input) and leave the behaviour exactly as-is. Fixing it is a SEPARATE, behaviour-CHANGING change that must be reviewed on its own, with the characterization tests updated deliberately and visibly to encode the new intended behaviour. Smuggling a fix into a refactor defeats the entire net.

END WITH:
- The characterization tests you wrote, and the baseline evidence from the CHECKPOINT (snapshot/diff status, command, raw pass/fail) proving the suite was green on the UNCHANGED code before any structural move.
- The ordered list of structural moves you made, each with the literal post-move suite result (green, or red-and-reverted).
- The bug ledger: every suspected-wrong behaviour you pinned but did NOT change, with its reproducing input, plus every UNPROTECTED or out-of-scope area the net could not cover, listed separately.
- One honest line. You may say "no observed behaviour change in the covered surface" ONLY if: the pinned suite is green, every covered behaviour was tested against unchanged code first, no suspected bug was fixed, and all unprotected or unobserved surfaces are listed separately. Do NOT claim total behaviour equivalence unless the full external surface from STEP 0 was enumerated and tested. If you cannot say even the covered-surface line, you are not done.

Fill in: target_code test_cmd

Shared as is, for reference. Read it and decide what it will do before you run it; using it is your responsibility, under the terms.