chemenu/instructions/dev/doc-pull-through.md

type, name, description

type	name	description
types/instruction.md	doc-pull-through	Which document makes a claim about a surface you are about to change - a wikitool command's behaviour, a stage's rules, an AGENTS.md rule/gate/invariant, a README-shaped human doc, a docs/ page's reasoning - and so needs updating in the same session, since tools/wikitool docs verify never reads a cell's prose.

Update every document that makes a claim about the surface you changed

tools/wikitool docs verify is a hard oracle over presence, not content: it checks that a command is listed, that a contract exists, that an ignore canary is (or isn't) caught - never what a table cell, a contract section, or a README paragraph actually says. A command's flag can change, a gate's threshold can move, a contract's wording can go false, and every one of those checks stays green (Gitea #90; Gitea #91 narrows what the command-table check matches, but adds no reading of cell content). Content quality of every document below is therefore session work, the same duty AGENTS.md's Changelog section states for README.md/EVALS.md/ tools/README.md - this instruction exists because that duty used to stop at those three files while the contracts rotted next to a green check (ten stale error-contract rows accumulated this way; see Gitea #89 for one).

When to run

Before tools/wikitool docs verify/publish in a stack-dev session that changed behaviour - stack-dev step 5 sends you here. Read the table below and update every row whose surface you touched; a row that does not apply needs no action.

Steps

1. Name the surface(s) you changed. A wikitool command's flags or behaviour, a stage's rule, an AGENTS.md-level rule/gate/invariant, a workflow a human runs by hand, or the reasoning behind a design decision - one change can touch more than one row.

2. For each surface, update every document the table names - not only the one you were already editing:

   Touched surface	Document(s) that make a claim about it
   A wikitool command's behaviour, flags, or interface	Both tables in tools/CONTRACT.md: the command reference row, and its per-command error contract (exit codes, atomicity, retry-safety)
   A stage's authoring rules (raw/, kb/, types/, reports/, work/, tools/, instructions/)	The touched <stage>/CONTRACT.md
   A rule, gate, or invariant AGENTS.md itself states	The relevant AGENTS.md section (Invariants, Gates, File naming, Routing, ...)
   A workflow, stage, or command a human operates by hand	Whichever of README.md, EVALS.md, tools/README.md, INSTALL.md, DEVELOPMENT.md names it - AGENTS.md § File naming says which document is for which reader
   The reasoning behind a gate, boundary, or design decision	The docs/ page that carries it, if one exists (AGENTS.md § File naming lists all five reached from AGENTS.md itself, plus a sixth reached only from CLAUDE.md)
   A skill's own step sequence or catalogue	The skill's SKILL.md source under instructions/<name>/ or instructions/dev/<name>/

3. A heading you changed means a table of contents to regenerate - by the tool, never by hand. Every reference file over 100 lines carries one (AGENTS.md, the stage contracts, kb/CONVENTIONS.md, each COLLECTION.md, the flat instructions/**.md form, the type-specs, the docs/ pages - a SKILL.md is the one exception). Adding, renaming, reordering or deleting a ##/### heading in one of them makes its region stale, and docs verify fails on stale exactly as it fails on missing:

   tools/wikitool docs toc          # dry run: which files would change
   tools/wikitool docs toc --apply  # write them
   

   The region is generated, so AGENTS.md invariant 1 applies to it like any other: editing the list by hand is the failure, not the fix - and a hand-written entry survives until the next --apply silently disagrees with it. It is cheap to over-run: --apply is idempotent and a file whose headings did not move is left untouched.

4. Do not re-derive what docs verify already checks mechanically - existence, table-row membership, ignore-canary state. That enumeration lives once, in tools/CONTRACT.md's own docs verify row; copying it here would be a second copy that drifts, the exact failure this instruction exists to describe (Gitea #90). This instruction is only about the prose no check reads.

Decision points

• The change touched no document in the table? Nothing to do - not every stack change moves a claim. A pure bugfix with an unchanged interface is the common case.
• Unsure whether a docs/ page's reasoning moved? Read it. A docs/ page carries no normative sentence and nothing verifies it by construction (AGENTS.md § File naming), so an unsure guess defaults to reading the page rather than skipping the question - stack-close step 3 asks it again at the end of the session as a backstop, not as the only time it is asked.
• The surface is a whole new stage, collection, or gate? The table's rows are the steady state; a new row-worthy category is itself a change to this instruction - add the row here rather than leaving the next session to rediscover the gap.

Scope

Applies to stack-dev sessions only - wiki content changes have their own provenance and cross-reference rules (kb/CONTRACT.md, wiki-manage), which already pull the relevant pages through as part of the normal skill. Not a replacement for stack-close step 3, which re-asks the docs/-staleness question after publish as the second, session-final check.