Rewrite or Repair
Forces an honest answer to 'fix it or start over', costed in evidence rather than taste.
When to reach for it
When a change to existing code has stalled and someone — usually the agent — starts suggesting it would be faster to rewrite the whole thing.
What changes
- The agent states what the existing code already gets right, including behavior nobody documented, before proposing to throw it away.
- Both options are costed in the same units — files touched, tests to redo, behavior at risk — so they can actually be compared.
- The odd branches and magic numbers in the old code get listed as things a rewrite would have to reproduce, which is usually what settles the argument.
- If repair wins you get the smallest repair; if rewrite wins you get a plan that keeps the old path running until the new one passes.
- 'Rewrite because it is ugly' gets rejected out loud instead of acted on.
Pairs with
- Dependency AuditDecides whether a library earns its place, or whether twenty lines of your own would do.
- Spike Then DecideBuys certainty about an unknown approach with a throwaway experiment on a fixed budget.
- Assumption CheckMakes the agent state what it is assuming — and verify it — before it writes a line.
Rewrite or Repair
The question is not which code is nicer. It is which path reaches working software with less risk.
1. Establish what the current code gets right
Read it and list the behavior it already handles. Pay attention to the parts that look strange: an odd branch, a hard-coded exception, a retry with a specific number in it. Those are almost always something that went wrong once in front of a real user, and a rewrite will meet it again.
If you cannot explain why a line is there, write it down as unknown behavior. Unknown behavior counts against rewriting.
2. Name the actual problem
Be precise about what is wrong:
- It does not do something we now need it to do.
- It is too slow, by a measured amount.
- Every change to it breaks something else.
- Nobody understands it.
Only the last is about the code being unpleasant, and it is the weakest reason on the list.
3. Cost both paths in the same units
For repair and for rewrite, estimate: files touched, tests that must be rewritten, behavior at risk of regressing, and how long until something runs again. A rewrite that "starts clean" still owes every item from step 1, and that debt is invisible until you write it down.
4. Choose, then shrink the choice
- Repair — make the smallest change that solves the named problem. Do not tidy the surrounding code in the same pass.
- Rewrite — leave the old path running. Build the new one beside it, move one caller across, verify, then move the rest. Delete the old code only when nothing calls it.
Rules
- Do not rewrite because the code is unfamiliar. Unfamiliar is a reading problem, not a code problem.
- Do not start a rewrite without the list of behavior it must reproduce. That list is the real cost of the decision.
- Do not plan a rewrite with no working state in the middle. If there is no point where you could stop and still ship, the plan is wrong.
- Do not blur the two. A repair that quietly replaces half the module is a rewrite with no plan and no way back.