Skip to content

Write in the first person where a role word described me - #223

Merged
iderex merged 1 commit into
mainfrom
documentation/the-decision-records-report-on-me-from-outside
Aug 31, 2026
Merged

Write in the first person where a role word described me#223
iderex merged 1 commit into
mainfrom
documentation/the-decision-records-report-on-me-from-outside

Conversation

@iderex

@iderex iderex commented Aug 31, 2026

Copy link
Copy Markdown
Contributor

What was wrong

Three tracked files described me from outside with a role word instead of
saying "I". The word is maintainer, and it stands in this body only inside
backticks and indented blocks, so that the sentences of the body are themselves
in the voice the change is about.

At the base commit cfa174a:

git grep -in maintainer -- .
decisions/0004-one-table-two-places.md:64:tree from a source its own maintainer is not reading.
decisions/0006-what-answers-at-the-catalogue-address.md:78:Whether the domain moves at all is the maintainer's call, as entry 3 of issue #7.
decisions/0008-the-url-shape.md:99:Where the addresses are served from is entry 3 of issue #7 and is the maintainer's

Three files, three occurrences, and the set is exactly the one issue #220 names.
None of the three is text taken from somewhere else: the licence, the DCO and
the notice file carry no occurrence, so the exemption the issue reserves for
somebody else's vocabulary has an empty population here and no file is left
behind under it.

What this does

decisions/0004 argued the cost of having this build write the organisation
profile table directly, and one part of that cost was commits landing in that
tree from a source its own holder was not reading. That tree is Flowfin/.github,
and its roster record in the operations tree names one writer:

git -C <operations> show origin/main:store/repo/.github.md | sed -n '1,8p'
Kind: repo
Id: .github
Mainline: main
Visibility: public
Language: en
Tracker: owned
Owner: Flowfin
Writers: iderex

So the sentence was about me, and it now reads "from a source I am not reading
when I edit it by hand". The cost it names is unchanged; who bears it is now
stated rather than displaced onto a third person.

decisions/0006 and decisions/0008 each handed entry 3 of issue #7 to
somebody named in the third person, under their own "What this record does not
decide" heading. That call is mine, and both now say "is my call". Neither
record decides the question either way, before or after.

What this prevents is a reader learning the project's voice from the text and
learning the wrong one. The three records are the ones a reader opens to find
out how a decision is argued here, so a third-person report about me in exactly
those files teaches the shape most reliably.

Two paragraphs are rewrapped where the shorter sentence left a line ragged or
over the width the neighbouring paragraphs use. No other bytes moved.

Closes

Closes #220.

The issue's done-when asks that git grep -il against the head return only
files carrying somebody else's vocabulary. That set is empty here, so the head
returns nothing at all:

git grep -il maintainer -- . ; echo "exit=$?"
exit=1

What this is allowed to be

A landed decision record is never edited to change its answer, and this change
is not that. decisions/README.md draws the line itself:

Corrections that do not change the answer are ordinary edits: a broken
link, a misspelled identifier, a command that has to change because the
thing it queries moved. If the correction changes what a reader would
decide after reading it, it is not a correction and it needs a new record.

Read against that test: 0004 still rejects the same alternative for the same
cost, 0006 still leaves the domain question open, and 0008 still leaves the
serving question open. A reader reaches the same decision after each of the
three as before, so none of them needs a new number and none supersedes
anything.

What was run

At the head commit e719027b2498529d22e2555a4020a64cd470aaa9:

go run . ci
gate: 7 legs, in order: format, vet, test, build, links, sitemap, invariants
  needs-network was not asked for. Asking costs a request to the public name from whatever machine runs it, and a verdict that moves when somebody else's service does rather than when this tree changes. Ask with: go run ./harness/needs-network
  format: ok, 74 file(s)
  vet: ok
  test: ok, 37 test file(s)
  build: ok, 22 file(s)
  links: every reference that stays inside this site resolves to a file the build wrote
  sitemap: every page the build wrote is listed once, and every entry has a page behind it
  invariants: ok, 39 rule(s) decided, 2 owed and not decided
7 of 7 legs ran. None was skipped.

go run . hygiene origin/main HEAD
hygiene: 1 non-merge commit(s) in origin/main..HEAD, origin internal
  e719027b2498: subject carries its reference
1 commit(s) judged, none refused.

needs-network was not asked for and is disclosed here rather than left out:
it reaches a public name over the network, and nothing in this change touches
what it would read. go run . reproduce and go run . pins are not legs and
were not run; this change edits three prose files, adds no version and alters
nothing the build reads to render a page, which the gate's own build leg
confirms by writing the same 22 files.

The two rules the invariant leg reports as owed and not decided,
image-dimensions-match-the-file and
text-token-clears-the-declared-contrast-floor, were owed before this change
and are owed after it. Nothing here moves either.

No test was skipped. None of the legs asks for a display or for elevation.

The means

Prose in the Markdown files that already hold these records, edited in place.
Nothing else fits: the subject of the change is the wording of three tracked
sentences, so the means is the file the sentence is in. It adds no language, no
runtime and no dependency, and it is judged by the suite that is already here.
The format leg reads Go source and not these files; what reads them is the
invariants leg, whose tracked-text population covers all three:

go run . invariants | grep 'tracked-text-names-no-tool'
  tracked-text-names-no-tool: ok, 206 file(s) of every tracked text file, except the one declaring the vocabulary

That the population reaches one of these three files is shown rather than
assumed, by putting a marker from the vocabulary into it and watching the row
go red, then restoring the file:

printf '

Generated by ChatGPT and left in.
' >> decisions/0004-one-table-two-places.md
go run . invariants | grep names-no-tool
tracked-text-names-no-tool: REFUSED, 1 violation(s)
git checkout -- decisions/0004-one-table-two-places.md
go run . invariants | grep names-no-tool
tracked-text-names-no-tool: ok, 206 file(s) of every tracked text file, except the one declaring the vocabulary

Run 2026-08-31 at the head commit. That row refuses a produced-by marker and
not a role word, so what it proves is the reach of the population and nothing
about this change's own subject.

This change carries no rule a machine refuses. Nothing in this tree reads a
role word, which the base commit demonstrates: the gate was green with all
three occurrences in place. The property that would refuse the next one is not
built here and is not claimed to be, so what holds this rule after the merge is
the reading, not a check.

Why this is the second pull request for one change

Pull request #222 carried this same change and its head commit lacked the DCO
trailer, so the sign-off gate refused it:

FAIL  baed74e25c19a869db8d231cc149a7f975657380 is missing: Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>

Read from the run of .github/workflows/dco.yml on that head, 2026-08-31. The
repair for a wrong history is a new branch name rather than a rewrite of the
one already pushed, so the commit was cherry-picked with the trailer onto
documentation/the-decision-records-report-on-me-from-outside, this pull
request opened from it, and #222 closed with the reason in its own body. The
content of the three edits is unchanged between the two heads:

git diff baed74e25c19a869db8d231cc149a7f975657380 e719027b2498 --stat
(no output)

Who read it

Only me. The ruleset on the default branch requires no approving review, so
this is merged by whoever opened it, and there is no second reader on this
board tonight. The commands above and their output stand in place of one.

Three tracked files described me from outside instead of saying "I". The text
this project carries is written in the first person, so a word that reports on
me from outside is a defect in the voice rather than a wording preference. The
word is `maintainer`, and it stands here only inside backticks and indented
blocks so that the sentences of this message are themselves in the voice they
are about.

Before, at cfa174a:

    git grep -icl maintainer -- . | wc -l
    3

`decisions/0004` said commits would land in the organisation profile tree from
a source its own holder was not reading. That tree is Flowfin/.github, and its
roster record in the operations tree names one writer:

    git -C G:/Github/operations show origin/main:store/repo/.github.md | sed -n '7,8p'
    Owner: Flowfin
    Writers: iderex

So the sentence was about me and now says so.

`decisions/0006` and `decisions/0008` both handed entry 3 of issue #7 to
somebody named in the third person. That call is mine, and both records now
say so.

Each of the three is a correction that does not change the answer, which
`decisions/README.md` admits as an ordinary edit on a landed record:

    Corrections that do not change the answer are ordinary edits: a broken
    link, a misspelled identifier, a command that has to change because the
    thing it queries moved.

None of the three moves what a reader would decide after reading the record,
so none of them needs a new number and none of them supersedes anything.

After:

    git grep -il maintainer -- . ; echo "exit=$?"
    exit=1

    go run . ci
    7 of 7 legs ran. None was skipped.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex iderex added this to the Decisions of record milestone Aug 31, 2026
@iderex iderex added the documentation Improvements or additions to documentation label Aug 31, 2026
@iderex iderex self-assigned this Aug 31, 2026
@iderex
iderex merged commit acf49ee into main Aug 31, 2026
17 checks passed
@iderex
iderex deleted the documentation/the-decision-records-report-on-me-from-outside branch August 31, 2026 10:24
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Remove a role word from this project's tracked files

1 participant