Skip to content

The cutover runbook names the answer it proceeds on [#7] - #210

Merged
iderex merged 1 commit into
mainfrom
documentation/the-runbook-names-the-answer-it-proceeds-on
Aug 27, 2026
Merged

The cutover runbook names the answer it proceeds on [#7]#210
iderex merged 1 commit into
mainfrom
documentation/the-runbook-names-the-answer-it-proceeds-on

Conversation

@iderex

@iderex iderex commented Aug 27, 2026

Copy link
Copy Markdown
Contributor

What was wrong

docs/domain-cutover.md told its reader that whether the domain moves, and
when, is an open question. It said so twice, at the top and in its closing
section:

git show origin/main:docs/domain-cutover.md | grep -n 'entry 3 of #7'
7:It does not decide whether the domain moves, or when. That is entry 3 of #7 and
322:Whether the domain moves at all, and on what schedule, is entry 3 of #7.

That entry was answered on 2026-08-24:

gh issue view 7 --repo Flowfin/site --json comments \
  --jq '.comments[]|select(.createdAt=="2026-08-24T18:18:14Z")|.body' \
  | sed -n '1p'
Answer to entry 3, decided 2026-08-24: the new site goes live on a subdomain first, is proven there, and the cutover happens against a standing target - the catalogue address answers throughout, with no resolution gap. Two live sites for a bounded while is the price, paid knowingly.

and it is written in no tracked file:

git grep -l -iE 'subdomain' origin/main -- . ':!*_test.go'
origin/main:decisions/0006-what-answers-at-the-catalogue-address.md

That one hit is the alternative record 0006 priced and rejected for the
catalogue file, not this answer. All three run 2026-08-27 at 21bc843.

The cost is not that a sentence is out of date. This runbook is read on the day
the move is performed, and its own opening says the expensive part is the
ordering. A reader who takes the question for open plans the ordering against
whichever answer they assume.

What this does

The head quotes the answer with the command that reads it, and the closing
section says the entry is answered rather than open.

Naming the answer makes the sequence disagree with it in two places, so a new
section states both and repairs neither.

Step 2 proves the new site at the address the host gives a project site,
https://flowfin.github.io/site/, and the answer says a subdomain. Whether
those are the same thing is not decided in this change.

Step 5 opens a window in which no published site claims the name, and the
answer says the catalogue address answers throughout with no resolution gap.
Both cannot hold as the sequence is written. The document's own reading of the
host is what makes that structural rather than an ordering mistake: one custom
domain is attached to one published site at a time, so the old site releases the
name before the new one can take it. Closing the window therefore means either a
route this document has not found or the clause forbidding the gap giving way,
and neither is chosen here.

The sentence claiming the sequence is the same on any answer that ends with this
repository as the origin is removed, because the answer that arrived is one it is
not the same on.

Closes

Nothing. #7 closes when every one of its nine entries carries an answer written
down where the work that depends on it can read it, and when each issue that
waited on an entry names the answer it proceeded on. This change discharges that
for one entry in one document. Entries 8 and 9 are still written only on the
issue, entry 2 owes a pointer, and the pass over the issues citing an entry is
not this change.

What was run

At c5363658f977c7ae260984f363e7c0fc30783279, the commit being pushed.

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 needs-network set was not asked for, so nothing here was checked against
the live name. That is the same set the runbook's own readings come from, and no
reading in this change depends on it.

The formatter that judges this file is fetched at run time rather than installed,
so it is run separately:

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

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

git diff --name-only origin/main...HEAD
docs/domain-cutover.md

No test was skipped. Nothing here needs a display or elevation.

The means

Markdown in docs/, which is what the file already is, so this adds no
language, no runtime and no dependency. The means was checked rather than
carried over: the alternative was a decision record under decisions/, and it
was rejected because the answer was taken on the tracker rather than here and a
record would be this repository restating somebody else's decision as its own,
which is the drift the runbook is being repaired for. What this change carries
is a claim with the command behind it, which prose can do; it carries no rule,
so there is no guard here to show biting, and the formatter is the only machine
that refuses anything about it.

Who read it

Nobody else. This change carries no second reader, and the evidence above stands
in place of one: every claim it makes is a command with its output, run at the
commit being pushed, and the two claims it does not back that way are named as
claims in the file itself.

The runbook opened by saying that whether the domain moves, and when, is entry
3 of #7 and the maintainer's call, and closed by repeating it. That entry was
answered on 2026-08-24. A document telling its reader a question is open when
it has been answered is read as the state of the plan, and the next person to
open it plans around a decision that has already been taken.

It was found by reading the entry answers on #7 against what the tree carries:
the answer to entry 3 appears in no tracked file, and the two sentences here
were the only places naming that entry at all.

The head now quotes the answer with the command that reads it, and the closing
section says the entry is answered rather than open.

Naming the answer makes the sequence disagree with it in two places, so a new
section states both and repairs neither. Step 2 proves the new site at the
address the host gives a project site rather than at a subdomain. Step 5 opens
a window in which no published site claims the name, and the answer says the
catalogue address answers throughout with no resolution gap; the document's own
reading of the host, that one custom domain attaches to one published site at a
time, is what makes that window structural. Which of the two gives way is a
decision nobody has taken, so it is written down rather than resolved.

The paragraph claiming the sequence is the same on any answer that ends with
this repository as the origin is removed, because the answer that arrived is
one it is not the same on.

Signed-off-by: Nils Lehnen <30603423+iderex@users.noreply.github.com>
@iderex
iderex merged commit 2a1e214 into main Aug 27, 2026
17 checks passed
@iderex
iderex deleted the documentation/the-runbook-names-the-answer-it-proceeds-on branch August 27, 2026 11:35
@iderex iderex mentioned this pull request Aug 27, 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