Rewrite decision
Score the constraints before choosing the strategy
No single factor decides the answer. Use a representative journey to test whether the existing system can be changed safely and whether a replacement can preserve behavior.
Product knowledge
Measure how well current behavior and exceptions are understood.
- Refactor signal
- Reliable tests and known rules
- Rewrite signal
- Core model contradicts required product
- Uncertainty
- Important behavior exists only in production
Boundary quality
Locate coupling around identity, data and providers.
- Refactor signal
- Interfaces can be introduced incrementally
- Rewrite signal
- Critical invariants cannot be expressed safely
- Uncertainty
- Hidden shared state and side effects
Operational continuity
Preserve users, data and service while change occurs.
- Refactor signal
- Small reversible deployments
- Rewrite signal
- Current runtime cannot meet non-negotiable need
- Uncertainty
- No migration or rollback rehearsal
Team capability
Match the strategy to people who can own it after launch.
- Refactor signal
- Maintainers understand current stack
- Rewrite signal
- Supported target reduces key-person risk
- Uncertainty
- Choice follows tool familiarity alone
Economic evidence
Compare total transition and ongoing cost.
- Refactor signal
- Thin slice reduces recurring change cost
- Rewrite signal
- Replacement proves materially lower risk or cost
- Uncertainty
- Estimate excludes migration and dual operation
Operating principle
Rewrite decisions should begin with one migrated journey
A representative thin slice exposes the real constraints: data compatibility, identity, deployment, testing and team learning. It also produces a usable improvement even if the larger strategy changes.
Choose a journey with meaningful boundaries but bounded consequence. Implement the new seam, route a controlled population, compare behavior and preserve a rollback path.
- Inventory current behavior
- Preserve data semantics
- Run old and new paths deliberately
- Stop when evidence contradicts the plan
Applied example
Decision example: rewrite for a new framework
The team proposes a complete rewrite because the generated frontend is inconsistent. The backend contracts and data model are stable, and most defects are in presentation and state handling.
- The core product model does not require replacement
- A design-system and state-boundary refactor can be incremental
- A full rewrite would recreate working integrations
- One redesigned journey can test the hypothesis
Plain answers
Questions to resolve before shipping
When is a full rewrite justified?+
When non-negotiable requirements cannot be reached safely through incremental change and a tested migration path supports the replacement case.
Can we pause features during a rewrite?+
That is a business decision, but long freezes create divergence and delayed learning. Incremental replacement often reduces that risk.
How do we avoid repeating the same problems?+
Write product invariants, architecture decisions, acceptance tests and operational requirements before selecting the replacement design.