The five-field form that made 32 architecture decisions citable

A security platform team had made 32 real architecture decisions over the life of the product -- which database to trust, how to make an audit log tamper-evident, how to structure a permission model. Every one of those decisions was a good one. The problem was that "good decision" and "decision anyone six months later can actually find, understand, and cite" are not the same thing, and most teams only have the first.

The human moment

Picture a new engineer, or an auditor, asking a question that should have a one-line answer: "why does this system do it this way, and who decided that?" In most codebases that question sends someone digging through old pull requests, Slack threads, and institutional memory that only exists in someone's head. On this team, the answer instead came from a folder of dated files that all looked the same, because they were all built from the same five-field form.

The gap seen -- opportunity taken

The easy path is the one nearly every team takes: decisions get made in meetings or messages, the reasoning lives in someone's memory, and the only artifact that survives is the code itself -- which shows what was decided but never why, and never what was considered and rejected. The team here saw that gap early and refused to accept "the code is the documentation" as good enough for decisions that matter. Instead they built a lightweight, repeatable form and applied it every single time a real architecture decision got made, so the record couldn't fall behind the decisions the way memory always does.

Teach the concept

This is the architecture decision record, or ADR, pattern -- and the specific version of it in evidence here is deliberately small: a five-field template capturing a date, a category, a status (Proposed/Accepted/Deprecated), the context that made the decision necessary, the decision itself, and its consequences. Each one is dated and numbered, generated from the same scaffold every time, so 32 decisions read as one consistent, browsable record instead of 32 different documents in 32 different formats and states of completeness.

Why it matters -- the stakes without it

Without a citable decision record, institutional knowledge walks out the door with whoever made the call, instead of living in a record the whole team can read. A new hire re-litigates settled questions because they can't find out they were already settled. An auditor or a technical buyer evaluating the platform has to take "we thought about that" on faith, with nothing to point to. And a team under pressure quietly re-decides the same tradeoff differently the second time, because nobody remembered -- or could find -- what was decided the first time.

How we approached it -- outcome level, and the tradeoff we accepted

The team chose a deliberately minimal, machine-generated scaffold over a free-form "write it up however feels right" approach. A richer, more narrative format might capture more nuance per decision, but it also invites inconsistency -- some decisions get a paragraph, some get a page, some never get written at all because the bar feels too high. The five-field form trades some narrative depth for a much lower barrier to actually writing the record every time, which is why 32 decisions exist as a real, citable corpus instead of a handful of well-documented ones and a long tail of undocumented tribal knowledge.

What a reader can take to their own work

The next time your team makes a real architectural call, ask whether the reasoning will still be findable in a year, by someone who wasn't in the room. If the honest answer is "only if you ask the right person," a five-field form is a cheap fix for an expensive problem.

Evidence: an active, dated, numbered architecture-decision-record template governing 32 real decisions in a production security platform's codebase -- verified by direct read of the current on-disk template file, L2-reviewed 2026-08-25 -- full record: docs/technology-portfolio/validation/run-4a-overnight-aifs/BATCH-CONTENT-PLAN-2-2026-08-25.md.