--- 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. **How it gets there depends on the branch, and the tool tells you which happened.** The intent is a direct commit to `main` with no pull request — a deliberate exception to this estate's "everything is a PR" rule, because 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. That exception only holds while `main` accepts a direct push. It does not today: the docs repo gained OneDev branch protection (required `validate` and `gate` builds), and a direct push is refused by the pre-receive hook — verified 2026-09-06. `notes_write` handles this itself and falls back to opening a pull request, and its reply says so explicitly, naming the PR number. **Read that reply.** A note that came back as a PR is *proposed*, not live: it is not searchable by `notes_search` and nobody else can see it until the PR is merged. Merge it once CI passes, or the note is one nobody wrote after all. 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.