First Principles: When to Rewrite Instead of Refactor

A client asked me last month whether to refactor their old Django codebase or rewrite it. The question felt urgent to them. To me it felt premature. You can't decide rewrite vs refactor without answering a deeper question first: what is this code actually for?

The Only Honest Criterion

Rewrite when the current design is incompatible with the actual requirements. Refactor when the design is compatible but the code is messy. That's it. Everything else is aesthetics.

A codebase with ugly code but correct architecture should be refactored, not rewritten. A codebase with clean code but wrong architecture should be rewritten, because no amount of refactoring will fix it.

How to Tell Which You Have

Look at the last five bug tickets. If fixing them required changing the shape of the code (new tables, new services, new abstractions), the architecture is wrong and you need a rewrite. If they required touching the same modules over and over, the code is messy and you need a refactor.

Bug: payments fail silently when gateway times out
Fix shape: add retry queue, idempotency keys, dead letter handler
Verdict: architecture, not code -> rewrite the payments module

Why Rewrites Usually Fail

Most rewrites fail because the team skipped this analysis. They rewrote code that was just ugly, not wrong. They ended up with cleaner code that solved the same problems in new ways, with a year of lost velocity in between. The new system has its own ugly spots within six months.

Go to first principles. Ask what's wrong. Then pick the cheapest fix.