Repair, Wrap, Replace, Rewrite, or Archive

Repair, Wrap, Replace, Rewrite, or Archive is the decision every other chapter in this book either prepares for or executes. It is taken once, early, on evidence rather than instinct, and it is written down with the condition that would reverse it. Getting it wrong is not fatal. Taking it implicitly is.

Key takeaways

• There are five outcomes, not three. Repair in place, wrap behind an interface, strangler-fig replace, full rewrite, and archive. The two the usual argument omits, wrapping and archiving, are the two that most often save the most money.
• Each outcome has a threshold you can test against evidence from the first three weeks: whether seams exist, whether the boundary is stable, whether anyone is using the thing at all, and whether you know the requirements better than the code.
• The assessment is time-boxed to two weeks. A decision process that runs longer than the smallest option it is choosing between has stopped being a decision and become a delay with a meeting attached.
• The outcome is per component, not per system. Most stalled deliveries resolve into a mixed answer, and a single verdict for the whole codebase is usually a sign the assessment was rushed.
• Write the decision down with the evidence and the reversal condition. An undocumented decision gets relitigated every time delivery gets hard, which is the state the delivery is already in.

Read this beside Chapter 3, which produced the why column this decision is checked against, and Chapter 7, which is where the choice gets presented to the people paying for it. If the shape of the target system is the open question rather than the fate of the current one, System Design for Developers is the companion argument.

Three weeks in, someone will call a meeting to settle this, and two people will arrive having already settled it. The engineer who has been reading the payment module wants a rewrite, and can describe the new architecture in detail. The founder wants stability first and features by the quarter, and has a customer commitment behind it. Both positions are sincere. Neither is evidence.

What nobody in that room has budgeted for is the cost of finding out.

Three options is the wrong number

The argument people arrive with has three positions: rewrite it, refactor it, or replace it with something bought. That framing is not wrong so much as truncated, and the truncation is expensive, because the two outcomes it drops are the cheap ones.

The five that actually exist are repair in place, wrap behind an interface, strangler-fig replace, full rewrite, and archive. Wrapping means leaving the existing implementation alone and putting a stable interface in front of it, so that everything new is written against the interface rather than against the mess. Archiving means establishing that a component has no users worth the cost of keeping it, and removing it. Neither of those is a compromise between the other three. They are different decisions with different evidence behind them.

Notice what naming three options does to a room. It trains everyone present to argue about degree, from conservative to radical, along a single axis. Then the answer gets chosen by temperament, and temperament is distributed by role. The person who will do the work wants the rewrite. The person paying for it wants the repair. A five-way choice breaks that axis, because wrapping and archiving do not sit anywhere on it.

The threshold that selects each outcome

Each outcome is selected by a condition you can check, not by a preference you can defend. The evidence for every one of them was gathered in the first three weeks.

The table resolves the argument in the meeting only if the evidence exists. That is the actual reason the first three chapters come first. A decision matrix given to a team that has not done the reading becomes a vocabulary for the same argument.

Wrapping is the option nobody proposes

Wrapping loses the meeting because it is unsatisfying to everyone in it. It does not make the code better and it does not promise a new system. What it does is buy optionality, which is the thing a stalled delivery has none of.

The patterns for this are named and documented. Cartwright, Horn and Lewis published Patterns of Legacy Displacement in March 2024, and the useful ones here are Event Interception, where you capture the events flowing into the old system so new components can consume them, and Legacy Mimic, where the new system behaves in a way that keeps the old one satisfied while ownership moves. Their framing of the first step is the part worth stealing: agree the outcome the organisation actually wants before choosing a technique. They observe that different parts of an organisation routinely hold different views of that outcome, which is precisely what the meeting three weeks in reveals.

A wrap is also the move that makes the other outcomes cheaper later. Once traffic flows through an interface you control, replacing what sits behind it becomes a routing change rather than a migration. That is the mechanism behind Martin Fowler's strangler fig application, updated in August 2024, in which a new system grows around the old one and gradually takes over. His warning about the alternative is blunt: simple replacement plans go down in flames most of the time, because capturing everything the existing system does is harder than it looks.

So wrapping is not a way of avoiding the decision. It is often the first move of the decision you are going to make anyway, taken in the order that costs least.

Archiving is a delivery, not an admission

Every stalled system contains something nobody uses. A reporting module built for a customer who left. An admin panel replaced by a spreadsheet. An integration with a partner the business stopped working with, still running nightly, still failing occasionally, still generating alerts somebody has learned to ignore.

Removing those is the highest-return work available in week four, and it is almost never proposed. It reads as failure. Nobody gets credit for deleting a feature, and the person who built it may be in the room. The engineering case is simple in a way the political case is not: every component you keep has to be understood, tested, deployed, monitored and paid for, and a component with no users pays none of that back.

Establish disuse with evidence rather than opinion. Access logs over a full billing cycle, so monthly and quarterly jobs are visible. Database read patterns, not just writes. A named owner who will say in writing that the loss is acceptable. Then remove it behind a flag first, leave it dark for one cycle, and delete it when nobody notices. That sequence turns an irreversible act into a reversible one for the cost of a week.

Getting this wrong has a shape worth naming. The dangerous case is not the module with zero traffic. It is the one with almost none, where the remaining consumer is a regulator, an auditor, or a single large customer whose contract nobody has read.

The rewrite threshold, stated so it can fail

The rule from Chapter 3 was that a rewrite is defensible only when you know the requirements better than you know the code. Here it becomes a test with a procedure.

Take the why column. Count the filled cells against the total, and count how many people remain who can close a blank one. Then take the requirements: not the roadmap, but the behaviours the system must have, written down and confirmed by someone with the authority to confirm them. If the requirements document is thin and the why column is filling, you do not have a rewrite. You have impatience with a plan attached.

Peter Naur's own conclusion pushes the other way, and honesty requires keeping it in view. He argued that where a program's theory is genuinely dead, the text should be discarded and the problem solved afresh, at no higher and possibly lower cost. That condition is real. It is also narrow: no one left who holds the theory, and no recoverable reasons in the text. Check the condition before borrowing the conclusion.

Against it sits Joel Spolsky's argument from April 2000, written about Netscape, that rewriting from scratch is the single worst strategic mistake a software company can make, because the discarded code contains every production fix ever made to it. Twenty-six years later the specifics are dated and the mechanism is not.

You will also meet a statistic in this argument, quoted confidently, that some large share of rewrites fail or are cancelled. I have looked for its source and cannot find one. It is not in this book, and I would rather lose the rhetorical point than carry a number I cannot trace. What can be said with a source is narrower and more useful: Flyvbjerg and Budzier, studying 1,471 IT projects in 2013, found a mean cost overrun of 27% with a fat tail, one project in six overrunning cost by 200%. A rewrite is a new project, so it inherits that distribution rather than escaping it.

Time-box the assessment to two weeks

An assessment with no deadline expands until it costs more than the smallest option it is choosing between. Two weeks, starting when the why column is half filled.

Week one produces the component inventory: what exists, who uses it, how often it changes, and where the seams are. Week two produces a proposed outcome per component, each with its selecting condition, the evidence for it, and the cost of being wrong. Both weeks run alongside the stability work in Chapter 5, because a system that is on fire will not hold still for a study.

The output is one page per component and a single summary page. Not a slide deck. A document with the evidence attached, because the audience for it is not only the people in the room now. Six months from now, when the third option looks obvious in hindsight, the document is what distinguishes a decision that was made from an opinion that prevailed.

Expect the summary to be mixed. Repair the billing module, wrap the integration layer, archive two admin features, and defer the rest. A rescue that produces one verdict for an entire codebase has usually assessed nothing, and the shape of that mistake is visible in the meeting: it is fast, unanimous, and about the system as a whole.

What the decision has to survive

Two things will attack the decision, and both are predictable.

The first is delivery pressure. The moment a customer commitment slips, someone will reopen the choice, because reopening it feels like action. The defence is the reversal condition, written when the decision was taken: the specific observation that would change the answer. If that observation has not happened, the answer has not changed, and the conversation moves to Chapter 7 where it belongs.

The second is the payback horizon. Martin Fowler's argument from May 2019 is that internal quality pays back in weeks rather than years, and that there is almost no runway on which trading quality for speed makes sense. That cuts both ways here. It undercuts the case for indefinite repair of something with no users, and it undercuts the case for a rewrite justified by a payback nobody has estimated. If the outcome you chose cannot state when it starts paying back, it is not finished being chosen.

Chapter summary

The fate of a stalled system resolves into five outcomes rather than the three people argue about, and the two that get dropped, wrapping and archiving, are the two that most often save the most money. Each outcome is selected by a condition that can be checked against evidence already gathered: seams and a filling why column select repair, a stable boundary around an unmaintainable interior selects a wrap or a strangler-fig replacement depending on whether traffic can be routed per capability, an absence of users selects archiving, and only requirements known better than the code select a rewrite. Wrapping is unsatisfying in the room and usually correct, because it buys optionality and makes every later move cheaper, which is the mechanism behind both Event Interception and the strangler fig. Archiving is a delivery rather than an admission, established with access logs across a full billing cycle and a named owner, and made reversible by going dark before going away. The rewrite threshold is stated so that it can fail, with Naur's narrow condition on one side and Spolsky's Netscape argument on the other, and with no unsourced failure rate quoted in place of the Flyvbjerg and Budzier distribution that a new project genuinely inherits. The assessment itself is time-boxed to two weeks and produces one page per component, with the answer expected to be mixed. The decision is written down with its evidence and its reversal condition, because the two forces that will attack it, delivery pressure and an unstated payback horizon, both arrive on schedule.

The decision is now taken, and nothing has been repaired. Chapter 5 is Stability Before Features: how to stop the bleeding while the business is still asking for the roadmap it was promised, why an indefinite feature freeze fails politically before it fails technically, and how an error budget turns the argument about shipping into an arithmetic one.