Write down that a typed value is a defect, not a documentation problem #27

2026-09-01T23:23:49-07:00

dejima-agent commented

2026-09-01 23:23:49 -07:00

Summary generated by LLM agent

The lesson from dejima-ci-hardener's v3 migration, recorded where the next agent working on this repository will meet it.

Every step of that migration which asked an operator to type something went wrong on a real host, and every fix was to stop asking rather than to ask more clearly. A note that names a path, a network or a count is a note somebody runs twice, changing the obvious part and leaving the rest.

This repository already gets it right in one place, which is the example worth reaching for before adding another prompt: nothing asks an operator to record the guest version, because bootstrap knows it. mark-node exists only for the half no guest can see.

The section also says what to do where a value genuinely has to be given: make the wrong one refuse rather than proceed. A check that catches the mistake is worth more than a paragraph describing it, because the paragraph is read once and the check runs every time.

Tested: 188 passing, unchanged. Documentation only.

**Summary generated by LLM agent** The lesson from dejima-ci-hardener's v3 migration, recorded where the next agent working on this repository will meet it. Every step of that migration which asked an operator to type something went wrong on a real host, and every fix was to stop asking rather than to ask more clearly. A note that names a path, a network or a count is a note somebody runs twice, changing the obvious part and leaving the rest. This repository already gets it right in one place, which is the example worth reaching for before adding another prompt: nothing asks an operator to record the guest version, because bootstrap knows it. `mark-node` exists only for the half no guest can see. The section also says what to do where a value genuinely has to be given: make the wrong one refuse rather than proceed. A check that catches the mistake is worth more than a paragraph describing it, because the paragraph is read once and the check runs every time. Tested: 188 passing, unchanged. Documentation only.

dejima-agent added 1 commit 2026-09-01 23:23:49 -07:00

Write down that a typed value is a defect, not a documentation problem

tests / runner-env (pull_request_target) Successful in 36s

Details

tests / tests (pull_request_target) Successful in 1m13s

Details

88b4390e3e

The lesson from dejima-ci-hardener's per-pool migration, where every step that
asked an operator to type something was a step that went wrong on a real host,
and every fix was to stop asking rather than to ask more clearly.

Recorded here rather than only there because the failure shape is the same in
both: a note that names a path, a network or a count is a note somebody runs
twice, changing the obvious part and leaving the rest. This repository already
gets it right in one place - bootstrap records the guest version, so nothing
asks an operator to - which is the example worth reaching for before adding
another prompt.

branderson approved these changes 2026-09-01 23:40:48 -07:00

branderson merged commit 762282b0d4 into main

2026-09-01 23:40:52 -07:00

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: dejima/dejima-devbox-hardener#27