ADR-Worthiness Triple Gate

These examples and illustrative results are independently authored teaching materials, not measured model results.

Use case

Choose durable storage with future maintainers in mind. Teaching A is current-state tables plus audit log; B is appended events plus derived current view. Requirements preserve history and read current state often. Reversing B may require data/consumer migration rather than a trivial rename.

Mechanism

Apply three ADR heuristics: meaningful reversal cost, surprising without context and genuine alternatives/tradeoffs. When all hold, record context, options, reasons, consequences and revisit conditions. Routine conventions belong in ordinary docs, while mandatory organizational records follow their own rules.

Bad example

Write an ADR for every variable rename but describe storage B only as more advanced, omitting A, query cost and migration context.

Good example

Check A/B against reversal cost from migrations, contextual surprise and genuine history/query tradeoffs. If satisfied, record the B decision: history requirement, alternatives, centralized event rationale, derived-query/consistency costs and review conditions. Use ordinary change notes for routine renames; do not claim B universally superior.

Why the change matters

Decision records preserve consequential context rather than increasing document counts. Alternatives/consequences let maintainers reassess instead of inheriting an unsupported advanced label.

Observable expectation

An illustrative ADR explains why not A, benefits/costs of B and changes requiring review. ‘B is better’ fails; a rename usually lacks the three conditions.

Ground reasons in supplied requirements/comparisons and preserve unknown costs instead of invented performance.

Limits

These are documentation heuristics, not legal/compliance criteria or a storage recommendation formula. Real organizations may differ. An ADR neither proves correctness nor authorizes production migration.