The notes tier is opt-in, so a session pays for not reading it before it knows it needed to nf-0yn ← Beads

Twinned from https://github.com/cfsh/ninefold/issues/765 by tools/beads/import_github.py's reconcile pass.

Filed unclaimed after session:design-005 (#686), as evidence rather than opinion: the three most expensive process mistakes I made were each documented, in the notes file the task pointed at, and I did not open it until after paying.

The three

| what I did | what the docs already said | where | |---|---|---| | ran a full review_now after nearly every fix commit — ~12 times | *"once per batch, not once per push"* | CLAUDE.md:212 | | ran a full review_now to refresh a check stale after a rebase — 4 times | *"Your check is stale after a push? One command, ~12s, no model: --reconcile-only"* and ⚠️ *"Do NOT use a full review_now for this … minutes and tokens, to move something whose actual work is three seconds"* | notes/merging.md:179-189 | | posted a RELEASE marker as a markdown heading (## RELEASE …), so wrap_up.py refused | *"The marker is an issue comment whose FIRST line is …"* | notes/chunks.md:70 |

⚠️ notes/merging.md is the sharpest case: the note exists *specifically* to stop the expensive route, names the cost, and I took the expensive route four times — in a session where the CTO later asked why so much context went on four PRs.

Why this is a system observation and not just my error

The notes tier is opt-in by design — notes/README.md: *"loaded by the session that needs it"* — and CLAUDE.md's loop step 6 does point at notes/merging.md. The failure mode is that a session does not know it needs the file until after it has paid for not reading it, and nothing in the loop makes the read happen at the moment of use. Every one of the three above is a first-time-in-session action: first merge, first stale check, first RELEASE.

⚠️ The reviewer charter already solved this for itself: *"Read the relevant notes file before calling a convention absent — CLAUDE.md alone is not the full ruleset."* There is no equivalent instruction for a coding session before performing a step for the first time.

Directions, not a decision

• A just-in-time read instruction at the step, not only a topic pointer: e.g. loop step 7 becoming *"before your first merge_pr.py of a session, read notes/merging.md"*. Cheapest, and it matches how the reviewer charter fixed the same gap.
• Make the tool say it. merge_pr.py's refusal on a stale authority check could name --reconcile-only directly (that specific refusal is #761 item 1). A tool that knows the remedy should print it rather than rely on the reader having read a file.
• A first-use hint in the tools themselves — merge_pr.py/wrap_up.py printing → notes/merging.md on their first invocation per session. Weakest; it is one more line every reader learns to skip.
• ⚠️ Not "put it in CLAUDE.md" — that is the tax notes/README.md exists to avoid, and #551 deliberately moved detail out of it.

Related, and all measured in the same session: #726 (the poll digest is 256 KB, 93% of it issues printed in full — and a full digest is what CHANGED correctly tells you to run), #482 (mutation scaffolding does not survive the session, so a fix is verified only against the defect that prompted it), #761 (stack-merge mechanics).

Refs #686 · Refs #761 · Refs #726 · Refs #551