Skip to content

Record the answers to entries 5 and 7 where the work reads them - #203

Merged
iderex merged 1 commit into
mainfrom
documentation/records-for-the-mark-and-the-pictures
Aug 26, 2026
Merged

iderex merged 1 commit into
mainfrom
documentation/records-for-the-mark-and-the-pictures

Conversation

@iderex

@iderex iderex commented Aug 26, 2026

Copy link
Copy Markdown
Contributor

What was wrong

The Done-when on #7 asks for more than answers. It asks that every one of the
nine entries carry an answer written down where the work that depends on it can
read it, and that an entry whose answer belongs in a decision record point at
the record carrying it.

Nine entries have answers. Four of them are written only on the tracker, and the
tree behind the domain holds nothing for any of the four:

for pat in typographic 'drawn mark' screenshot imprint funding; do
  printf '%-14s ' "$pat"
  git grep -l -iE "$pat" c6fe593 -- decisions/ docs/ content/ | tr '\n' ' '
  echo ""
done
typographic
drawn mark
screenshot
imprint
funding

Run 2026-08-26 at c6fe593. Every line is empty, which is the finding.

Two of those four are entries this tree has already been built against, and one
of them was built against by the change immediately before this one. The mark is
produced by the build now, and the package that draws it opened by stating what
was decided with nothing in the repository behind the sentence:

git show c6fe593:internal/icon/icon.go | sed -n '12,13p'
// What the mark is was decided as a typographic icon and no drawn mark, so what
// is here is a letter set in the reader's own font rather than artwork. That

Run 2026-08-26. That is the shape this directory exists to prevent. Its own
README puts it plainly: the decisions have to exist before the code that assumes
them, and here the code went first.

What this does

Two records, in the shape the README and the template fix.

0015-what-the-mark-is.md carries entry 7: a typographic icon and no drawn
mark, with the measurement the entry was taken against, why a derivable letter
is worth more here than an asset nothing can check, what a drawn mark and no
icon at all would each have cost, and what would make it worth revisiting.

0016-whether-the-pages-carry-pictures.md carries entry 5: one current image on
the landing page and textual plugin pages, with the staleness surface and the
budget as the reasons, and per-plugin screenshots left as something that arrives
additively rather than something refused.

Each names the other under ## What this record does not decide, because the
two were answered on one day and are the two halves a reader will otherwise
assume one record settled.

Neither record decides anything. Both are answers already taken, written where
the work reads them, with the alternatives and their costs as the entry laid
them out.

The icon package cites 0015 instead of stating the decision unattributed:

grep -n '0015-what-the-mark-is' internal/icon/icon.go
13:// decisions/0015-what-the-mark-is.md, so what is here is a letter set in the

Run at c9771ac.

Closes

Closes nothing. #7 closes when all nine entries meet its Done-when, and this
change meets it for two of them. Entries 8 and 9 are still written only on the
tracker, and the second half of the condition, that each issue which waited on
an entry names the answer it proceeded on, is a reading across the board rather
than a change to this tree. Both are written into #7 with what is left.

What was run

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, 1 owed and not decided
7 of 7 legs ran. None was skipped.

The formatter that judges markdown on a pull request here reaches further than
the gate does, so it was run at the pinned version rather than assumed:

npx --yes "prettier@$(jq -er '.[] | select(.id == "prettier") | .version' pins.json)" --check --end-of-line auto "decisions/*.md"
Checking formatting...
All matched files use Prettier code style!

The needs-network set was not asked for and no result from it is claimed here.
Nothing was skipped for a display or for elevation.

No guard is added by this change, so there is none to show biting. What it adds
is prose, and the README beside it says plainly that nothing reads these
headings and no check refuses a record that omits one. That is the residual and
this sentence is the disclosure, not a softening of it.

The means

Markdown in decisions/, which is where this repository already puts a decision
of record, in the shape 0000-template.md carries and README.md states. The
means is not chosen here so much as followed: a record written anywhere else
would be a second home for the same class of thing, and the directory is the one
a reader is sent to.

Nothing about these two records is a number or a rule, so neither carries a
## What was measured heading of the kind the template makes room for, with one
exception: 0015 carries the reading the entry was taken against, because that
reading is what made the question unavoidable.

It adds no language, no runtime and no dependency.

Who read it

Nobody. This board requires no approving review and no status check on the
default branch, so this pull request is merged by whoever opened it, and there is
no second reader on it tonight. The evidence above stands in place of one.

These two records state answers taken elsewhere and add nothing to them. If
either has put an answer differently from how it was given, that is the failure
to look for, and the entry on #7 is the authority rather than the record.

The Done-when here asks that every entry carry an answer written down where
the work that depends on it can read it, and that an entry whose answer belongs
in a decision record point at the record carrying it. Nine entries have answers
and four of them are written only on the tracker.

Two of those four are the ones this tree has already built against. The mark is
produced by the build and its package doc states what was decided, with nothing
in the repository behind that sentence, which is the shape the decisions
directory exists to prevent: a record has to exist before the code that assumes
it, and here the code went first.

0015 carries what the mark is. 0016 carries whether the pages carry pictures.
Both are the answers as they were taken, with the alternatives and what each
would have cost, and neither decides anything on its own. The icon package now
cites 0015 rather than stating the decision unattributed.

The two entries left writing only on the tracker are 8 and 9. They are named in
the issue rather than here, because the pages they belong to are not this
change.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit ad8b25c into main Aug 26, 2026
17 checks passed
@iderex
iderex deleted the documentation/records-for-the-mark-and-the-pictures branch August 26, 2026 20:43
@iderex iderex mentioned this pull request Aug 26, 2026
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.

1 participant