Skip to content
Inherited systems

You are responsible for a system nobody understands any more.

The person who wrote it has gone. The documentation describes a version that no longer exists. There is one file everyone routes around, and a deploy step somebody does by hand on a Friday because that is how it has always worked.

So changes get smaller and rarer, and the system stops being something you use and becomes something you plan around.

Not ready to hand anyone read access to that system? There is a way to start on your own, below, and it asks nothing of you.

Built by an AI tool rather than by people who left? That has its own page.

Why it calcifies

Risk that cannot be sized becomes risk nobody takes.

A change to a system you understand carries a risk you can estimate, argue about, and decide to accept. A change to one you do not carries a risk that could be anything — and a rational team treats “could be anything” as “do not touch it”.

The cost never shows up as an incident. It shows up as a roadmap that quietly routes around a whole area of the product, and as an engineer’s answer being “we could, but I would not want to.”

This is more common than greenfield work and far less written about, because nobody wants to publish a case study about a system they were afraid of.

The expensive instinct

A rewrite is almost always the wrong first move.

It is the instinct because it feels like regaining control. In practice it trades a system you do not understand for a system that does not exist yet, and pays for the privilege — while the original keeps running in production, still unexplained, now also unmaintained because everyone is busy on the replacement.

The behaviour you actually need to preserve is mostly undocumented. That is the same reason the rewrite is hard and the reason it is risky, and it does not get easier by starting again.

Start on your own

Your first 30 days: read it before you touch it.

The instinct is to propose a rewrite. It is almost always wrong: a rewrite trades a system you do not understand for one that does not exist yet, and pays for the privilege. Start with a map.

Week 1

Write down what exists

Servers, services, scheduled jobs, databases, accounts, third-party connections, and where each one runs. One page, in plain words. Mark anything you cannot explain.

Week 2

Write down what depends on what

For each piece: what breaks if it stops, and who would notice first. Include the steps people do by hand (the Friday deploy). They are the part no code can tell you.

Week 3

Change one small thing, with checks on

Pick one real, low-risk piece of work and take it all the way to production with tests, review and a check that a person can still finish the job. You learn more from one clean change than from three weeks of reading code.

Week 4

Decide from evidence

Write what the change taught you: what was easy, what surprised you, what you still cannot explain. Only then decide to keep, tidy, replace in parts, or rebuild.

That is also why our own first engagement is deliberately small: one piece of work and read access to one system tells both sides more than any proposal document.

What we do instead

Read it first. Then change one thing, with the checks on.

01

Map, without touching anything

Read access only. The factory reads the system into a map of what it is, what depends on what, and where the gaps are — about ten minutes on a codebase the size of the ones we have run it on, six figures of lines, both listed on /results. A larger estate takes longer. Nothing you already wrote is overwritten.

02

Ask the people about what the code cannot say

The map is a read of the code and the repository history, so the two things you named first — behaviour nobody wrote down, and the Friday deploy step done by hand — are exactly what it cannot see. Those come out of a conversation with whoever is left, and they go in the write-up next to what is there and what we would leave alone.

03

One change, all 6 gates

Pick one real piece of work and take it the whole way through every check we run. The last one asks whether a real person can finish the job on the running system — which is the question a green test suite does not answer. You learn more from that than from three weeks of reading code.

Nothing is overwritten

We do not replace your documentation or restructure your repository to suit our tooling. If the engagement ends, you are not left unpicking our conventions.

The map is yours either way

The assessment is the deliverable, not a sales artifact. You keep it whether or not we do anything else.

We will say if it is fine

Sometimes a system is unloved rather than dangerous. That is a cheaper answer than the one you were expecting, and you get it.

The same process runs our own product, past 165,000 lines as at 2 August 2026. The work record behind it also says 43% of the work was later redone, and that queueing time rose as more of it ran in parallel. Both are published rather than dropped. All of it →

Start with the map.

Read access to one system, and we come back with what we found, what we would build and what it would take — before any commitment. If the answer is that it needs less work than you feared, that is the answer you get.

Map it — no charge