Rebuild or repair: triaging a platform that has stopped absorbing change

The conversation arrives in a recognisable form. A platform that once shipped weekly now takes a quarter to change anything. Estimates have stopped being believable. Every release breaks something unrelated. The team, asked what they would do, says rebuild — and they are frustrated enough to mean it.

That frustration is real evidence and should not be dismissed. But it is evidence of a symptom, and the same symptom is produced by causes with wildly different price tags. A rebuild costs a year and carries the risk that the replacement inherits the same problem, because the cause was never named. Before committing, four questions are worth answering honestly.

1. Is the data model wrong, or is the code just untidy?

This is the question that decides it, and the two are constantly confused.

Untidy code is expensive to work in and cheap to improve. It can be refactored incrementally, module by module, while the system keeps running and the business keeps getting features. There is no point at which everything must be correct simultaneously. Frustrating, unglamorous, and entirely survivable.

A wrong data model is different in kind. If the entities do not match how the business actually reasons about its work — if a concept the business treats as one thing exists as three unrelated records, or three distinct things share one overloaded table — then every feature fights the model, and every workaround makes the next one harder. That does not refactor away, because the model is what everything else is built on.

Untidy code is a tax. A wrong model is a ceiling. Only one of them justifies starting again.

The test is not aesthetic. Take the three changes the business most wants next and trace, concretely, what each would require. If the answer is repeatedly "we would have to change what this record means," the model is the problem. If the answer is "it is tedious but obvious," it is not.

2. Can the system tell you what it is doing?

A platform nobody can observe cannot be safely changed, and this is frequently the actual cause of slow delivery. If a defect in production takes two days to diagnose, engineers become cautious; cautious engineers batch changes; batched changes are riskier; riskier changes justify more caution. The loop tightens until a quarter is the natural unit of delivery.

This is worth checking before any rebuild decision, because it is comparatively cheap to fix and it changes the diagnosis. Structured logging, tracing across service boundaries, meaningful health checks and error reporting can often be added in weeks. Teams routinely discover afterwards that the system was never as bad as it felt — it was merely opaque, and opacity feels identical to fragility from the inside.

3. What is the deployment path?

Ask how long it takes to get a one-line change into production, and how it is reverted. The answer is diagnostic out of all proportion to its apparent significance.

If a deploy takes an afternoon, involves manual steps, and cannot be reversed quickly, then the cost of every change includes a fixed overhead and a risk premium, and no amount of code quality will remove them. This is also among the cheapest things to fix, and fixing it usually reveals how much of the perceived legacy problem was really a delivery problem.

4. Who understands it, and are they still here?

The least technical question and often the most decisive. If the only person who understood a critical subsystem left two years ago and nothing was written down, then the code is not merely legacy — it is unknown. Changing it means reverse-engineering behaviour under production risk, which is slow and frightening and rightly so.

Note that this is not solved by a rebuild. A replacement has to reproduce behaviour nobody can describe, including the undocumented rules that quietly matter to somebody. The genuinely useful first step is characterisation: write tests that capture what the system does today, before anyone changes or replaces it. Those tests are the specification, and they are valuable on either path.

What the answers usually add up to

In practice most platforms that feel unmaintainable are suffering from questions two, three and four — poor observability, a painful deployment path, and lost knowledge — rather than question one. Those three are fixable in months, in place, without stopping delivery, and fixing them makes the underlying code quality problem tractable rather than overwhelming.

When question one is genuinely the answer, a rebuild is warranted, and then the sequencing matters more than the technology. The pattern that works is strangling rather than replacing: put a routing layer in front, move one bounded capability at a time, run both systems against each other while traffic shifts, and keep the reversible path available at every stage. A big-bang cutover of a system nobody fully understands is the highest-risk shape this work can take, and it is the shape most often proposed.

The question behind the question

One last reframing. "Should we rebuild?" is usually standing in for something more specific: we want to do something the current system cannot do, and we are trying to work out what it costs. Asked that way, the answer is frequently narrower and cheaper than a rebuild — extract the one capability that is blocked, leave the rest alone, and revisit in a year with better information and a system that is easier to reason about than it was.

That is a less satisfying answer than starting again with a clean sheet. It is also, most of the time, the one that gets the business what it actually wanted this year rather than next.