polycratia

Most questions on your pre-rewrite checklist have an answer somewhere in the old codebase. That is the trap.

What the code says and what production traffic does are two different specifications. Traffic is the one that counts.

They stopped matching years ago. Reading the old system tells you what it was meant to do, not what anyone currently depends on, and that gap is where cutovers fail.

Four things only observation answers:

Which endpoints are actually called, and by whom. Not which ones are still routed: routing keeps dead paths alive for years.

The real shape of the payloads. Fields documented as required that arrive empty. Optional ones that keep showing up in live calls anyway, so your new validator rejects real traffic on day one.

Which error responses callers branch on. In payments I think this is the sharpest one: a client retry loop keyed to a specific failure code is a contract, whether or not anyone wrote it down.

How much duplication the old system is quietly absorbing. Often it tolerates repeated calls by accident, through a constraint or a stale cache that nobody sat down and designed. Rebuild it cleanly and the duplicates surface.

So before scope gets frozen: instrument the old system and watch it for a full cycle. Not a week: a window that includes month-end, because settlement, billing and reporting jobs only exist then, and they rarely make it into the rewrite plan...

A spec written from code reproduces intent. A spec written from traffic reproduces behaviour. Only one of those survives the switch.

If you are planning a rewrite, I'd want to know how long a full cycle runs in your system, and whether your observation window actually covers the slowest job in it.

react

$ new-project --brief

or email hey@polycratia.com