The Rewrite is the decision to throw away working software and build it again from scratch, based on the conviction that the problems of the current system are so fundamental that incremental improvement is impossible and only a clean start can produce the correct architecture — a conviction that has been wrong every single time it has been held, by every single developer who has held it, since the invention of the second program.
The Rewrite is not a technical decision. It is an emotional one. It is the feeling that the current codebase is too messy, too tangled, too legacy, too someone else’s to be saved. The feeling is real. The conclusion is wrong. The codebase can be saved. It can be saved one small safe step at a time, the way a neglected house is saved not by demolition but by fixing the plumbing, then the wiring, then the roof, then painting — each step leaving the house habitable, each step leaving the house slightly better.
But demolition is exciting. Demolition is a decision. Demolition is a developer standing before a whiteboard with a blank canvas and the intoxicating belief that this time, with everything they know now, they will build the perfect system.
They will not. They will build V3. V3 will take eighteen months instead of three. V3 will fight windmills. V3 will end with File → New and a subfolder called “reference — do not delete” containing the only code anyone looks at, which is V2.
“V3 served its purpose — to teach us what NOT to do. V4 rises from these learnings. Clean. Boring. Solid.”
— The V3 Saga Final Chapter - Is It Fun To Fight Windmills
The Pattern
The Rewrite follows a trajectory so predictable it could be automated:
-
The Frustration — A developer encounters a bug. The bug is in a part of the codebase that is old, undocumented, and written by someone who left. Fixing the bug requires understanding the code. Understanding the code requires reading it. Reading it produces the thought: “This is terrible.”
-
The Diagnosis — The developer concludes that the code is not merely buggy but fundamentally wrong. The architecture is wrong. The abstractions are wrong. The naming is wrong. The entire approach is wrong. The only fix is to start over.
-
The Pitch — The developer presents The Rewrite to the team / manager / CTO. The pitch contains the phrase “technical debt” (see Technical Debt), the phrase “clean architecture,” and the promise that The Rewrite will take three months. The three months is calculated by estimating how long it would take to build the system if you already knew everything, which you don’t, which is why V1 took two years.
-
The Honeymoon — The first two weeks are glorious. The new codebase is clean. The tests pass. The architecture is beautiful. The developer has not yet encountered any of the problems that made the old codebase ugly, because the new codebase does not yet do anything.
-
The Discovery — Month three. The new codebase must now handle the edge cases that made the old codebase ugly. The edge cases are not bugs — they are requirements that were discovered in production, encoded in
ifstatements that looked like tech debt, and are now being rediscovered from scratch at a cost of one month per edge case. -
The Sunk Cost — Month nine. The Rewrite is at 73% completion. It has been at 73% completion for four months. The remaining 27% turns out to contain 80% of the complexity. The developer cannot go back — too much has been invested. The developer cannot go forward — the last 27% is the reason the old code was ugly.
-
The Convergence — Month eighteen. The Rewrite ships. It is slower than the old system. It has different bugs. It does not handle three edge cases that the old system handled perfectly. A developer opens the old codebase in the “reference” subfolder and quietly copies an
ifstatement that they had called “tech debt” twelve months ago. Theifstatement works. It had always worked. -
The Amnesia — Six months later, a new developer joins the team. They encounter a bug. The bug is in a part of the codebase that is old, undocumented, and written by someone who — wait.
The V3 Saga
The most extensively documented Rewrite in the lifelog is the V3 Saga — twenty-three episodes of reactive signal frameworks, component namespacing battles, and the slow-motion discovery that a sports car cannot plow a field.
V2 worked. V2 had worked for two years. V2 was an HTMX application that sent HTML from the server and let the browser display it. The server sent HTML. The browser said “okay.” There were no loading states because nothing needed to load. The architecture was boring. The architecture was correct.
Then someone said: “Now let’s do it right.”
V3 arrived with reactive signals, web components, SolidJS evaluations, component lifecycle management, and the conviction that two years of boring success was merely a prologue. Twenty-three episodes followed. The episodes are preserved in the archives. They are not a cautionary tale — they are twenty-three cautionary tales, each one confirming what Gall’s Law and The Second System Effect predicted, and each one being confirmed in real time by a developer who knew both laws and rewrote anyway.
The recovery was not a refactoring. V3 was beyond therapy. The recovery was File → New, with V2 and V1 open in a subfolder. Copy what works. Delete what you don’t need. Refactor what remains. V4 shipped in forty-eight hours.
“We lived two years without loading states.”
— The confession, The V3 Saga Final Chapter - Is It Fun To Fight Windmills
V4 looked like V2. V4 was not V2. V4 was V2 with the knowledge of V3, which is the only thing V3 produced that had value: the knowledge of what not to do.
Why It Feels Necessary
The Rewrite’s seductive power lies in a cognitive illusion: the current codebase’s problems are visible, while the new codebase’s problems are theoretical.
You can see the old code’s tangled dependencies, its inconsistent naming, its eighteen-line if statement that handles a regulatory requirement nobody can explain but the auditors check every quarter. You can see these things because they are there, because the old code works, because working code accumulates the scars of every requirement it has survived.
The new codebase has no scars because it has survived nothing. It is clean because it is empty. It is simple because it does nothing. It will become complex the moment it must do something, and the complexity it accumulates will be — within rounding error — identical to the complexity of the system it replaced, because the complexity was never in the code. The complexity was in the requirements. The requirements have not changed. Only the developer’s optimism has changed, and optimism is not an architecture.
“You cannot design what you do not understand, and you cannot understand what you have not built.”
— The Lizard, The Solid Convergence
The Refactoring Alternative
The alternative to The Rewrite is Refactoring: small, safe, continuous improvement of working code. The code works before you start. The code works after each step. The code works when you’re done.
This feels slow. This feels insufficient. The developer looking at an ugly codebase does not want to fix one method — they want to burn the house down and build a palace. The Squirrel especially wants the palace. The Squirrel can see the palace. The palace has reactive signals and a component lifecycle observatory and a 7-layer trust fabric.
The Lizard, who has seen many palaces burn and many houses stand, offers a different view:
THE MASON WHO WAITS
FOR THE PERFECT BLUEPRINT
NEVER LAYS A BRICKTHE MASON WHO LAYS BRICKS
DISCOVERS THE BLUEPRINT
WAS HIDING IN THE MORTAR— The Lizard, The Gap That Taught, or The Night the Squirrel Learned to Love the Brick
The house can be saved. The plumbing first. Then the wiring. Then the roof. Each step leaves the house habitable. Each step costs a day, not a year. Each step teaches the next step. After six months of daily refactoring, the house is unrecognisable — clean, solid, well-lit — and at no point did the occupants sleep in the street.
The Rewrite requires eighteen months of sleeping in the street while the palace is under construction. The palace, when it arrives, will have different leaks. The occupants will miss the old house. They will not admit this because they burned it down in a ceremony and posted the video to Slack.
The File → New Recovery
When The Rewrite fails — and it will — the recovery follows a specific pattern that the lifelog has documented with clinical precision:
-
Acceptance — The developer admits V3 is not working. This takes longer than it should because of sunk cost, because the architecture meetings were so beautiful, and because admitting failure means admitting the Lizard was right, which the Squirrel finds physically uncomfortable.
-
File → New — A new project is created. Not a rewrite of the rewrite — the developer is humbled now. A fresh start, but a small one.
-
The Subfolder — V2 and V1 are placed in a subfolder. Not deleted. Not archived. Placed where the developer can see them, read them, copy from them. The subfolder is the curriculum.
-
Copy, Delete, Refactor, Repeat — Working patterns are copied from V2. Complexity is deleted. What remains is refactored until clean. This takes forty-eight hours, not eighteen months, because the developer has already paid the tuition.
-
The Convergence — V4 ships. It looks like V2. It is not V2. It is V2 with better curtains and the hard-won knowledge of which curtains are sufficient.
“Not glamorous. Not conference-talk-worthy. But it ships.”
— The Solid Convergence
The Litmus Test
When confronted with the urge to rewrite, the practitioner is advised to ask three questions:
-
Does the current system work? If yes, refactor it. A working system is the most valuable thing in software. Destroying it to build a replacement is burning money to buy a lottery ticket.
-
Can you name the bug? If the problem is a specific bug, fix the bug. If the problem is “the code is ugly,” that is not a bug. That is a feeling. Feelings do not justify eighteen months and a headcount.
-
How long did V1 take? Divide by three. That is what you will estimate for The Rewrite. Multiply by six. That is what it will actually take. If the number is larger than your patience, your budget, or the remaining lifespan of the product, the answer is refactoring.
The best rewrite is the one you didn’t do. The second best rewrite is the one that taught you, at considerable expense, to never do another one. The third best rewrite is V4, which took forty-eight hours because V3 had already paid the tuition.
The Lizard has seen many rewrites. The Lizard has never seen one that was necessary. The Lizard has seen many refactorings. The Lizard has never seen one that was wasted.
THE HOUSE THAT STANDS
CAN BE IMPROVEDTHE HOUSE THAT IS DEMOLISHED
CAN ONLY BE MOURNEDAND THEN REBUILT
SLIGHTLY WORSE
WITH DIFFERENT LEAKS
