15 October 2026
Taking over a system nobody documented
A handover arrives as source code, a server and a name. What to look at first when the documentation does not exist: run the main path, write the implicit rules down, read the defect distribution as architecture, and change nothing that cannot be rolled back.
The brief arrives in the same shape every time. There is source code, there is a server, there is a person who left, and there is a business process that has to keep running on Monday. Nobody can tell you which parts are load-bearing, because the knowledge left with the person.
We have taken over systems this way for years — most clearly on a long-running ERP engagement where the first three months were spent taking over testing and defect fixing before any module development was handed across, and where every module was eventually transferred to the offshore team. The pattern that worked there is the pattern we still use.
Run the main path before reading the architecture
The first day is not for reading code. It is for getting the system to do the thing it exists to do, end to end, in a copy of the environment, and writing down every point where you needed a fact that was not in the repository.
That list is the actual documentation gap. It looks like: a scheduled job that must run before the report, a configuration file on a share, a certificate that expires, a stored procedure that fixes up yesterday’s data, a manual step that the operations team performs without thinking of it as part of the system. None of it is in the README, and all of it is load-bearing.
Two people should do this separately and compare lists. The differences between the two lists are where the real risk sits.
Turn the implicit rules into a table
Business systems are full of rules that nobody states because everybody knows them. Rounding on money. The cut-off hour that decides which day an order belongs to. What a status transition permits. Which role may override what. The order in which two batch jobs must run.
Write them down as a table with three columns: the rule, where it is implemented, and who agrees it is the rule. Then get the two people who disagree about it — usually operations and finance — to settle it in writing. This is unglamorous and it is the highest-value work in the first month, because every later bug report will be an argument about one of those rows.
Each row should end as a test. A rule that exists only in a paragraph will drift within a quarter.
Read the defect distribution as an architecture diagram
You cannot see the architecture yet, but the bugs can. Where defects cluster tells you which module has no clear owner, which two modules are coupled through a side channel, and which feature was patched repeatedly instead of designed once.
On the ERP takeover, the instrument was the defect trend itself: total defects and critical defects, tracked by iteration, both falling as ownership transferred module by module. That number is also the honest way to report progress to a client, because it is measured rather than described.
So before changing anything, establish the baseline: defect counts by severity, test coverage as it actually is, build and deployment time, the list of known-broken things. Without that baseline, the improvement you claim later cannot be shown, and the first regression will be blamed on you by default.
Change the smallest thing that can be rolled back
The temptation in month two is to refactor something ugly. Resist it until a rollback exists.
The order that works: get deployment repeatable and scripted, get database changes under version control, confirm you can restore, and only then touch behaviour. A system with no documented history is a system where every change is an unlabelled experiment; the rollback path is what converts an experiment into a managed risk.
Then take modules one at a time. Order them by coupling and by business criticality — the least entangled, most visible module first, so the team learns the system on something that will not take production down. Agree the acceptance criteria for a module before starting it, and write the decision record as you go, because the next person is the reason to do it.
What we do not do, and say so early
We do not propose a rewrite of a system in production as the opening move. A rewrite is sometimes the right answer, but it is a different conversation with a different budget and a different risk profile, and it should be a decision the client makes with evidence rather than a reaction to unfamiliarity.
The system you inherit is also the specification. It encodes years of decisions about exceptions that a clean design would never have guessed, and every one of those exceptions has a customer behind it. The work in the first months is not to make the system good. It is to make the system known.