Decision Granularity

A team writes one record called "Platform Architecture" covering the language, the datastore, the deployment target, the auth approach and the message broker. Two years later they move off the broker. Superseding the record would discard four decisions still in force. Editing it breaks the immutability the practice depends on. So nobody does either, and the record stays accepted while one of its five paragraphs is false.

Granularity is the choice that prevents this: one decision per record, where a decision is something that can independently become wrong. It is a boring property and it decides whether a set of records can still be trusted after three years of change.

Why it matters

Decision records are only useful if a reader can tell which ones are current. That test runs on the status field, and status is per record, not per paragraph. A record bundling five decisions has no honest status once any one of them changes — it is neither accepted nor superseded, and readers learn to distrust the whole set.

The failure compounds in the direction teams do not expect. Records that are too coarse do not get superseded; they get quietly ignored, and the ignoring spreads. Within a year the team has decided that records are not worth reading, and the diagnosis is usually "we chose the wrong template" when the actual fault was scope.

Granularity also governs cost. A record costs roughly an hour to write and 2 hours of reviewer attention in total, so splitting a decision into five records is a real expense. Too fine is a smaller problem than too coarse, but it is not free: a set of 300 records where 40 would do is unsearchable in a different way.

Implementation patterns

• The independence test: could this part become wrong while the rest stays right? If yes, it is a separate record.
• The supersession test, applied before writing: imagine superseding this record in two years. If the replacement would have to repeat parts of the original unchanged, the scope is too wide.
• Keep a record to about one page — 300 to 600 words. Length is a proxy for scope and a reliable one.
• Use a parent record for a programme, listing the decisions it contains and linking out, so the strategy has a home without bundling the choices.
• Split on different rates of change. A datastore choice and a deployment-tool choice move on different clocks and belong in separate records even when decided in the same meeting.
• Do not split what cannot move independently. Choosing a broker and choosing its delivery semantics are one decision if changing either forces the other.
• Title by the question answered, not by a component name, because a question has exactly one answer and a component accumulates many.

Industry example

The public decision processes that survive at scale enforce this explicitly. Kubernetes enhancement proposals are scoped to one enhancement, with its own lifecycle status, and a change of direction produces a new proposal rather than an amendment. Rust's RFC process works the same way: an accepted RFC is a historical artefact, and the next change is another RFC that references it. The decision-record format popularised by Michael Nygard's 2011 post is built on the same assumption — status plus immutability only works if the unit of status is the unit of change. Teams that adopt the template and ignore the scoping rule get the ceremony without the property that makes it work.

Failure scenarios

• The omnibus record that cannot be superseded, so it rots in place while retaining "accepted" status.
• Silent editing of a bundled record because superseding is too costly — which destroys the history and the reason for keeping records at all.
• A superseding record that re-states four unchanged decisions, creating two documents that must now agree and will not.
• Fragmentation in the other direction: fifteen records for one migration, none of which states the overall position, so a reader can find every detail and no conclusion.
• Titles named after components — "the payments service" — that accumulate three unrelated decisions over time and reproduce the omnibus problem by drift rather than by design.

Trade-offs

The bundled form is genuinely more pleasant to read once, at the moment it is written, which is exactly why it keeps being chosen. Its cost lands entirely on people who are not in the room.

When not to use it

For a team of four on a three-month project, a single running design document beats a set of records: everyone is present, nothing has yet needed superseding, and the indexing cost buys nothing. The rule starts mattering at the first supersession, which in practice is 12 to 18 months in or the first time a second team depends on a choice.

There is also a legitimate coarse form: a context record that captures a set of constraints — regulatory scope, target platform, budget — that individual decisions then reference. That is not a bundle of decisions; it is one decision about the frame, and it supersedes as a unit when the frame changes.

Interview question

Q: Your team's decision records are one per quarter, each covering everything decided in that quarter. They are well written and nobody supersedes any of them. What is wrong, and what do you change without invalidating three years of history?

What a strong answer covers: name the mechanism — status is per record, so a quarterly bundle can never be accurate after its first change, and the predictable result is that supersession stops happening. Do not rewrite history: leave the old records in place as an archive, and start writing one decision per record now. Split retroactively only where a decision is currently being revisited, with the new record referencing the paragraph it replaces. Change the title convention to a question, since that alone prevents most re-bundling. Expect the set to look inconsistent for a year and say so, because pretending otherwise leads to a backfill project that will not finish.

Quick check

Quiz: What test decides whether two choices belong in the same decision record? — Whether either can become wrong while the other stays right. If they can move independently, they need independent status, so they need separate records.

Flashcard: Why does a coarse-grained decision record stop being superseded? — Superseding it would discard the parts still in force, and editing it breaks immutability, so the team does neither and the record keeps an "accepted" status it no longer deserves.