# Writing an untemplated document

Load when: no template in [`templates/`](../templates/Readme.md) matches the document being written — a design note, a comparison, an investigation writeup, an index, a reference sheet, anything the Routing table sends to "no template matches".

A template is a pre-made set of shape decisions. With no template, make the same decisions explicitly, in this order.

## 1. Decide the nature — truth, record or queue

Every document is exactly one of the three (`SKILL.md` § The three natures). Ask: *when reality changes, is this file rewritten, frozen, or does it lose a row?*

- Rewritten in place → **truth document**. Topic-named (`kebab-case.md`), lives outside `docs/history/`, present tense throughout.
- Frozen → **record**. Date-named (`YYYY-MM-DD-slug.md`), lives in `docs/history/` — inside an existing subfolder where it fits (an investigation or research writeup → `history/research/{topic}/`); a genuinely new category of record needs a `docs/structure.md` folder-rule row in the same change, never an invented folder.
- Loses a row when work is resolved → **queue**. A fixed name, one row per item; extend an existing queue before inventing one.

When a draft wants to be both — the current state *and* the story of getting there — split it: the state becomes a truth document, the story becomes a record that links to it. Never mix the natures in one body.

## 2. Place and name it

- `docs/structure.md` is the placement authority — match the document's topic to its folder map before inventing a location.
- **One canonical home per topic.** If a document on the topic already exists, extend it; a second document on the same topic is drift. Link, don't copy.
- A new topic *folder* gets a `Readme.md` landing page that describes what the folder holds and how its files are named, never a row per file (`type: folder-index`).

## 3. Shape it

- **Open with the goal.** The first line under the H1 states what the document is for and who reads it, so a reader landing cold decides in one sentence whether to keep reading.
- **Headings are noun phrases** — no verb, no tense, no person (`references/style-guide.md` § Labels).
- **Headings are retrieval keys.** Sections get pulled out of context by search and agents; qualify generic headings with the topic (`## Merge rules — data sync`, not `## Rules`) so each stands alone.
- **Tables for enumerable facts, prose for judgment.** One row per item; anything needing a *because* lives in prose around the table, never inside a cell.
- **Every section earns its place.** No empty stubs — omit what has nothing real to say; write an explicit "None" only where the absence itself is information.
- **Build from the outside in.** The question and its boundary, then the model, then the parts, then the detail — and nothing that fails the stability test (`references/style-guide.md` § Shape — the model first, the detail after). An explanation of a concern the whole platform handles is not untemplated: it is `templates/doctrine.md`.
- **Cite sources and link neighbours.** If the document mentions a concept another document owns, link it; if it draws on code, name the directory it lives in — the code graph finds the files, and a file list goes stale.

## 4. Write it in the house style

`references/style-guide.md` carries the rules: present tense with no history narration, progress markers, or stale-reference tripwires (§ The Two Natures); third-person, present-tense, active sentences after noun-phrase labels (§ Voice, § Labels); diagrams in documents only, beside the prose and never in its place (§ Diagrams); signatures, state shapes and code examples under 15 lines in reference documents only (§ Reference documents).

## 5. With a human in the loop — the co-authoring workflow

**Stage 1 — context gathering.** Read what already exists on the topic, then draft the structure from §1–3 with sensible defaults for audience, purpose and format. Ask only the questions whose answer the repository cannot give and a default would get wrong (usually one to three), each with your recommended answer, in one message.

**Stage 2 — draft.** Show the structure with the questions, then draft the whole document on the answers or the defaults. Learn the user's style from the changes they make, and **never** silently rewrite their edits.