Architectural diagnostic of a system

The system works — or has stopped working — and why, nobody has known for a long time.

The people who built it have left or moved on. The ones who stayed know their own corners and not the whole. Every estimate turns into an argument, because the argument is not about the work but about what is actually in there.

What was built gets read, not what was intended. Documentation describes the intention, code describes the fact. They always diverge; the only question is where.

The expensive places get found. Not "bad code" — there is plenty of bad code and much of it is harmless. An expensive place is one where a single change drags ten more behind it, and each such place is priced separately.

The critical path gets restored. Which part of the system actually carries the business, and which was built just in case and has existed ever since.

Urgent and expensive get separated. These are two different lists, and mixing them costs the most: the urgent burns today, the expensive will cost you all of next year.

A map of the system you can use to talk to any contractor — it is yours and it stays with you. A list of the places that are expensive to touch, each with its price. And a clear view of which work is unavoidable and which can wait a year.

Eight people had spent eight months on the system, and the release kept slipping. For the first two days I wrote no code — I read what had been built. The gap between what was intended and what stood in the code turned out to be the place where everything had stopped.

The same move at another scale: fifty-odd applications assembled since 2005 by different hands and different traditions. What had to be read was not the applications but the moves between them — and that is where the real price sat.

An assessment of people. A diagnostic reads the system, not the team, and the report carries no names.

And it is not a checklist audit. A checklist gives you deviations from a standard; what you need is the list of places where your money is, and those are different lists.

Name the one place that is most expensive to touch, and one number that can be measured. If no such place can be named, that is the first result of the diagnostic, and we start there.