Separate the decision from the evidence supporting it

What This Concept Is

An architecture decision is a choice under stated constraints. Evidence supports particular claims about that choice; it does not turn the choice into an unconditional fact. An ADR should let a future reader reconstruct both what was known and what was uncertain when the decision was made.

Why It Matters Here

Earlier modules produced measurements, dependency graphs, domain traces and compatibility witnesses. This module turns those into a decision argument. Pasting every passing check into an ADR can still leave its most important assumption unsupported.

Concrete Example

A team proposes caching document reads because a warm-cache run has a median of 18 ms versus 42 ms for direct reads. That observation supports a narrow latency claim under the recorded workload. It does not establish a p95 target, deletion safety, cold-start behavior or reduced operating cost.

Write separate claims: warm-cache median improves in the measured trace; authorization remains correct after a policy change; deleted documents cannot be returned after the agreed completion point. Attach a measurement to the first claim and targeted failure traces to the latter two. If those traces do not exist, mark the claims unverified rather than describing the cache as safe.

Common Confusion / Misconception

A polished ADR is not evidence that a review happened. A benchmark result is not a reason to select an option until it connects to a prioritized scenario. Three alternatives must be viable under the constraints, not one favored option plus two deliberately weak choices.

How To Use It

For each material claim record the scenario, observation, artifact revision, environment, method and limitation. Distinguish measured, inferred, assumed and unresolved statements. Preserve negative results. Record the options rejected and the condition under which each would become preferable. A past decision may be reconstructed, but label remembered reasoning and missing contemporaneous evidence explicitly.

Check Yourself

Which claim does the median measurement support? What evidence would a deletion-safety claim require? Can an option be reasonable while a key assumption remains uncertain? Who has authority to accept that uncertainty?

Mini Drill or Application

Take one existing ADR and underline every empirical claim. For each, attach an artifact or change the wording to an assumption. Add the cheapest experiment that could overturn the preferred choice. Keep the original version so the correction remains visible.

Read This Only If Stuck

Fundamentals of Software Architecture — decisions and consequences. Nygard's original ADR article motivates concise decision records; the claim/evidence checklist here is this curriculum's additional practice.