007-before-the-rewrite.md
What I want to know before a rewrite
Frustration with existing code needs to become a specific case for replacing it.
I understand the appeal of a rewrite. Reading unfamiliar code is tiring, especially when a small change requires understanding several years of decisions. Starting again offers the prospect of choosing names and boundaries that make sense immediately.
That feeling deserves some scrutiny before it becomes a project plan. The existing system contains behaviour people depend on, including behaviour nobody thought to put in the requirements. Replacing the code means deciding which of those details to preserve and finding a way to discover the ones we have missed.
Name what has become difficult
I want a specific account of the problem. Perhaps releases require coordinated changes across the application. Perhaps a dependency prevents a necessary upgrade. Perhaps a calculation is so entangled with the interface that nobody can test it independently.
Those are different reasons to intervene. They also suggest different first steps. Moving a calculation behind a clearer boundary may help immediately and create a place to compare old and new results. Replacing the interface first could leave the difficult calculation exactly where it was.
The comparison matters to me because a rewrite needs evidence that it is improving the part we set out to improve. A cleaner repository is satisfying. The team also needs to know whether changing a business rule has become safer, or whether a release now requires fewer people to coordinate.
Plan for the overlap
If replacement is justified, I want to see how the transition works. Which part moves first? How do we compare behaviour? When can we retire the old path? For systems that store data, the plan also needs to explain where changes go while both versions exist.
That overlap is part of the estimate. So is the work of finding exceptions in the old system. Leaving those questions until the replacement is built puts the most uncertain work at the point when everyone expects the project to be nearly finished.
I am comfortable recommending a rewrite when the case supports one. I want the proposal to explain how we will move a real workflow and remove what it replaces. Finishing that first transition gives the team a better basis for estimating the next one than a plan built entirely around an empty repository.