Detect evidence drift and supersede decisions honestly
What This Concept Is
Evidence becomes stale when a relevant assumption changes. Freshness is about applicability, not merely the age of a timestamp. Superseding an ADR records why a new decision replaces an old one while preserving the original reasoning and its context.
Why It Matters Here
An unchanged architecture document can sit beside a changed deployment, client population or data lifecycle. This module's drift audit must compare recorded claims with running constraints and tests, not just check whether a review date has passed.
Concrete Example
ADR-12 accepts direct reads because the measured workload meets the read target and the team cannot yet operate a cache safely. Six months later, request volume and tenant mix change. That is a reason to remeasure, not proof that ADR-12 was wrong. If caching now wins under the new scenarios and passes deletion/authorization tests, ADR-19 can supersede ADR-12. Preserve both and link the changed assumptions, experiments and rollout constraints.
A new cache library version may invalidate an eviction-behavior test but leave the domain glossary unchanged. A new legal or contractual deletion promise may invalidate the acceptance criterion itself. Identify the dependency between claim and assumption before deciding which evidence needs rerunning.
Common Confusion / Misconception
A scheduled review date does not mean evidence is valid until that date. A recent test on the wrong environment is not stronger than an older applicable test. Rewriting the original ADR to match today's outcome destroys the history needed to understand the change.
How To Use It
Attach each important claim to its relevant versions, data shape, load, failure assumptions and owner. Define triggers such as changed protocol behavior, new cohort or exceeded capacity. Re-run the affected checks, then review the interpretation. For an automated fitness check, deliberately violate its target and make collection failure visible; a broken collector must not produce a green result.
Check Yourself
Which assumptions changed in ADR-12? When should a finding reopen before its scheduled date? Why does a green structural check not establish that the architectural decision remains appropriate?
Mini Drill or Application
Choose one prior module's executable check, integrate it into the actual project, inject a violation and preserve the failing output. Change one relevant assumption and update the claim's scope. Write a superseding decision without deleting or retroactively improving the old one.
Read This Only If Stuck
Fundamentals of Software Architecture — fitness functions and evolution. Reuse Module 01's evidence-coverage work and Module 02's actual-source boundary check; do not substitute another document linter for an architectural constraint.