Skip to content

Hold the decision records to five antitheses a file - #111

Merged
iderex merged 1 commit into
mainfrom
doc/905-decisions-antithesis
Aug 14, 2026
Merged

Hold the decision records to five antitheses a file#111
iderex merged 1 commit into
mainfrom
doc/905-decisions-antithesis

Conversation

@iderex

@iderex iderex commented Aug 14, 2026

Copy link
Copy Markdown
Contributor

Closes #112.

The fleet text survey graded this board light and found one register: the prose
under decisions/. Tree, issues, pull requests and the last fifty commit
subjects were already free of em dashes, placeholders, emoji and local paths.
What was left was density.

What was measured before this change, at 4ec0540

git grep -cF 'rather than' -- 'decisions/*.md' | awk -F: '$2>5'
decisions/gate-parity.md:16
decisions/speed-budget.md:13
decisions/manifest-schema.md:10
decisions/plugin-identity.md:9
decisions/conformance-declaration.md:8
decisions/release-procedure.md:7
decisions/means.md:6
decisions/first-release.md:6

git grep -nE "this (document|file) (exists|states)"
decisions/design-system-binding.md:129
decisions/gate-parity.md:183
docs/design-tokens.json:79

Eight files above the limit and three self-references. The survey wrote seven and
four; the tree has moved since, so these are the counts at the head this branch
was cut from, and they are what the change is measured against.

What changed, and what it prevents

A contributor reads the decision records before anything else here, so the figure
they meet first is the register the board writes in. Thirty-five sentences drop
their antithesis and say the thing directly.

The kept figures are the ones where the contrast IS the information: a finding
that blocks against one that annotates, a threshold stated against one assumed, a
budget of 0.00 against the 0.1 the ecosystem calls good, a rule runnable against
a planted input against one shown to bite only by breaking the tree, the head
branch against the author association.

The three self-references go too. gate-parity.md names the issue that raised
the failure instead of naming itself, design-system-binding.md points at the
rule above it, source-set-declaration.md points at the declaration it
introduces, and the token file's note says what its values are for.

All four locations the survey named are rewritten, and the closing paragraph of
gate-parity.md now ends on the instruction to re-run the commands.

Measured at this head

git grep -cF 'rather than' -- 'decisions/*.md' | awk -F: '$2>5'
(no line)

git grep -nE "this (document|file) (exists|states)"
(no line, exit 1)

The same grep run case-insensitively also prints no line, which is worth saying
because the survey's count included This file states and the pattern as written
is case-sensitive.

go run . gate
gate examined 14 of 14 legs.
  build, test, format, editorconfig, tests-reach-nothing, no-hardcoded-names,
  site-fetches-nothing-outside, site-links-resolve, coverage,
  site-declares-its-language, install-address-is-answered,
  focus-stands-off-every-surface, page-matches-the-token-file, pr-hygiene
  all passed

Run in a worktree at this branch's head before the push. The harness did not run
and none of its three requirements was asked for; no leg above depends on any of
them, so that verdict is complete.

THE FIRST PUSH WAS REFUSED BY THIS BOARD'S OWN GATE, AND THAT IS RECORDED

Gate: pr-hygiene refused the first version of this request under its blocking
rule: neither the title nor the body carried a #number, so nothing connected
the change to the issue that argued for it. The argument was on another board's
tracker and this one had no issue for it, which is the state the rule exists to
catch. #112 is that issue, opened with the measurement in it, and this body now
names it. The title also came in at 85 characters against the 72 the same leg
annotates on, and it is shorter now.

The local run above passed pr-hygiene because that leg's subject is the pull
request and not the checkout, so it judged nothing on a local run and said so.

The means

Markdown and one JSON string, both unchanged as formats. This is a prose edit
inside files that already exist, so nothing is added to the toolchain and no
suite has anything new to reach.

WHAT THIS DOES NOT DO

It changes no number, no command, no decision and no interface. Every edit is one
sentence saying the same thing in another shape, and the diff is 62 insertions
against 68 deletions across eleven files.

It does not touch the counted figures in files already at or under five, so the
board's total rather than count falls but does not go to zero, and it was never
asked to.

No second reader was available on this board tonight. The gate output and the
commands above stand in place of one.

…t self-reference

The prose under `decisions/` had run to 112 hits of `rather than`, eight files
above five and a peak of sixteen, and three passages explained why they existed.
Both are tells the fleet text survey counts, and the decision records are what a
contributor reads first, so the figure was the register they met.

Eight files come down to five each. The kept figures are the ones where the
contrast carries the information - a finding that blocks against one that
annotates, a threshold stated against one assumed, a budget of 0.00 against the
0.1 the ecosystem calls good - and the rest say the thing without its opposite.

The self-references go with them. `gate-parity.md` no longer names itself as the
thing a dropped leg would fail, `design-system-binding.md` points at the rule
above it, `source-set-declaration.md` points at the declaration it introduces,
and the token file's note says what the values are instead of why the file is
there. The closing paragraph of `gate-parity.md` ends on the instruction to
re-run the commands, no longer on a contrast pair.

    git grep -cF 'rather than' -- 'decisions/*.md' | awk -F: '$2>5'
    (no line)

    git grep -nE "this (document|file) (exists|states)"
    (no line, exit 1)

    go run . gate
    gate examined 14 of 14 legs.  (all passed)

No number, no command and no decision moves. Every edit is a sentence saying the
same thing in a different shape.

Answers operations issue 905.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex iderex changed the title Hold the decision records to five antitheses a file, and drop the last self-reference Hold the decision records to five antitheses a file Aug 14, 2026
@iderex iderex closed this Aug 14, 2026
@iderex iderex reopened this Aug 14, 2026
@iderex
iderex merged commit e376e7a into main Aug 14, 2026
63 of 69 checks passed
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 decision records read as a register, and three explain themselves

1 participant