Replace the old shape with the simpler shape the codebase would want if it were\ndesigned today. Refactoring is not adding a compatibility layer beside the problem;\nit is moving ownership until every concept has exactly one clear home. That cuts\nboth ways: merging N duplicated owners into one, and splitting one over-loaded\nmodule into the several owners it was hiding.
\nEvery line is debt — the best mechanism is the one you don't write.\nBefore building any guard, validator, convergence protocol, or cleanup\npath, two checks gate it:
\nMeasure the change, and treat a bad size-to-behaviour ratio as a shape\ndefect. Before accepting a change, count what it actually cost — production\ncode apart from tests and docs, and comments apart from logic, because a\ndiff dominated by explanation is not the same as one dominated by machinery:
\ngit diff --numstat <base> -- ':!specs' ':!*.test.*' ':!**/test-harness'\nThen read the added lines, not just the total. A small behavioural change\nthat costs a large number of lines is a red flag — it is the most reliable\nsignal that the fix is fighting the existing shape rather than fitting it:\na special case layered where the general case belongs, a second owner\nintroduced beside the real one, or a wrapper bridging two things that should\nhave been merged. The correct response is to rework it from the shape the\ncode would want, not to commit it with a paragraph explaining why it had\nto be big; that explanation is the smell, not the mitigation.
\nTwo honesty rules, or the number means nothing: formatter churn in files the\nchange did not otherwise touch is not part of the change and must stay out of\nthe commit; and a net count near zero can still hide real weight — a new\ncron, table column, index, endpoint, dependency, or config flag is a surface\nsomeone now owns and maintains, so name those separately from the count.
\nDo not over-weigh the sunk cost of the existing architecture. \"It already\nexists and works\" is not an argument for keeping a shape — coding agents make\nlarge architecture switches cheap, so size a refactor by the quality of the end\nstate, not by the volume of code it replaces. When behavior must survive, pin it\nwith tests at the consumer surface and swap the architecture underneath — though\nmost of the time even the old seams shouldn't survive verbatim: a big refactor is\nthe chance to redraw them into the shape the codebase would want today, not to\nfaithfully rebuild the old interfaces on a new foundation.
\nPrefer one shared primitive over N adapters. An adapter is acceptable only at an\nexternal boundary or as a short-lived migration seam.
\nSplit a module that owns too many concepts — decomposition is refactoring\ntoo. The dual of merging duplicates: when one file or function has accreted\nunrelated responsibilities, divide it along ownership seams so each piece owns a\ncoherent slice a reader can name and the original thins to composition. Past\n~1000 lines a file is a smell, not a verdict — some modules earn their size (a\ncohesive state machine, a generated table, one algorithm with tight internal\ncoupling), but a god-file that registers dozens of routes or handles many domains\ninline is accreted responsibility, not cohesion. The split is right only when\neach new module owns a nameable responsibility and import pressure drops because\ndependencies moved with it; it's wrong when it's line-count relief that scatters\none concept across files a reader must reassemble.
\nKnow what already exists before you build something new. Before writing a\nnew mechanism — a shape, computation, asset, state machine, data contract —\nsearch the codebase for one that already does this, or something close enough\nto share. Only once you know what's there can you make the real decision:\nreuse it, consolidate two near-duplicates, or extract the shared core into an\nindependent module both call — and that decision belongs before you start,\nnot bolted on after. Reuse is not automatically the answer; the existing thing\nmay be wrong, or genuinely different, and then you build new deliberately. The\nfailure this prevents is building in ignorance of what's already there: two\nimplementations that must agree then silently drift, each re-deriving details\nthe other already settled (orientation, units, edge cases, ordering).
\nDo not preserve dev-only compatibility by default. Unshipped scaffolding should\nmove to the clean contract immediately.
\nZero lineage signaling: name things for what they are, never for where they\ncame from. A name that encodes history — a slice file prefixed with the\nmega-file it was split from, foo-v2/foo-new/foo-legacy, a module named\nafter the experiment that produced it, a wrapper named after the API it\nreplaced — carries no information to a reader who wasn't there, and actively\nmisleads the one who was once the old thing is gone. The test: would someone\nwho joined today, knowing nothing of the history, choose this name? If the\nname only makes sense with the backstory, rename it; history lives in git,\nnot in identifiers. The same rule kills lineage comments (\"previously this\nwas...\", \"moved from X\") — they describe the diff, not the code, and rot the\nmoment the referent disappears.\nRenaming is routine maintenance, not a separate project or a reason to ask for\npermission. Do it proactively at whatever scale the consumers require; a large\nmechanical diff is not a reason to retain a misleading name. Distinguish internal\nidentifiers from persisted keys and external contracts: retain the latter only\nfor an identified consumer, under the compatibility rule above. Do not leave\ninternal aliases that preserve the old vocabulary.
Prefer the idempotent contract over the refusal. When an operation can be\nasked for twice — a retry after a lost response, a user clicking the same\nbutton again, a replayed webhook — reaching the requested end state should\nsucceed, not error. \"Install X\" where X is already installed at the place it\nbelongs is a success: return the thing. Refusal is correct only when the\nsecond request means something genuinely different from the first — a\nDIFFERENT thing already occupies the name, so honoring the request would\ndestroy or shadow it. The tell that you have it backwards: a caller has to\nspecial-case your error code to recover normal behavior, or a retry path\nneeds a pre-flight \"does it already exist?\" read that races. Applies beyond\nwrites: deletes of absent things, unsubscribes, and \"mark complete\" toggles\nare all idempotent by nature, and making them 404 or 409 pushes bookkeeping\nonto every caller.
\nConstrain the model to what production actually writes. A schema that\npermits more than any writer produces — a list where every flow stores one\nelement, a state nothing reaches — taxes every consumer with the general\ncase. The tell: a consumer asking \"but which one?\" when the data can only\ncontain one. Enforce the constraint at the write path; widen when a real\nuse arrives.
\nMake ownership visible in stats, tests, or debug output when divergence was the\nbug class.
\nA check that RE-DERIVES a value the code already computes will drift from\nit. A test or second consumer that recomputes geometry, state, or a derived\nquantity independently can disagree with the code over a difference invisible\non paper — an operation-order or rounding subtlety — and fire false verdicts.\nExport the owner's computed value and have the check consume that, so it\nenforces exactly what the code produced: one owner for the computation, not two\nthat happen to mostly agree.
\nA symmetric or featureless placeholder can hide an orientation or coordinate\nbug in the thing it stands in for. A symmetric stand-in renders the same\nwhether or not the coordinate frame is flipped, so the defect stays invisible\nuntil a real asymmetric asset exposes it. When you swap a placeholder for the\nreal asset, re-verify orientation and framing, not just that it renders.
\nUpdate the spec or handoff with the new invariant, not the mechanical file list.
\nIf the refactor starts widening into unrelated behavior, slice it: land the shared\ncontract first, then port consumers in reviewable passes.
\n