Most rewrites fail at the border. The new system works. The old system works. The migration between them is hand-waved as “data work” until it becomes the project.
That is backwards. For replacement projects, the migration plan is the feature. Users do not care that the new table is cleaner. They care that their old invoices, permissions, saved filters, exports, and weird historical states still make sense on Monday.
Plan the crossing
A migration plan needs:
- A mapping. Every old state has a destination, including the embarrassing ones.
- A rehearsal. Run it on a copy and record the exceptions.
- A rollback story. Know which writes are reversible and which are not.
- A customer-visible receipt. Users should know what changed and what did not.
The dangerous sentence is “we will clean that up during migration.” Migration is when unknowns are most expensive.
Build the bridge before you celebrate the new shore. Otherwise the old system remains load-bearing forever, and the rewrite becomes a second system you also have to maintain.