Skip to content

Admit the section heading the wording rule reads as a sentence about the record - #509

Merged
iderex merged 1 commit into
mainfrom
af01-core/heading-outside-the-wording-rule
Sep 18, 2026
Merged

iderex merged 1 commit into
mainfrom
af01-core/heading-outside-the-wording-rule

Conversation

@iderex

@iderex iderex commented Sep 18, 2026

Copy link
Copy Markdown
Contributor

What changed

The ## Decisions section of CONTRIBUTING.md carried two sentences that
pulled in opposite directions on one heading, and neither said which of them
reached it. The first requires a record to carry a section saying what would
have gone wrong without it. The second, in force from 2026-09-05, refuses prose
that explains the record's own presence - and a heading opening
Why this is written down reads as exactly that while being the title of the
section the first sentence requires.

This adds two paragraphs. One says a heading is the name of a section and is
outside the refusal, so the heading is admitted and nothing is put in its place.
The other bounds the derivation command the rule already hands a reader: it
returns the refused sentences and no heading.

The specific failure it prevents

The next record's author reads two sentences of one section and has to guess
which governs the heading. The only route that catches a wrong guess is the
review of the pull request that adds the record, which the same section says in
its own words, and this board has no second reader.

Evidence

Read on 2026-09-18 at the mainline this branch is cut from,
bad66a2.

The register almost entirely uses the heading:

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

Sixty-six of sixty-seven. The command the rule hands a reader returns none of
them:

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 is in none of them. So a reader deriving the
subject from that command reads the rule as one about a rare wording rather than
as one that could have reached the shape almost every record carries - which is
the second paragraph this change adds.

The one record that does not carry the heading names its subject instead, and
predates the rule:

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' 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

The body of #314 counted sixty-five of sixty-six. The register has gained one
record since that reading and both numbers moved by one; nothing else in the
reading changed, and the counts above are the ones taken at this branch's base
rather than the ones carried from the issue.

The Split: line

#314 was opened on 2026-09-07 and its body carried no Split: line, which the
comment of 2026-09-17 on that issue records together with the examination behind
the answer: the issue is childless, and its three done-conditions are one wording
rule at one site rather than three pieces of work. That comment states the
refusal lands on the change rather than on the issue and is paid by whoever
pushes it. Split: none is now the first line of the body. The examination is
not written again here or there.

The guards this ran through

No guard is added or edited, so there is no deliberate violation to show. The
document checks were run at the commit being pushed:

bash .github/doc-paths/doc-paths.sh check
ok    81 document(s), 410 named path(s) resolved, 0 excused as examples

bash .github/format/format.sh check
Every tracked source file above is written the way the formatter would write it.

One file is touched:

git diff --name-only origin/main...HEAD
CONTRIBUTING.md

No cargo run was made, because nothing this change touches is compiled.

What this does not cover

  • Nothing refuses the shape in a new record. The section already says so in
    its own words and this change does not alter that. The rule is prose, a record
    written tomorrow with a heading of any shape passes every check in this tree,
    and the review is where it is caught. No check is added here.
  • The wording of any landed record. Rewording is not one of the in-place
    edits the register allows, so the answer reaches the next record and not the
    sixty-seven that stand.
  • 0116's heading. It predates the rule and keeps its wording by the sentence
    that was already there. This neither blesses nor refuses it as a second shape.
  • Whether the twelve sites the derivation command returns should be reworded.
    They are landed records, the sentence above them says they stay, and nothing
    here reopens that.
  • Any other disagreement inside the Decisions section. Only the heading
    question 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 names was read.

Who has read this

Nobody other than its author. There is no second reader on this board tonight,
and the commands above are quoted with their output so the reading can be
repeated rather than trusted.

Closes #314

…the record

Two sentences of the Decisions section pulled in opposite directions on one
heading. The first requires a section saying what would have gone wrong without
the record. The second refuses prose that explains the record's own presence,
and a heading opening `Why this is written down` reads as exactly that, while
being the title of the section the first sentence requires. Nothing said which
of the two reached it, and it decides how every record from now on opens that
section.

A heading is the name of a section and is outside the refusal. What is refused
is prose explaining the record's own presence; what stands under the heading is
the failure the record prevents. So the heading is admitted, nothing is put in
its place, and a record written from now on opens that section the way the
register already does.

The command the rule hands a reader for its own population gains its bound in
the same breath. It returns the refused sentences and no heading, so a reader
deriving the subject from it takes the rule for one about a rare wording rather
than one that could have reached the shape nearly every record carries.

    git grep -nE "this (record|section) exists" -- docs/decisions/

What this prevents is the next record's author reading two sentences of one
section and having to guess which of them governs the heading, with the only
route that would catch a wrong guess being a review this board has no second
reader for.

Closes #314

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 243f6e1 into main Sep 18, 2026
28 checks passed
@iderex
iderex deleted the af01-core/heading-outside-the-wording-rule branch September 18, 2026 13:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant