“Why is it built this way?” — “Nobody knows. The person who decided left.”
Every engineering org past a certain age has had that exact exchange. Michael Nygard named the disease fifteen years ago when he introduced the architecture decision record: the hardest thing to track through a project’s life is the motivation behind its decisions. And he named the trap it sets for whoever comes next: with the reasoning gone, you have two options — blindly accept the decision, or blindly change it. Both are terrible. Accept it and the system fossilizes around constraints that may have expired. Change it and you rediscover, usually in production, exactly why the queue was there.
Gate 40 in my system is Architecture Complete, and I want to disarm the obvious objection before walking it, because the objection is correct. Martin Fowler’s definition of architecture is the honest one: the decisions you wish you could get right early — the ones everyone perceives as hard to change — and the architect’s most important job is to make fewer things irreversible, not to produce more documents. So no, this gate doesn’t weigh diagram tonnage. It asks a narrower question: for the decisions that are hard to reverse, is the readiness real and is the why written down? That’s also where the fourth of Cagan’s four big risks burns down — feasibility: can we build this with the time, skills, and tech we actually have? Value and viability died or survived at Gate 20; usability at Gate 30. Feasibility is engineering’s own risk, and this is its gate.
What does “written down” actually mean?
Four things, none of them heavy.
The decisions, with their why. One ADR per architecturally significant decision — the ones touching structure, dependencies, interfaces, the hard-to-change list. Context, decision, consequences; one page; in source control next to the code it explains. This stopped being a niche practice years ago — ThoughtWorks put it at Adopt with the flattest endorsement in the Radar’s vocabulary: “we see no reason why you wouldn’t want to use this technique.” Even ISO’s architecture-description standard folds recording decisions and rationale into what an architecture description is. The why isn’t garnish on the architecture. It’s part of the architecture.
A map at each altitude. The HLD job is zoom out and zoom in: system context first — who talks to us, what we talk to — then containers, then the components that matter. If a reviewer can’t walk from the top view to the risky component without a guided tour, the design isn’t reviewable; it’s a mural.
NFRs against a taxonomy, not vibes. “We thought about performance” is not an NFR review. Walk a real list — the ISO quality model gives you nine: functional suitability, performance, compatibility, interaction capability, reliability, security, maintainability, flexibility, safety — and mark each one addressed, deferred, or not applicable. The point isn’t ceremony; it’s that the unmarked ones are where incidents come from.
Risks and tradeoffs, chosen on purpose. The formal-review lineage (SEI’s ATAM runs days with trained evaluators) exists to surface architectural risks and tradeoff points early. You don’t need the ceremony. You need its outputs: the risks named, the tradeoffs acknowledged as choices — with owners and mitigations — before the code makes the choice for you.
(By the way, this is the gate where I catch myself most. The design is in my head, clear as day, and writing it down feels redundant. It is redundant — for exactly one person, for about six weeks.)
Is the paperwork worth it?
Take the honest numbers, caveats included. Boehm and Basili’s defect-reduction list — still the citable source, folklore charts aside — puts fixing a problem after delivery at often a hundred times the cost of fixing it at requirements-and-design time; their own data says more like five-to-one for small, non-critical systems.
Their sharper insight sits one line lower: good architectural practices shrink that escalation factor by confining fixes to small, well-encapsulated modules. And avoidable rework eats forty to fifty percent of project effort. The gate is cheap. The rework it prevents is not.
To the new hire and to the machine alike, your load-bearing weirdness looks like cleanup.
Why does this gate matter more now?
And then the amplifier — because this gate changed more in the last two years than in the previous twenty. Code churns at machine speed now, and that breaks the old memory model twice. First, the half-life of “everyone remembers why” collapsed: the system changes faster than oral tradition can keep up. Second, and sharper: AI agents read your repo and improve what they see — and an undocumented deliberate choice is indistinguishable from an accident. The decision record is what marks it constraint instead of candidate. Feed your ADRs to the agents as context and they work with the grain of the system. Leave the decisions in heads, and AI will helpfully refactor the very thing keeping you up at night for staying up.
How do you capture the why without the friction?
The augmentation follows, and it kills the main excuse. Nobody skips ADRs because they disagree with them; they skip them because writing is friction after the decision already happened. So don’t write them — capture them. The design discussion already exists: the thread, the doc, the meeting transcript. AI turns it into a one-page context-decision-consequences draft in minutes; the job was never prose, it was preserving the why. Same move for the review: AI walks the HLD against the nine characteristics and hands back the unaddressed ones as questions. The human does the one thing that was ever worth a human: makes the call, and signs it.
Why does the engineering leader own this gate?
Because the team’s memory should outlive anyone’s tenure — including mine. And because committing a team to build something is a management act: feasibility is my risk to burn down before the sprint math starts, not the architect’s alone.
Nygard’s own defusal answers the last objection: agile was never against documentation — only against valueless documentation. One page per hard-to-reverse decision; if it doesn’t fit a page, the decision isn’t understood yet. Architecture you can’t explain is architecture you don’t control. So put the why in writing. Word is the key to everything.
That’s Protocol #4. Gate 50 — Work Breakdown Complete, where “ready” finally earns a definition — is next. Eight gates to go.
