writing-docslisted

# Writing docs an agent will actually use Governs: shared/scripts/context/before_write.py A document is read because something happened. That event is its **reading trigger**, and it decides everything: where the file goes, how long it may be, and what shape it takes. Documents written without one become reference material nobody references. ## Fix the top level; leave the interior free | Directory | Trigger | What it holds | |---|---|---| | `how-to/` | I am about to do a thing | Ordered steps, each ending in an observable criterion | | `reference/` | I need to look up a fact | Facts keyed for lookup, carried by working examples | | `decisions/` | Why is it like this? | Numbered from the PR, dated, superseded rather than edited | | `exec-plans/` | What are we in the middle of? | Goal · steps with state · what would abort it | Four directories, fixed. **Inside each one, organise however suits the material.** Both halves are evidence, not taste: a mandated shallow top level with a free interior is the arrangement that survived a decade across hundreds of OpenStack repositories, while two controlled studies — one on 65 people, one on 1,650 agent sessions — each found *no* effect from documentation shape. So the constraint sits where something was measured and stays off where nothing was. Templates in `references/kinds.md` are advice. Additions to the top level are fine once `docs/index.md` routes them. A directory that forks a required name (`adr/`, `howto/`, `plans/`) is