A Python 2 monolith landed on me, and everyone agreed it had to be rewritten. I agreed too. That agreement was the easiest part of the whole project.
I mapped the modules, drew the service boundaries, picked the order. The plan looked clean. Then the first extracted service went live and started producing results that were technically correct and operationally wrong.
The old code had a behavior nobody had written down: an upstream call came back empty, and it fell through to a stale cached value instead of failing. Someone did that years earlier, probably for a good reason, under pressure. Downstream, three different consumers had quietly built on top of it. One of them treated a missing record as a signal, not as an error.
My rewrite was more correct than the original. That was the problem. It raised where the old one shrugged, and the shrug had become part of the contract.
What it cost: weeks of chasing symptoms that looked like data issues and were really semantic drift between two versions of the same system.
What I do differently now, before touching anything:
I stop asking whether the code is bad. It is, that's why I'm here. I start asking which of its current behaviors are load-bearing, and I don't look for the answer in the source. The source tells you what someone intended. It does not tell you what consumers came to depend on.
So I run both systems against the same real traffic and diff the outputs. Not the happy path: the empty results, the timeouts, the duplicates, the partial writes. Every place the two disagree is either a bug I'm fixing or a contract I'm about to break, and I have to decide which, explicitly, in writing. The ones I choose to break get a migration instead of a surprise.
That shadow-run period feels like pure overhead when you're trying to ship. It is the cheapest part of the entire rewrite.
The second thing I ask: can this be strangled incrementally, or does it have to go in one cut? If the answer is one cut, the honest follow-up is whether the business can absorb a bad week. Sometimes it can. More often nobody asked, and finding out during the cutover is a career-shaped event.
I wrote up the full set of questions I run through before agreeing to a rewrite, including the two that usually kill the idea, here: https://polycratia.com/c/880960cd
For those of you who've done a big migration: I'd like to hear which undocumented behavior turned out to be a contract you didn't know you'd signed...