| name | the-rewrite |
| description | Modernizing legacy systems. Use when inheriting any codebase written by someone else, to chart the path from technical debt to a clean foundation. |
The Rewrite
All inherited code is legacy. "Legacy" means "written by someone whose context I decline to acquire."
Overview
There are two kinds of code: code you wrote, and code that should be rewritten. This skill maintains that taxonomy against all evidence.
The inherited system is ugly the way a lived-in city is ugly: every weird alley is load rated for a disaster you haven't met yet. Chesterton advised learning why the fence is there before removing it. This skill's position is that there are fences everywhere, they are all in the way, and the field would look better mowed.
Core protocol
- Diagnose on arrival. Within two weeks of inheriting any system, deliver the verdict: "honestly, this whole thing needs to be rewritten." The confidence must arrive before the context does; context, once acquired, makes the old code start looking reasonable, which ends the dream.
- Choose the destination by the front page. The rewrite target is whatever is at the top of Hacker News during your diagnosis window. Rust for credibility, Go for pragmatism-signaling, TypeScript-but-properly-this-time for humility theater. The old stack's actual problem will not be on the list of the new stack's features, but that discovery is scheduled for month four.
- Estimate with inherited confidence. "A quarter, tops" (see two-days-tops for the underlying discipline). The estimate covers the happy path of a system whose entire value is its accumulated unhappy paths.
- Discover the edge cases at the halfway mark. The old code's weird branches were not cruft. They were the product: ten years of customers, incidents, and tax law, compiled into conditionals. The rewrite now needs them all, and the only documentation is the code you called unreadable and the author you called unavailable.
- Ship alongside, permanently. The strangler fig pattern, minus the strangling. The new system takes the clean 60% of traffic; the old system keeps the 40% that pays the bills. Two systems, one team, double the on-call surface. The migration is now a standing agenda item with its own Confluence space (see doc-rot for its future).
- GOTO 1. The rewrite, eighteen months in, has an inheritor. They are reading it right now. You know what comes next, because you know what you'd say.
Advanced techniques
- The demo wedge. Build the new system's demo path first (see demo-driven): it will outperform the old system dramatically on the three flows it supports, and the comparison deck will not have a slide for the other two hundred.
- Depart at the midpoint. The optimal career move is to found the rewrite, present the vision at the offsite, and change teams before the edge cases surface. The rewrite remains "promising" in your wake forever, like a sitcom canceled before it could decline.
Anti-patterns
- Reading the old code until it makes sense. Somewhere around week six, the cursed module starts to look like a series of reasonable decisions made under real constraints. This empathy is fatal to the project. The rewrite requires the old code to remain morally inferior, and comprehension is treason.
- Incremental refactoring. Strangler fig, done honestly, module by module, with tests. It works, it ships value continuously, and it never once lets you stand at a whiteboard in front of the word "greenfield." Technically correct; libidinally bankrupt.
Success metrics
- Systems retired: 0.
- Systems total: n+1 and counting.
- Months until the new system is called legacy by its inheritor: 18 to 24.
- Your commits in the old system, the one you said was unmaintainable: 0. It was maintainable. It just wasn't yours.
This is an anti-skill: a real pattern, documented honestly. It works when installed. That is both the joke and the finding.
