Documentation rules

How documentation is organised and written in this repository. AGENTS.md at the root holds the standing engineering rules; this file holds the ones about prose. The procedure for writing or auditing a page is choruz-doc; sentence-level judgement is choruz-prose-standard.

The tiers: one home per fact

Every fact has exactly one home. Everything else links to it.

Placement: bugs and incidents go to a note or a runbook, rationale to notes, procedures to operations or a skill, definitions to the data model or a subsystem page, package contracts to the package README, standing orders to AGENTS.md with a link.

Writing rules

• Document current state, not change history. No "previously", "now", "no longer", pull request numbers, or migration narration outside archive/ and a note's Consequences.
• Classify every page as a tutorial or a reference. A tutorial orders concepts by prerequisite and ends in an observable outcome; a reference is exhaustive and skimmable. Split a page that tries to be both.
• Test, do not assume. A command, flag, default, error or path appears in a page only after being run or read in the current checkout; delete what did not reproduce.
• Link by relative path, never by bare filename or note number; a link to a heading uses its real anchor.
• One physical line per paragraph. Use editor soft-wrap; hard-wrapped prose makes diffs and greps unreadable.
• Each section opens with a short orienting paragraph before subsections or exhaustive detail.
• Prefer the real identifier: the crate, the table, the endpoint, the env var, the script, so the page can be checked against the tree.
• Chinese is welcome where the existing page is Chinese (README.md, user-facing pages); keep one page in one language.

The slop checklist

Hunt these with the cheapest probe first (git grep a distinctive phrase, word counts, heading counts):

• Duplicated rules: the same instruction in two homes. Keep one, link from the other.
• Narrated history: "we used to", "this was changed", "since PR …".
• Status annotations: "(WIP)", "(deprecated)", "(new)" inside reference prose; status lives in the tree or the note lifecycle.
• Hand-restated inventories: a list the tree, a script or a manifest already owns.
• Reasoning transcripts: "(decision 3)", "as discussed", "the reviewer asked", hedged planning residue.
• Repeated rationale: the why written again where only the what belongs, instead of a link to the note.
• Paragraph walls: a section with no orienting sentence and no structure.
• Emphasis inflation: bold on whole sentences, exclamation marks, superlatives.
• Spec-speak in implemented material: "will", "should", "plan to", acceptance criteria, migration steps in a page or note that describes shipped reality.

Validation

Every non-trivial change updates the document that names what it changed, in the same pull request. python3 scripts/verify_agent_notes.py gates the notes; links are checked by hand or in the rendered preview; a command in a page is re-run before a claim about it merges. A documentation-only pull request runs no test job and merges in seconds, so keep configuration and code out of it.