--- name: thermograph-notes description: Where written work belongs — notes vs docs, and how to get either into the docs repo properly. --- # Notes and docs Two destinations, and picking the wrong one is the common mistake. ## Notes — `notes_write` A **note** is working material: a decision and why, an observation, what a call concluded, a thing that surprised you. It lands in `notes/YYYY-MM-DD-slug.md` in the docs repo and is committed **straight to `main`** with no pull request. That is a deliberate exception to this estate's "everything is a PR" rule. The docs repo's `main` is unprotected and its only CI is a markdown validator, so a note needs no review gate — and demanding a pull request per jotting is exactly enough friction that the notes never get written. A note nobody wrote is worth less than a slightly messy note that exists. Write notes freely. Use `append: true` to add to an existing note on the same day and title rather than fragmenting a session across files. Good notes: - **"Prod's Swarm log streams have no `service` label."** A fact that cost someone twenty minutes and will cost the next person the same. - **"Chose direct commit for notes because PR-per-note kills the habit."** The reasoning behind a decision, which is the part that evaporates. - **"Lake query was slow until the predicate included `tile`."** A surprise. Not notes: anything that reads like documentation. That is a doc. ## Docs — `docs_write` A **doc** is a publication with an audience. It opens a **pull request** against `main` and is gated by the markdown validator. The sections mean different things: - **`architecture/`** — decisions: what we are going to do and why. Decision records, not tutorials. - **`runbooks/`** — numbered steps a human or agent executes. If it has ordered steps, it belongs here. - **`business/`** — product overview, operating model, costs, roadmap. A doc graduates between sections as it moves from "what we'll do" to "exactly how". Mark a superseded doc **Superseded** at the top with the date and what replaced it — never delete it. The decision trail is the point. ### The business/ rule Keep claims **grounded in the shipped system**. Never invent revenue, users, or commitments. Mark genuinely open strategy calls **`Decision needed`** rather than presuming an answer. It is a working document for a real business, not a pitch deck. ### Linking Cross-reference by **repo-root-relative** link (`architecture/foo.md`), never absolute and never `docs/`-prefixed — that prefix is a leftover from before the repo split and is a bug the validator will not catch inside backticks. ## The pipeline ``` voice call → transcript → notes → summary → doc ``` Each step loses volume and gains durability. Search in the same order when you are looking for something: `voice_search` for what was said, `notes_search` for what was written down, `docs_search` for what was actually decided. ## Before you write Search first. `notes_search` and `docs_search` are cheap, and the thing you are about to write down is often already there — in which case update it rather than adding a second slightly-different account of the same fact.