The Documentation Completeness Test: A Six-Field Checklist Per Decision

Recording rationale alongside a decision is the right instinct, but "record the why" is still vague enough that two architects following the same advice can produce documentation of wildly different quality -- one writes a paragraph of genuine reasoning, another writes "chosen for performance reasons" and calls it done. What's needed is a concrete, checkable structure: a fixed set of fields that, filled in for every architectural decision, produces documentation that actually survives the test of someone else using it later.

The Six Fields

For each architectural decision in the system, the documentation should capture:

This is a genuine enhancement over documenting "the why" as a single free-text field: it forces the documentation to separate *what was chosen* from *what was rejected and why* from *the tradeoff* from *who's accountable* from *what evidence backs it up* -- five distinct pieces of information that a single "rationale" paragraph tends to blur together, often omitting one or two of them entirely without the author noticing, because a paragraph doesn't have empty boxes that visibly need filling the way a checklist does.

The Documentation Completeness Test

The six fields exist to pass one specific test, and the test itself is the more important thing to internalize: could someone who never sat through the original design discussion read this and modify the system without introducing a regression? This reframes documentation quality away from "did we write enough words" and toward "does this actually transfer the knowledge a stranger needs." A document that's long but missing the rejected alternatives, or missing who owns the decision, or missing any evidence beyond "it works," fails this test regardless of its word count -- and a document that's short but hits all six fields for the decisions that matter can pass it.

Why Each Field Earns Its Place

• Without rejected alternatives, a future maintainer re-proposes an option that was already tried and discarded, wasting time re-litigating a settled question.
• Without the tradeoff stated explicitly, a maintainer sees only the chosen path and has no way to judge whether the tradeoff still holds once circumstances change.
• Without an owner, there's no one to ask when a question the document doesn't answer comes up -- and no accountability if the decision turns out to have been under-scrutinized.
• Without an evidence artifact, "it was the right call" is an assertion with nothing behind it, indistinguishable from a guess dressed up as a decision.
• Without audit-ready status as an explicit check, a document can look complete to its author (who has all the missing context in their head) while being genuinely unusable to anyone else -- which is exactly the failure mode the whole discipline of documentation exists to prevent.

Worked Example

Compare two entries for the same decision. Weak version: "Model tier: mid-size. Chosen for cost/performance balance." That's a decision with a vague half-sentence of rationale -- no rejected alternative named, no owner, no evidence, and it would fail the completeness test the moment a stranger asked "balance against what, exactly, and who decided that balance was right?" Six-field version: "Decision: mid-size model tier for the retrieval-generation step. Rejected alternatives: large tier tested and rejected -- 340ms slower per request with no measurable accuracy gain on our eval set; small tier tested and rejected -- accuracy dropped below the 92% floor on ambiguous queries. Tradeoff: we gain p95 latency under 1.8s with reranking enabled; we pay roughly 15% higher cost per request than the small tier. Owner: J. Alvarez (lead architect), approved by the eng director in the 3/14 design review. Evidence artifact: eval-run-2024-03-12.json, comparing all three tiers on the same 500-query benchmark set. Audit-ready: yes -- eval artifact and rejected-tier results are both in the shared eval repo, retrievable without asking the original author." A future maintainer reading the second version can verify the choice, understand exactly what would need to change to justify revisiting it, and knows who to ask if something's still unclear -- the first version offers none of that.

Common exam traps

• Treating "we documented the rationale" as sufficient without checking whether rejected alternatives, ownership, and evidence are all actually present -- a rationale sentence can exist while still failing the completeness test.
• Assuming documentation length is a proxy for documentation quality. A long document missing an owner or an evidence artifact still fails; a short one hitting all six fields for its key decisions can pass.
• Skipping the completeness test itself ("could a newcomer to the discussion make a safe change from this alone?") and instead just checking that *some* prose exists under a rationale heading.