A review of a failed build can record, in its own evidence base, that the high and low level design documents were obtained and read, and that an architecture diagram sat inside them. The same review can state, in its technical findings, that no documented systems design artefact was in place. Both sentences are in the same report, about the same build, written by the same people. Neither is a slip. They describe two different documents, and the one the contract had priced is the one that was not there.
A European banking group's IT services subsidiary commissioned an independent post-delivery review after an offshored build of a business application failed to reach acceptance testing and the statement of work was terminated. Inside that contract sat a costed activity, estimated at 140 person-days: a system design artefact setting out coding standards, design principles and the supplier's rationale for the way it intended to build. The review looked for it and found no evidence it had ever been produced.
The challenge
Drawings and reasoning are different artefacts, and organisations buy the first while believing they have bought the second. A high level design says what is wired to what. A low level design says how each piece is shaped. Neither is obliged to say why the shape was chosen, which constraints it was chosen against, what has to stay true for it to keep working, or what breaks if the next person changes it. That last set is what a design rationale carries, and it is the only part of a design record an architect cannot reconstruct by reading source.
The review's finding is precise about the effect, and it is worth staying inside its wording rather than extending it. With no documented systems design artefact in place, the report says, it was difficult for the client's architects to understand the development logic in the software. Not that the build failed because of it. The report's own summary of why the engagement failed points elsewhere, to depth of experience on the delivery side and to how slowly delivery management responded when problems were raised. The missing artefact is a finding, and its recorded consequence is narrow and specific: the people whose job was to reason about the system could not do it from the documentation.
What the report records separately is where the quality problems actually surfaced. Most were spotted when a client architect went into the supplier's code to help resolve something else, a performance question or a piece of behaviour that would not work. The review does not join those two findings into a chain, and neither will we. What is worth noticing is only that reading a system that way is reading it in the worst available conditions: under time pressure, inside an unrelated problem, with no map of intent to check a suspicion against. Every finding obtained that way costs a senior person's afternoon and arrives after the decision it should have informed.
Two other observations in the report sit next to this one and deserve to be read with it. The supplier's monthly headcount bills were pulled as evidence, and the review noted no architect being billed on them. When quality had already been escalated formally and the client asked for a senior architect to step in, more than two months passed before that architect arrived. The document was bought. The role that would have written it, and then defended what it said for the length of the build, was not visible in the record on a continuous basis. A design rationale is not really a file. It is the residue of somebody being accountable for the design in public, repeatedly, while the design is still cheap to change.
The approach
What the review recommended was recommended after termination rather than performed during the build: agree design and coding standards before work starts, state which patterns are wanted and which are to be avoided, agree a quality model jointly and configure tooling to check the code against it automatically, and run peer review as a discipline rather than a courtesy. Sensible, phased, and too late to help this application, which had already been taken back in house.
The question this finding raises is what the excuse is now. Until recently, "we did not have time to write it" was at least an honest account of a real cost. Setting out coding standards, design principles and a defensible rationale for a build of this size was weeks of skilled attention, which is why the contract priced that activity at 140 person-days and why it is the kind of line that slips.
That cost has collapsed. A coding assistant with retrieval over a repository will produce module maps, dependency relationships, a summary of what each area does and a first draft of a design description in an afternoon, and it will do it again next month when the code has moved. Structure is now close to free to regenerate, which means an organisation that ships a build with no readable description of its shape is choosing that, not suffering it.
What has not become free is the part that mattered here. Retrieval returns what is in the corpus. Where the reasoning was never written down, a generated design description will not report an absence; it will infer intent from the code and state it fluently. For an architect trying to decide whether a static variable is a performance choice or a security one, that is a worse artefact than an empty page, because an empty page cannot be trusted by accident. Generation gives you the map. It cannot give you the constraint the map was drawn against, unless somebody wrote the constraint down when the choice was made.
The practical shape of that, in the delivery work we do on the Platform, is unglamorous. Decisions get recorded at the moment they are taken, short, dated, attached to the change that implements them, with a named owner. Standards get expressed as checks that run on every commit rather than as prose nobody re-reads. Generated descriptions are treated as drafts, tested against an evaluation set built from the questions architects actually asked during the last few incidents, because a design summary that cannot answer those is decoration with better formatting.
The outcome
This engagement produced a findings pack, recommendations and a phased plan for acting on them. It repaired no application, and nothing reported here is an outcome of those recommendations, because the contract had ended before they were delivered.
The durable lesson is which excuse the failure now travels under. The report shows an evidence base in good order: design drawings obtained and read, weekly reports from both parties on file, a risk log maintained throughout, and a formal escalation raised early. The same report finds plenty wrong with how that machinery was used, reporting misaligned, no shared definition of a red status. But none of it, used well or badly, was built to notice that the artefact explaining the reasoning had never arrived, because nothing downstream was waiting on it. Cost was the alibi then. Cost is gone, and the same gap will now show up as a folder of generated pages nobody has been asked to defend.
There is a regulatory edge coming to this. The European rules on artificial intelligence that reached political agreement are built around technical documentation for the systems an organisation puts into use. Anyone who could not produce a design rationale for an ordinary web application, over a build of many months, with the activity priced in a signed contract, should be careful about assuming they will produce one for a model whose behaviour they can describe even less precisely.
The test worth applying is a short one. Pick the part of your estate your architects reason about most often, and ask what they read when they need to reason about it. If the answer is the source, the design record you are paying for is not the one they need.