fix(docs): AGENTS.md-Contract-Prosa als Sitzungsarbeit klargestellt, doc-pull-through-Instruction (schliesst #90)
Files changed: - AGENTS.md - CHANGES.md - VERSION - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/testing-conventions.md - instructions/dev/version-parts.md - tools/chemenu/commands/docs_verify.py
This commit is contained in:
@@ -0,0 +1,67 @@
|
||||
---
|
||||
type: types/instruction.md
|
||||
name: doc-pull-through
|
||||
description: 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](../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 four) |
|
||||
| A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/` |
|
||||
|
||||
3. **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](../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`](stack-close/SKILL.md) 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.
|
||||
Reference in New Issue
Block a user