torbenandClaude Opus 5.5
d66a3f65f4
The seven explanation pages move to docs/explanation/ without a stub, DEVELOPMENT.md becomes docs/dev/development.md (translated to English), dist export leaves docs/dev/ out, docs verify rejects a file outside the five areas, and AGENTS.md states that the stack's human documentation is English. Required migration 9.0.0-docs-diataxis rewrites the old path in an instance's own kb/CONVENTIONS.md. Files changed: - .wikitool-kb.json - AGENTS.md - CHANGES.md - CLAUDE.md - DEVELOPMENT.md - INSTALL.md - README.md - VERSION - docs/dev/development.md - docs/explanation/README.md - docs/explanation/knowledge-and-commitment.md - docs/explanation/language-boundaries.md - docs/explanation/model-and-effort-selection.md - docs/explanation/ownership-and-templates.md - docs/explanation/pipeline-rationale.md - docs/explanation/version-model.md - docs/explanation/why-gates-are-code.md - docs/how-to/README.md - docs/knowledge-and-commitment.md - docs/language-boundaries.md - docs/model-and-effort-selection.md - docs/ownership-and-templates.md - docs/pipeline-rationale.md - docs/reference/README.md - docs/tutorials/README.md - docs/version-model.md - docs/why-gates-are-code.md - instructions/CONTRACT.md - instructions/dev/dev-setup.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-mode.md - instructions/gtd-weekly-review/SKILL.md - instructions/ingest-queue.md - instructions/migrations/6.0.0-type-guidance-split.md - instructions/migrations/9.0.0-docs-diataxis.md - instructions/upgrade-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - tools/CONTRACT.md - tools/chemenu/commands/dist_cmd.py - tools/chemenu/commands/docs_verify.py - tools/chemenu/commands/new_page.py - tools/chemenu/commands/task_cmd.py - tools/chemenu/tasks/protocol.py - tools/chemenu/tests/test_dist_cmd.py - tools/chemenu/tests/test_docs_verify.py - tools/chemenu/tests/test_git_publish.py - tools/chemenu/tests/test_toc.py - types/type-guidance.md Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
91 lines
8.6 KiB
Markdown
91 lines
8.6 KiB
Markdown
---
|
|
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 build session that changed behaviour -
|
|
`stack-build` 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 | Its `cli_contract.CommandRecord` (name, synopsis, properties, exit status, retry policy - `tools/chemenu/cli_contract.py`), then `wikitool docs contract --apply` to regenerate its copy in [tools/CONTRACT.md](../../tools/CONTRACT.md) |
|
|
| 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`, `INSTALL-MCP.md` or the pages under `docs/tutorials/`, `docs/how-to/` and `docs/reference/` names it - AGENTS.md § File naming says which document is for which reader. A new page goes into the area its kind of documentation belongs to; that area's `README.md` says which |
|
|
| The reasoning behind a gate, boundary, or design decision | The `docs/explanation/` page that carries it, if one exists (AGENTS.md § File naming lists all six reached from AGENTS.md itself, plus a seventh reached only from CLAUDE.md). **A decision with no page yet is the gap worth closing**: reasoning that lives only in a Gitea issue never ships - `dist export` carries `docs/explanation/` and no issue tracker, so a distributed instance gets the mechanism without the why |
|
|
| A task-tracker adapter (`tools/chemenu/tasks/`), its recorded fixtures, or the live suite | [instructions/dev/tracker-testing.md](tracker-testing.md), and `MANIFEST.json` beside the fixtures when they were re-recorded |
|
|
| A skill's own step sequence or catalogue | The skill's `SKILL.md` source under `instructions/<name>/` or `instructions/dev/<name>/` |
|
|
| A per-checkout configuration file an instance owns (`.wikitool-tasks.json`, `.wikitool-telemetry.json`, `.wikitool-remotes.json`, `.wikitool-upload.json`) | [INSTALL.md](../../INSTALL.md) § Konfiguration, where an operator looks the shape up; the [setup-instance.md](../setup-instance.md) decision point that offers it during setup; and `doctor`'s own row in [tools/CONTRACT.md](../../tools/CONTRACT.md), since `doctor` is what reports the file's state |
|
|
| An installation instruction - [preflight.md](../preflight.md), [setup-instance.md](../setup-instance.md), [bootstrap.md](../bootstrap.md), [upgrade-instance.md](../upgrade-instance.md) - or `tools/prerequisites.txt` | [INSTALL.md](../../INSTALL.md), the human guide to the same procedure. Read it against the instruction: what to prepare, the sentence for the agent, what the agent asks, where it stops and why. `docs verify` checks only the two enumerable overlaps - the prerequisites lists, which `wikitool docs prerequisites --apply` regenerates from the manifest, and the setup questions: a question the agent asks the user carries `<!-- setup-question: <key> -->` where it is asked in `setup-instance.md`, and `INSTALL.md` § "Was der Agent dich fragt" names it with the same marker. Every other sentence is this session's to compare. `INSTALL.md` does not retell the steps, so a change to their order or wording alone moves nothing there |
|
|
| [dev-setup.md](dev-setup.md), the release workflow (`version bump`/`version release`/`publish`/CI), or another developer-facing process | [docs/dev/development.md](../../docs/dev/development.md), read against it the same way - nothing checks this pair at all. A page under `docs/dev/` is never shipped, so it may link into `instructions/dev/` and cite issue numbers |
|
|
| A new page type the stack requires, or a new collection | Its type-spec and `COLLECTION.md` (both as the `.template` an instance adopts), the collection table in [kb/CONTRACT.md](../../kb/CONTRACT.md), and **both adoption paths**: [setup-instance.md](../setup-instance.md) for a fresh instance and [upgrade-instance.md](../upgrade-instance.md) for an existing one, where an unadopted template is what `docs verify` refuses |
|
|
|
|
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 in all five areas - each with the `<name>.template` it ships
|
|
as, where one exists, and a `SKILL.md` 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:
|
|
|
|
```bash
|
|
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](../../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/explanation/` 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 in the closing phase 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-development 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 the green CI run as the second, final check.
|