The Friendly Rewrite
A rewrite framed as cleanup becomes a long-running replacement with no stable landing zone.
- Also known as
the big bang rewritethe clean slate trapv2 syndromethe eternal rewrite
- First noticed by
tech leadarchitectsenior engineer
- Mistaken for
- good engineering hygiene
- Often mistaken as
- responsible modernization
Why it looks healthy
Concrete external tells that make the pattern read as responsible behavior.
- The new system uses current frameworks and cleaner patterns
- Architecture diagrams look tidier than the old code
- Leadership hears the words modernization, scalability, and debt reduction
- Morale is visibly higher on the rewrite side of the team
Definition
What it is
Blast radius code delivery team business
A full or near-full rewrite justified by pain in the current system, but without a disciplined migration strategy.
How it unfolds
The arc of the pattern
-
Starts
The current system is painful. Everyone agrees. A clean slate feels rational, overdue, even virtuous.
-
Feels reasonable because
The existing mess is real, and a rewrite promises clarity, speed, and fewer compromises.
-
Escalates
Parallel systems appear. Scope expands. The new system is always almost ready while the old one remains mission-critical.
-
Ends
The team maintains two worlds, trust declines, and leadership eventually asks why nothing meaningful shipped.
Recognition
Warning signs by stage
Observable signals as the pattern progresses.
EARLY
Early
- We should rebuild this properly.
- The old system is too messy to change safely.
- No one can describe what will be migrated first.
MID
Mid
- Two systems run in parallel for months.
- Net-new scope gets added before parity is reached.
- Delivery dates keep moving but optimism stays strangely intact.
LATE
Late
- The old system still receives urgent fixes.
- Nobody can define done in plain language.
- The team has lost confidence in both systems.
Root causes
Why it happens
- Pain in the current system is real
- Migration strategy is weak or absent
- Teams underestimate hidden behavior in existing systems
- Ambition grows faster than discipline
- Leadership likes the symbolism of a fresh start
Response
What to do
Immediate triage first, then structural fixes.
First move
Name the rewrite as a rewrite in writing, and stop framing it as cleanup.
Hard trade-off
Accept that some of the new system will be thrown away, or accept that the old system will outlive the migration by years.
Recovery trap
Launching a second rewrite to fix the first rewrite.
Immediate actions
- Freeze net-new scope until migration strategy is explicit
- Define smallest valuable slice to replace first
- Write down exit criteria for each migrated area
Structural fixes
- Use strangler migration patterns
- Make cutover milestones concrete and testable
- Track parity, usage, and retirement explicitly
What not to do
- Do not let the rewrite absorb unrelated improvements
- Do not treat morale as evidence of viability
AI impact
How AI distorts this pattern
Where AI-assisted workflows accelerate, hide, or help with this failure mode.
AI can help with
- AI can help inventory legacy behavior, map dependencies, generate migration checklists, and summarize hidden code paths.
AI can make worse by
- AI can accelerate the wrong rewrite by generating scaffolding and broad rewrites faster than the team can validate architecture and migration risk.
Relationships
Connected patterns
Causal flows inside Failure Modes, and related entries across the site.
Easy to confuse with
Nearby patterns and how this one differs.
-
Migration debt is about unfinished prior moves. The friendly rewrite is a new move whose endpoint was never defined.
- Adjacent concept Regular refactoring work
Refactoring preserves behavior and scope. The friendly rewrite expands scope while the old system stays live.
-
Abstraction addiction adds layers inside one system. The friendly rewrite builds a parallel system.
Heard in the wild
What it sounds like
The phrase that signals the pattern is about to start, and who tends to say it.
We'll rewrite it properly this time.
Said bytech lead or architect
Notes from practice
What experienced people notice
Annotations from engineers who have worked this pattern before.
- Best momentWhen intervention actually changes the trajectory.
- Before the rewrite becomes the default answer
- Counter moveThe specific action that breaks the pattern.
- Replace one slice, prove one cutover, retire one dependency.
- False positiveWhen this pattern is actually the correct call.
- Some rewrites are justified; the failure mode is not rewriting, but rewriting without disciplined displacement.