Skip to content

The record shape owes a section the 2026-09-05 wording rule refuses, and that rule's own command finds none of the sixty-five #314

Description

@iderex

Two sentences of the record rule sit next to each other and pull in opposite
directions on one heading, and the command the second hands a reader to derive
its own population finds none of the sixty-five records that carry it. The first
record written under the second sentence carries it too.

What is wrong

Read at the mainline as it stands.

git rev-parse origin/main
13defcfc4b8f660d946666c6a90dfe70f221ed6a
git show origin/main:CONTRIBUTING.md | sed -n '440,444p'
A decision that shapes this repository is a file under `docs/decisions/`, in the
shape `docs/decisions/0001-decision-records.md` fixes: what was decided in one
sentence, what would have gone wrong without the record, the alternatives with
what each one cost, and a reversal condition somebody can check against the world.
A record is added or superseded and never edited in place.

So a record owes a section saying what would have gone wrong without it. Eleven
lines below:

git show origin/main:CONTRIBUTING.md | sed -n '450,455p'
A record written from 2026-09-05 on states what it decides and does not explain
why the record exists or speak about itself. "The failure this record exists to
prevent" and "what this section exists for" are the shapes it does not use: a
sentence about the record's own presence tells a reader nothing that the
decision, the failure and the reversal condition do not already say. Records
that predate that date keep their wording deliberately. The register allows

The register meets the first requirement under one heading, in every record it
holds:

git grep -l 'Why this is written down' origin/main -- docs/decisions/ | wc -l
65
git ls-tree --name-only origin/main docs/decisions/ | grep -vc README
66

Sixty-five of sixty-six, and the sixty-sixth meets the same requirement under a
heading that names the subject instead:

git ls-tree --name-only origin/main docs/decisions/ | grep -v README | sort > all.txt
git grep -l 'Why this is written down' origin/main -- docs/decisions/ | sed 's#origin/main:##' | sort > with.txt
comm -13 with.txt all.txt
docs/decisions/0116-learning-that-something-cached-has-changed.md
git grep -n '^## Why listening' origin/main -- docs/decisions/0116-learning-that-something-cached-has-changed.md
origin/main:docs/decisions/0116-learning-that-something-cached-has-changed.md:62:## Why listening, and what it does not buy

That one is from 2026-08-16 and predates the rule, so it is an existing shape
rather than a decision anybody has taken, and it is named here because it is what
the answer would look like if the heading is refused.

A heading beginning "Why this is written down" is a sentence about the record's
own presence, which is what the second rule refuses,
and the section under it is what the first rule requires. Whether the heading is
inside or outside that refusal is not stated anywhere, and it decides how every
record from now on opens that section.

What the derivation command does not see

The rule hands a reader a command for the population that carries the shape:

git grep -nE "this (record|section) exists" origin/main -- docs/decisions/ | wc -l
12
git grep -nE "this (record|section) exists" origin/main -- docs/decisions/ | grep -c 'Why this is written down'
0

Twelve sites, and the heading sixty-five records carry is in none of them. A
reader deriving the population from that command reads it as twelve paragraphs in
eleven old records rather than as a shape the whole register uses, and takes the
rule for one about a rare wording.

What has already arrived under the rule

One record in the register is dated on or after the day the rule takes:

git grep -l '^Date: 2026-09-0[5-9]' origin/main -- docs/decisions/
origin/main:docs/decisions/0303-the-licence-the-core-is-offered-under.md
git grep -n '^## Why this is written down' origin/main -- docs/decisions/0303-the-licence-the-core-is-offered-under.md
origin/main:docs/decisions/0303-the-licence-the-core-is-offered-under.md:383:## Why this is written down before the code

The record that landed on the same day as the rule carries the heading, and the
rule's own closing sentence says why nothing caught it:

git show origin/main:CONTRIBUTING.md | sed -n '462,463p'
Nothing refuses the shape in a new record. The rule is prose, and the review of
the pull request that adds the record is where it is caught.

That review is where it would have been caught and there was no second reader for
it, which the comment on #291 already discloses for that landing. The wording of a
landed record is not one of the three in-place edits the register allows, so
whatever is decided here reaches the next record rather than that one.

Done when

  • Whether a heading of that shape is inside or outside the 2026-09-05 rule is
    answered where the rule lives, so the next record's author reads one thing
    rather than two.
  • The command that rule hands a reader either returns the population the rule is
    about, or the rule says in one sentence which part of the population it returns.
  • The answer names what a record written from now on puts in place of the heading
    where one is refused, since 0001 still requires the section under it.

Scope: CONTRIBUTING.md

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

blocked-on-decisionWaits on an entry of #1 that is not answered yetdecisionAn architecture decision that must be written down with its reasonsdocumentationImprovements or additions to documentation

Type

No type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions