Decision Half-Life
The observed time it takes for half a set of architecture decision records to be superseded, read as a diagnosis of how the records are written rather than of how unstable the system is.
A platform team reviews 4 years of decision records and finds half are superseded within about 7 months. The conclusion drawn in the room is that recording decisions is not worth the effort, since the records expire faster than anyone reads them.
That conclusion is almost always wrong, and the number is diagnostic rather than damning. A short half-life usually means each record bundles a durable choice with a revisable parameter, so moving the parameter invalidates a document that was mostly still correct.
Why it matters
"We will store workspace data in a sharded relational database keyed by workspace id" is a multi-year position that constrains everything built afterwards. "We will run 32 physical hosts with 15 logical shards each" is a capacity setting that changes with growth. Fused into one record, it dies at the first resharding and takes the durable part with it.
Measuring the half-life separates the population. Durable records about data model, tenancy key, identifier format and external contracts outlive their authors. Parameter records churn and should be written to be replaced. The metric says which kind your template is producing, without anyone arguing about ADR discipline.
Implementation patterns
- Compute it from the front matter. Date accepted, date superseded, and the id of the superseding record. If half-life cannot be computed, supersession is a label rather than a link and that is the first thing to fix.
- Report it per class, not per log. Split records into structural and operational before computing, and expect two very different numbers.
- Use it to set the granularity rule. One decision per record, in Michael Nygard's 2011 sense, means one thing that can become wrong on its own.
- Attach a trigger rather than a review date to the records whose class churns: "revisit when a shard exceeds 500 GB" is monitorable, while "review in six months" is a calendar entry nobody honours.
- Watch the tail, not the median. A record accepted 5 years ago, never superseded and still load-bearing is the most valuable document in the repository, and the likeliest to rest on an unchecked assumption.
Industry example
Public sharding histories show the pattern. Notion sharded Postgres into 480 logical shards in 2021 across 32 physical hosts, then in 2023 redistributed the same 480 onto 96 hosts. The logical shard count was the durable decision and the host count was the parameter, and they moved on different timescales: one has not changed, the other changed within 2 years. A record fusing them would have read as a failed decision, when in fact the expensive choice held.
Failure scenarios
- Wrong lesson drawn. A short half-life becomes evidence that the practice costs more than it returns, the log is abandoned, and 2 years later nobody can explain the shard key.
- Uncomputable metric. Superseded records name no successor, so the number cannot be produced and the log's currency cannot be trusted.
- Granularity creep. Records become project write-ups covering six decisions, and any one change marks the whole thing stale.
- Survivorship blindness. Only churning records get attention while the oldest and most consequential one rests on an expired assumption.
Trade-offs
| Choose | Gains | Pays |
|---|---|---|
| Fine granularity - one revisable thing per record | Supersession replaces exactly what became wrong | More records and a real need for an index |
| Coarse records covering a whole project | Fewer documents to write | Half-life collapses and durable reasoning is lost with the parameters |
| Tracking the metric at all | The template gets fixed rather than the people blamed | Front matter discipline and a small script to maintain |
When not to use it
Do not compute it on a log with fewer than about 30 records: the sample is too small and the number will swing on one supersession. A five-person team with eleven records does not need the metric or the machinery, because the person who wrote them is in the room. It is also the wrong instrument for judging whether records are useful — that is answered by timing how long a new engineer takes to find the current position on a subject. Half-life diagnoses granularity, nothing more.
Interview question
Q: Half your team's decision records are superseded within six months. Leadership reads this as proof that writing them is wasted effort. What do you say?
What a strong answer covers: reframe the number as a granularity signal, with an example of a record fusing a structural choice to a capacity parameter; propose splitting the template so parameters carry trigger conditions and structural records do not; name what would be lost, which is the explanation for every constraint baked into the code; and offer a measurable test of usefulness instead - time a new engineer finding the current position on one subject, before and after adding supersession links and a generated index.
Quick check
Quiz: A decision log's half-life is about seven months. What is the most likely cause? Records bundle a durable choice with a revisable parameter, so the whole record dies when the parameter changes.
Flashcard: What does a very long half-life on one old record tell you to do? — Check its assumptions. The oldest unsuperseded record is the most load-bearing and the least likely to have been revisited.