A document with two unrelated halves is one nobody can cite half of.
Bundling is always cheaper at writing time. One record, one review, one merge — and the second half arrives free, because it was going to be written anyway. The cost lands later and never goes away.
This was first written about decisions, and it is not about decisions. It holds for any document a reader is expected to name: a decision, a principle, a practice in a record of practices, a claim in an anthology. The unit is whatever gets cited.
What it costs
The second half has no code. A citation is how a record is used: an argument names its premise, a module names the decision it implements, a lint message names the rule it enforces. Half a document cannot be named, so the half that was cheap to add is the half nothing can point at — and a rule nothing points at is a rule nobody knows applies to them.
Superseding withdraws more than intended. A document that changes gets superseded whole. If two things share a record, retiring the one that aged out silently retires the one that did not, and the record now says nothing about a question it had answered. That is the failure the status vocabulary exists to prevent, reintroduced at a coarser grain.
Alternatives stop being reconstructable. For a decision, the alternatives section is the highest-value part, and it only works when it is the alternatives to one choice. Two choices produce a cross-product, or — far more often — an alternatives section that silently covers whichever half the author found more interesting.
Two tests
Could the halves have been decided differently? If a project could adopt one and reject the other, they are two documents, however naturally they arrived together.
That one only fires while writing, and it depends on the author asking. Typed edges (ADR-071, ADR-060) make a second test possible, and this one fires afterwards, mechanically:
Does an edge into this document have to name which part of it applies? If stating what a relation asserts requires pointing at one clause of its target, the target is two documents.
Note what this test is not. An overrides edge already means where both bear,
this one wins — the overlap is decided by the two documents’ contents, so an
edge is not over-claiming merely by being silent about scope. The tell is
narrower and shows up in the prose beside the edge: a body that has to explain
which sentence of the target it is arguing with.
The worked case is a record of an assistant’s operating constitution, which
contains no decisions at all. A boundary — never infer a person’s pronouns
from their name — declares that it overrides a practice titled deliver the
whole requested scope; state assumptions rather than narrowing. But the
boundary’s body does not argue with delivering the whole scope. It argues with
a different claim the same document happens to carry: make the routine
judgment call yourself rather than escalating it. The override had to say so
in prose, because the code it names covers both.
Applying the first test confirms it. Deliver the whole scope and make the routine call yourself could be adopted separately — a project could want one and reject the other — so they were always two practices. They had simply arrived in the same paragraph of the source. Splitting them let each override name what it actually beats, and immediately exposed a second error: one of the two edges, checked against the narrower practice, turned out not to hold at all.
That is the useful property. The a-priori test needs an author to stop and ask. This one arrives as friction while writing something else, which is when a granularity defect is cheapest to notice and most likely to be noticed at all.
The general form is DP-016 — an awkward structure is reporting a distinction the model has stopped expressing — and this is its granularity case. What that principle adds is the instruction not to resolve the awkwardness with a clarifying sentence, which is always available and always leaves the model wrong.
Why not just qualify the edge
Because a condition on a relation is unfalsifiable in exactly the way this
record’s machinery exists to prevent. overrides is checked — the code must
resolve, to a document of the declared scheme, that actually exists. A when:
beside it is prose in a data field: nothing evaluates it, nothing notices when
it stops being true, and nothing tells a reader whether the qualifier or the
edge governs their case. It is escalating emphasis in a new costume, one level
up, and the graph it produces is worse than no graph because it looks checked.
This is why #141 puts when
expressions among its non-goals, and why it refuses precedence between
configuration surfaces — a conflict there is an error rather than something a
tie-break rule resolves. Same move: decline the qualifier, and remove what
made it necessary.
What this is not
Not an argument for small documents. A document covering one thing can be long, and usually should be — the context, the alternatives and the consequences of a single claim are most of what makes a record worth keeping.
Nor is it an argument against related documents landing together. Ship them in one contribution if that is honest; give them separate codes so each can be cited, revisited, and retired on its own evidence.
And it is not a licence to split on sight. The second test is the discipline that keeps it honest: split when something points at a part rather than the whole, not whenever a document could conceivably be subdivided. A record of maximally small documents has the same problem in reverse — every claim needs five citations to state, and none of them means anything alone.