Rewrite or upgrade? A decision framework with five questions

Every team with an aging system has the argument eventually. Half the room wants to burn it down and start clean. The other half says rewrites always fail. Both camps are partly right, which is why the argument never ends.

Rewrites do fail often enough that "upgrade by default" is a sensible starting position. But it is a default, not a law. Sometimes the existing system really is the wrong foundation, and pretending otherwise just means paying for a slow rewrite in installments.

Here are five questions that move the decision from opinion to evidence. Answer them in writing, with the people who run and maintain the system in the room.

1. Is the problem the code, or the shape of the product?

If your pain is "this framework is old and the build is slow," that is a code problem. Upgrades fix code problems.

If your pain is "we sell a different thing now and the data model assumes the old one," that is a product-shape problem. Upgrading the framework underneath will not change the fact that your core entities are wrong. Teams that confuse these two end up either upgrading a system that still does not fit, or rewriting one whose only issue was a stale dependency.

A useful test: list the five changes you most want to make to the product in the next year. If most of them are blocked by the data model or architecture rather than by tooling, lean toward rewrite or at least a heavy rework of the core.

2. Does the system's behavior contain knowledge you cannot afford to lose?

Old systems encode years of edge cases: the tax rule for one region, the partner who sends malformed files, the discount that exists because of one contract. Much of it is undocumented and lives only in the code.

A rewrite has to rediscover all of it. Underestimating this is the classic reason rewrites run long. If the knowledge is valuable and poorly documented, you can either extract it first (characterization tests are one way, and we wrote about that separately) or favor an upgrade that preserves it by construction.

If instead the old behavior is mostly accidental and you would happily drop half of it, that tilts toward rewrite.

3. Can the business keep shipping while you do this?

Upgrades can usually be sliced into steps that each ship. A rewrite often cannot, because for a long stretch you maintain two systems, and every feature request lands in both or waits.

Ask honestly: how long can you tolerate feature freeze or double maintenance? If the answer is "not long," a big-bang rewrite is dangerous. The middle path is incremental replacement, often called the strangler approach, where you route one slice of functionality at a time to new code while the old system keeps running. It is slower to start, but it keeps value flowing and gives you an exit at every step.

4. How far is the runway to support?

Look at the actual end-of-support situation, not the vibes. Is your framework or runtime still receiving security fixes? Is there a documented, step-by-step upgrade path? Frameworks that publish upgrade guides for each major version make upgrading a bounded problem.

Where no sensible upgrade path exists, for example the platform is discontinued, the language ecosystem has moved on and key libraries are unmaintained, or the vendor has gone, upgrading may mean porting anyway. At that point you are choosing between a port and a rewrite, and a rewrite informed by the old system's behavior is a legitimate option.

5. Do you have the people to do either one well?

A rewrite needs people who understand the domain deeply and can make architecture decisions that will hold. An upgrade needs people who are patient, test-minded and comfortable with unglamorous work.

If the only people who understand the domain have left, a rewrite is riskier than it looks, because you lose the one asset that would guide it. If your team is small and fully loaded with feature work, either path needs outside capacity. Be realistic about which skills are actually available, not which you wish you had.

Reading your answers

| If your answers look like this | Lean toward | |---|---| | Tooling pain, valuable undocumented behavior, must keep shipping, clear upgrade path | Upgrade | | Product has changed shape, data model blocks most roadmap items | Rewrite or heavy rework of the core | | No viable upgrade path and platform effectively dead | Port or rewrite, informed by old behavior | | Mixed answers | Incremental replacement of the worst parts |

Tally it, but do not treat it as arithmetic. One answer can dominate. A discontinued platform settles the matter regardless of how the other four come out.

When a rewrite is genuinely right

Since this post is meant to be honest, here are the cases where we would say rewrite without hesitation:

• The system is small. Rewriting something a couple of engineers can rebuild in weeks costs less than a careful upgrade plan.
• The core architecture contradicts what the product now needs, such as single-tenant code that must become multi-tenant at its foundation.
• The platform is end of life with no practical migration route.
• The codebase is so tangled that the cost of understanding it exceeds the cost of re-specifying the behavior from users and data.

Even then, the rewrite should be scoped, tested against the old system's behavior and cut over in stages where possible.

A cheap way to settle a stuck debate

If you cannot decide, run a short, time-boxed spike on each side. Try upgrading one module by one version and see what breaks. Try re-implementing one real feature in the proposed new stack and see how much of the old behavior you had to rediscover. Two weeks of evidence beats two months of opinion.

Both spikes also give you an honest first estimate. If you want one, our write-up on estimating a modernization before you talk to a vendor walks through a method.

Getting a second opinion

We are a new studio, delivering through a lead and vetted senior engineers, and we would rather tell you a rewrite is wrong for you than sell you one. If you want to pressure-test your five answers, book a free 30-minute Triage. If you want a quick first look at your stack before that, the instant check takes a few minutes.