Taking over a codebase nobody documented

When a developer disappears, they rarely take the code with them. They take something worse: the explanation. The repository is still there, the app still mostly runs, and nobody alive can say why the invoice number starts at 4000 or what the checkbox labeled "legacy mode" protects you from. We have inherited a system in exactly this state: a fleet-compliance platform with no reliable documentation. This is the method we use to rebuild the missing explanation, written down so you can run it, or at least recognize it when someone runs it for you.

The requirements still exist. They're just scattered.

The comforting truth about an undocumented system is that the requirements did not vanish. They were never written in one place, but they exist in fragments: in old emails between the owner and the developer, in proposals and invoices that name features, in support messages where users complain about what broke, and above all in the behavior of the product itself. Requirements recovery is archaeology. The evidence is buried, and there is a method to the dig.

Source one: the correspondence

We start by asking for everything written. Email threads, chat exports, the original proposal, invoices, even voice-note transcripts. It feels invasive and it is gold. People negotiate requirements in writing without noticing: "can it also flag rest violations on Sundays" in a message from March is a requirement, and the reply "done, deployed Friday" is a claim you can test. We read the whole pile in date order and keep a running list of every promise, every change of mind, and every number anyone agreed to.

Source two: the product, observed like a lab animal

Then we use the system, slowly and on purpose. Every screen, every button, every setting toggled both ways with the outcome written down. Where the interface offers something the correspondence never mentioned, that is a discovery. Where the correspondence promises something the interface does not have, that is a gap, and gaps are exactly what the owner needs listed. The code gets read too, but code tells you what the system does, and only people can tell you whether that was ever the point.

Source three: the humans

Last come the interviews, run against what the first two sources produced rather than from a blank page. Asking an owner "what should the system do" produces philosophy. Asking "in this March email you asked for Sunday rest alerts. Does the current behavior, which we tested and does X, match what you meant?" produces requirements. Alexandru closes every one of these sessions the same way, with "so to confirm:" and a list read back out loud. Memory is agreeable. Read-back is honest.

Writing the document that should have existed

Everything converges into one document with three columns: what was promised, what exists, and what state it is in. Works, half-works, missing. That document does two jobs at once. It becomes the plan for finishing the system, and it becomes the first documentation the project ever had. On the fleet-compliance rescue, this single document turned an unclear situation into a finishable list, and a finishable list is where a rescue starts moving forward.

Then protect what you learned

The last step is making sure this never has to happen again. The recovered rules go into automated tests, because a test is documentation that checks itself. The document lives in the repository, next to the code it describes, and every milestone from then on updates it. Knowledge held only in one developer's head is how you arrived here. Knowledge held in tests and plain-language documents is how you leave.

Software project rescue and takeover →

Rescue or rewrite: how we decide →