# Documentation style guide This guide states how a document is written: every file under `docs/` and every README the `documentation` skill authors or edits. Two neighbouring authorities answer the questions beside it: [`instruction-style.md`](instruction-style.md) governs the files an agent obeys (`CLAUDE.md`, rules, agents, skill prose), which are paid for on every load and written lean, and each template in [`templates/`](../templates/Readme.md) governs its genre's sections and fields. The first two sections are enough to write a correct document; the sections after them are the detail each principle unfolds into, so a reader who stops early holds a coarse picture that is true. ## The model A document is read by a person who wants to understand something or to act on it, and it is scanned more often than it is read. Every rule below follows from ten principles; later sections cite them by number. ### Principles 1. **Three natures:** every document is a truth document (what is, now, rewritten in place), a record (what happened, dated and frozen) or a queue (work not done yet, rows appended and deleted when resolved). A truth document never narrates history, a record is never edited to match the present, and a queue holds only open rows, because a reader must be able to trust each without the others. 2. **The outside-in shape:** an explaining document opens on what it defines and its boundary, then the model with its numbered principles, then the parts and their relations, then each part's decisions, and stops at its genre's deepest layer. Each layer is complete on its own, so a reader who stops at any layer holds a picture that is coarse but true. Headings name the concept a section covers, never the layer it sits in. 3. **The stability test:** a sentence that would have to change when a function is renamed, a file moves, a route, column, error code or cookie attribute changes, or a constant is retuned without the design changing belongs to the code, which the code graph computes on demand (`docs/architecture/systems/knowledge-layer.md`), and not to the document. A copy typed into a document is at best a duplicate of the code and at worst a stale one. 4. **The authority split:** the code is the authority on *what*; the document is the authority on *why*. A disagreement on *what* means the document is stale and the code wins; a disagreement on *why* or on an invariant is a defect to raise, because one side is wrong on purpose. Doctrine is the one exception: it is a specification, so code that differs from it has a gap to plan and build (`templates/doctrine.md`). 5. **Noun-phrase labels, third-person sentences:** every heading and every bold bullet label names something and contains no finite verb, so it carries no tense, person or voice. The sentence after a label is third person, present tense, active, with the actor as its subject. 6. **A body scanned by people, a closing for the pointers:** an owning document is bullets under noun-phrase headings, tables wherever the cases are parallel states, code named only where a person types or sees it or at a cross-cutting seam, and a closing that holds pointers, never an inventory: "For the agent" in an owning document, Terms and Related documents in a doctrine document. 7. **Self-contained, never padded:** the body reads whole without opening another file, restating the one sentence of context a borrowed concept needs and citing the authority for the rest. Length is a signal of a document that has let mechanism in, never a target. 8. **Depth per genre:** doctrine stops at decisions and reasons, a system at behaviour across packages, a package at its public contract, a feature runs deepest at its end in Promises, and a reference document or runbook keeps full detail because the detail is its content. 9. **Every line owns a decision:** a line earns its place by stating a rule, a reason, a boundary or a promise a reader would otherwise get wrong. A line restating a rule that has a home is a citation instead, and a line stating nothing is cut, because restatements drift apart and filler buries the rules a reader came for. 10. **Standard terms, one rule per sentence:** a sentence uses the term engineers use for the thing, states one rule, and stops. Its reason, where the rule needs one (§ Sentences), is the next sentence. A plainer synonym reads as vague, and a rule fused with its reason hides which half binds. ## The genres Every genre takes the same shape (principle 2) and the same labels (principle 5); what differs is how deep it may go. | Genre | Nature | Deepest layer | Excluded | | --- | --- | --- | --- | | Doctrine (`docs/architecture/doctrine/`) | Truth | The decisions behind each part and the reasons for them | Any mechanism. A doctrine document describes no code | | Playbook (`docs/architecture/playbooks/`) | Truth | What a person sees and does in the shape, part by part: its arrangement, each part's behaviour, its states and promises | Any one product's values: its labels, routes, limits and timings, which are its feature documents'. Any mechanism | | System (`docs/architecture/systems/`) | Truth | The machine's behaviour across packages: the order it runs in, sequence and state diagrams at role level, the invariant at each place where parts meet, what re-drives a stall. No single file shows a cross-package flow, so this layer earns its place | Per-function steps, tables and columns, routes | | Package (`docs/architecture/packages/`) | Truth | The public contract a consumer touches: commands and their flags, exports, what is installed and where. For a CLI the flags *are* the promise | Internal layout, the build's steps, which file holds what | | Feature (`docs/features/`) | Truth | The behaviour a person meets, in full: each state the surface can be in, each edge case, what a rejection tells them, the wording where the wording is promised. This genre runs deepest toward its end, in Promises, because a promise is checked by a person or a test and the code cannot state it as intent | Columns, routes, guards, functions, files | | Reference (API reference, environment registry) | Truth | The contract itself: signatures, shapes, variables | Nothing. The detail is the point | | Operations procedure, migration runbook | Truth, record | The exact commands, in order, with their expected output | Nothing. The detail is the point | | Record (plan, changelog entry, runbook) | Record | Its template's fields, as of the moment it describes | Nothing. Its prose follows § Voice and § Labels; the dates and the journey are its own | | Queue (backlog, journal, bookkeeping, memory) | Queue | One row per open item, in its template's row grammar | Nothing. A row may carry its own date; a resolved row is deleted | - **Owning documents:** feature, package and system are the three genres that speak for code: source files name them in their headers, and the ownership scan resolves paths to them (`frontmatter.md`). They take principles 5 and 6 in full, their sections are fixed (§ Owning documents — the body and the footer), and `doc-lint` reads them. A UX document also speaks for a surface's components where none of the three does; its sections are its own genre's (`templates/ux-behavior.md`). - **Doctrine:** the same shape and labels as an owning document, speaking for no code and describing no mechanism. Each section opens with a definition or the governing rule, never a lead-in, and continues in bullets like every other explaining document. - **Reference documents and procedures:** the one place a signature, a shape, a variable table, a command list or a file path is the content. They keep the detail the owning genres hand to the graph (§ Reference documents). - **Indexes:** a folder's `Readme.md` describes directories, never files — no link, filename or record ID per file; each file's own `description:` frontmatter is its account. The root README follows `templates/root-readme.md`. Both take § Labels. ## Shape — the model first, the detail after Every truth document a person reads to understand something is written from the outside in (principle 2). The failure this prevents is a document written at one density from its first word: an inventory table before the reader knows what is being inventoried, and the principles that summarize it arriving last, where nobody reads them. ### The layers 1. **The definition and its boundary:** the opening states what the document defines, then what is in scope and what is out of scope, each out-of-scope item pointing to the document that owns it. No scene-setting before it, and no addresses, file paths or configuration in it. 2. **The model:** what the thing is, in a page: the parties or parts, the one or two axes that organize them, and the invariants that hold everywhere, numbered so later sections cite them ("principle 3"), each with its reason where the rule needs one (§ Sentences). 3. **The parts:** one table or diagram placing every part in the model, then how the parts relate: what they share, where they meet, what keeps them apart. 4. **Each part in turn:** for each part, the decisions it rests on and why. A part's section opens with its definition or its governing rule, never with how it is built. Each layer is carried by sections named for their concepts: "Callers", "Principles", "Credential families", "Capability links". A heading never names the layer itself: no "The model", "The parts", "In depth" or "Overview". 5. **The genre's deepest layer:** the row for the genre in § The genres, and nothing deeper. An owning or doctrine document's fixed sections carry these layers; nothing is added beside them to hold a layer: | Layer | Feature | System | Package | Doctrine | | --- | --- | --- | --- | --- | | The definition and its boundary | Goal line, Scope | Opening paragraph, Scope | Identity and goal lines, Scope | Opening sentence and scope bullets | | The model | Scope's In scope bullet | Flow's opening | Usage's opening | The participant sections, then Principles | | The parts | Flows | Flow | Ownership, Usage | The parts table and its relations | | Each part's decisions | Decisions | Decisions | Decisions | One section per part | | The deepest layer | Promises | Promises | Promises | — | ### The stability test The test (principle 3) decides what a sentence may say. These survive it: - **Reasons:** why the design is this way, and what would break otherwise. - **Invariants:** what must hold everywhere. - **Decisions:** the choice made, and the alternative a reader would reach for. - **Promises:** what a person or a test can check. - **Cross-component contracts:** what no single file shows, such as two clients that must classify the same answer identically. - **Decided-but-unbuilt intent:** outside doctrine, what the code cannot reveal because it does not yet do it, wrapped in `` … `` in plain words. A design decided *against* carries no marker. Unbuilt work has one home per kind. A doctrine document carries none of it, because it specifies every product and records no product's build state. Elsewhere, decided design the code does not do yet is an `UNBUILT` block where the design is stated; a shortfall in what is built (a promise the code does not keep, a case it mishandles) is one bullet under Gaps; the work that would close either is a backlog row, and the document never tracks that work's progress. The authority split (principle 4) is stated once, where agents enter the docs (the root instruction file or `docs/README.md`), so a reader who finds the code and the document disagreeing knows which way to resolve it. A doctrine document states its exception in its opening, as the specification sentence (`templates/doctrine.md`), where its readers would otherwise apply the default; a feature, package or system document never restates the split, because its opening is fixed to its goal. ### Diagrams and length by layer - **A diagram's layer:** at the model and parts layers a diagram names roles ("the browser", "the auth service"), never a URL, a header or a file. A diagram drawn from the code's names belongs to the code graph. - **Length as a signal:** a document whose reference tail is longer than its body is an inventory with an introduction. A doctrine document past about two hundred and fifty lines has usually let mechanism or restatement in; the per-genre expectations are each template's. ## Labels A heading, and the bold label that leads a bullet, is a noun phrase (principle 5). It names something. It never contains a finite verb, so it carries no tense, no person and no voice; the sentence that says what happens comes after the label, never inside it. A clause used as a label is the recurring defect. Once a label has a verb it has to pick a tense ("What *was* decided" is past tense in a present-tense document), a person ("*You* already belong…") and a voice ("was decided" is passive). A noun phrase has none of these, so it cannot be wrong in any of them. | ❌ Clause | Grammar | ✅ Noun phrase | | --- | --- | --- | | "How it works" | wh-clause, present tense | Flows | | "What was decided" | wh-clause, passive voice, past tense | Decisions | | "What it promises" | wh-clause | Promises | | "Why it exists" | wh-clause | Scope, or nothing: its content is a decision | | "Where a person lands" | wh-clause, third person | Landing | | "Asking who you are" | gerund clause, second person | Identity check | | "You already belong to an organization:" | declarative sentence, second person | Organization member: | | "Run `nustack login`." | imperative sentence | `nustack login`: | | "NuStack checks identity; it does not own it" | two declarative clauses | Identity: checked, not owned | - **Format:** `**Label:** sentence`. The bold label ends in a colon, then one or two plain sentences follow: "**Dead grant:** the stored item is deleted, and the person is prompted to sign in." - **The label's job:** it names the case, the thing or the decision; the sentence says what happens. "**Unclaimed domain:** user gets a private organization…", never "**Nobody claims your domain:** …". - **Reach:** the rule applies at every depth: `##`, `###` and `####` headings, table header cells, and the bold lead of every bullet or numbered item, in every document this guide governs. - **Exemptions:** the goal line and running prose are full sentences. A heading whose text is itself the checkable claim (a behavioural checklist's section, an acceptance criterion) is content, not a label, and keeps its sentence, because the assertion is what the reader came for. - **Lint:** `doc-lint` warns `clause-label` on a heading or bold label in an owning or doctrine document that opens with a wh-word or a personal pronoun, or that ends in a full stop. ## Voice The sentence after a label, and every sentence of running prose, describes the product to whoever reads it; it does not address the reader. - **Person and tense:** third person, present tense, active voice. The subject is the actor (user, machine, CLI, server, the organization): "**Organization user:** user lands in their existing organization", never "you land in the organization you already belong to". `doc-lint` warns `second-person` on "you" or "your" outside quoted copy, in an owning or doctrine document. - **Quoted interface copy:** keeps its own wording, including its "you", because the product does address its user. Quote it exactly, in quotation marks. - **Concision:** "Merges server data with local changes by version", never a sentence that restates its own subject twice. A function or a command is described by what it does ("Fetches data from the server", "Returns an array"), never by what it "is used to" do and never in the passive ("an array is returned"). - **Bold:** marks a bullet's label or a defined term's first appearance, never a noun mid-sentence. - **Em-dash:** a budget of one per paragraph, never a joint between clauses. - **Inline code:** every identifier, filename, command, flag, environment variable and config key a document names is in backticks. Where a document may name code at all is § Owning documents — the body and the footer and § Reference documents. - **Decoration:** ❌ / ✅ only inside banned/blessed lists and comparison tables, never as general decoration; no emoji in headings. ### Sentences The reader is an engineer deciding what to build or checking what was built, so a sentence earns its place by carrying a fact, a rule, a boundary or a reason (principle 9). The test for any sentence: deleted, does the reader lose one of those? If not, it is cut. - **One rule per sentence:** the rule is the sentence. Its reason, where it has one, is the next sentence, never joined to it by *so*, *so that*, *because* or *which means* (principle 10). - **Reasons where a rule needs one:** a rule takes a reason when any of four holds, because a rule with no reason reads as a preference and leaves a disagreement nothing to argue with: | Trigger | Example | | --- | --- | | The alternative is tempting: an engineer would reasonably do otherwise | retrying a failed signed token as a lookup; adopting an account by an unverified email | | The rule costs something: friction, or a feature someone will ask for | no password-only administrators; a step-up prompt; no forced rotation | | The value looks arbitrary: a number or a cutoff | a fifteen-minute window; a twenty-four-hour overlap | | The failure is invisible: an attack or a drift no user or test would notice | a timing leak; an account takeover; data crossing organizations | In doctrine the triggers propose and a cold reader decides: every reason, existing or proposed, goes through the reason check (`templates/doctrine.md` § Reason check), and an obvious one is cut. No reason is owed by a definition, by a rule a cited principle already justifies (the citation is the reason), or where the only reason restates the rule ("this keeps things secure"). - **The reason's size:** one sentence, after its rule, naming the concrete failure the rule prevents: "A cross-site page otherwise makes the browser send its cookie." Alternatives weighed and the argument behind a choice belong to an architecture decision (`decisions/`), which the document cites; the document carries the conclusion and its one line of why. - **Length:** about twenty-five words at most, one idea each. A sentence listing three or more items introduces them with a colon, in parallel form, and is the one exception. - **Statements, not modals:** a document states what happens ("the request is rejected"), never what must or should happen; its statements are requirements by being in it. "Never" marks a hard boundary, sparingly. - **Declaratives only:** no questions, rhetorical or otherwise, and no *imagine*, *consider* or *suppose*. - **Specific over general:** the concrete thing, never an abstract stand-in: role, credential, route, not power, proof, door. - **No rhetoric:** no scene-setting opener, no generic truth used as framing, no metaphor, aphorism, personification, or phrasing inverted or balanced for effect, and no hedging (*generally*, *typically*, *in most cases*). State the rule and list its exceptions. | ❌ Cut | Why | ✅ Keep | | --- | --- | --- | | "Every product on the enterprise plane must know exactly who is calling before it does anything else." | A truth no reader doubts, naming nothing, written to introduce the next sentence | "This document defines how a product identifies the caller of every request: one principal per request, step-up verification for sensitive actions, bounds on agent runs, and the credentials a product verifies itself." | | "A key that makes keys turns one leak into unlimited keys, so a person's API key cannot mint keys." | Reason and rule fused, the rule last | "A person's API key cannot list, mint or revoke API keys. A credential that can mint credentials turns one leak into an unbounded set." | | "the one caller whose next act nobody wrote down in advance" | Personification standing in for a definition | "An agent run is a job in which a model selects the next step." | | "Many proofs, one person" | A balanced slogan in place of the rule | "**One principal per person:** handlers see the same principal however the person authenticated." | ### Vocabulary A document uses the term engineers use. A plainer synonym reads as vague and an elegant one as literary, and either one reads as a second concept (principle 10). | Use | Not | | --- | --- | | verify, validate | prove, check, where verification is meant | | reject, deny; rejection | refuse; refusal | | resolve (a principal) | turn into, become | | mint, issue (a credential) | create, make | | route, endpoint | door, gate, page | | permission, role | power, authority | | origin, same-origin | the product's own site or pages | | timestamp, recency | how recently, when it was last | | constant-time comparison | a compare that leaks nothing | | step-up verification | a fresh sign-in, proving it again | | revoke | withdraw, kill (a credential, session or link) | - **One term, defined once:** a term is defined once (in a doctrine document's Terms table, at its first appearance elsewhere) and used unchanged after; it is never varied for style. - **"Doctrine" in prose:** the word is the genre's tooling name (`type: doctrine`, the template, the folder). A doctrine document calls itself "this document" or "this specification", and its neighbours "related documents". ### Reach and lint § Sentences and § Vocabulary bind doctrine and owning documents; records and queues take § Vocabulary and the person and tense rules. On a doctrine document `doc-lint` warns `modal-verb` (*must*, *should*, *shall* outside a quotation), `question` (a question mark in prose), `long-sentence` (past twenty-five words, a colon list exempt), `vague-term` (a word in the Not column above) and `doctrine-word` (the genre name in prose). A fused reason and rhetoric are judgment, and they are the cold read's (`document-sets.md` § Rubric). ## Owning documents — the body and the footer A feature, package or system document is scanned more than read (principle 6). It takes the shape (§ Shape — the model first, the detail after) and the labels (§ Labels) above, and these rules. ### Sections | Genre | Sections, in order | | --- | --- | | Feature | Goal line · Scope · Flows · Decisions · Promises · Gaps · For the agent | | System | Opening paragraph (the machine defined) · Scope · Flow · Decisions · Promises · Gaps · For the agent | | Package | Identity line · Goal line · Scope · Ownership · Usage · Decisions · Promises · Gaps · For the agent | Nothing else. A "Why it exists" section has no place; its content is Scope or Decisions. Mechanism sections (Architecture, Key Functions, State, Files, Schema, Routes, Wire, and their kin) are the graph's, and `doc-lint` blocks them as `mechanism-section`. The templates say when each section is required and how long each genre runs. ### The body - **The opening:** the goal is the first paragraph under the title, after the one identity line a package carries. No plan link and no routing line above it. - **Bullets:** each section is bullets under a noun-phrase heading; each bullet is a bold noun-phrase label, a colon, then one or two plain sentences saying what happens, what is decided or what is promised. - **Tables:** a table replaces the bullets wherever the cases are parallel states, such as each rejection and the exact message it shows. Its header cells are noun phrases. - **Paragraphs:** right for the goal, for a system's opening definition, and for the one- or two-sentence definition that opens a section. Everywhere else, a paragraph is bullets that have not been cut yet. - **Code in the body:** named only where a person types or sees it (a page, a command, a flag, an environment variable) or at a cross-cutting seam the graph would not lead a reader to from the feature's own files: a middleware, a gate, a hook, a scheduler tick, a shared store holding part of the feature's logic because that logic is global. Written once, by name, where the narrative leaves the feature. Everything else is a plain name: "the device registry", "the sign-off page", "the mirror". `doc-lint` warns `body-identifier` past three identifiers in a section. - **Flows:** describe behaviour, never mechanism. A flow bullet says that a forgotten machine comes back on its next call, never which function re-mints the row. Behaviour in plain words is intent made legible; columns, routes, guards and signatures are the graph's. - **Promises:** the deepest section of a feature document: every state, edge case and rejection, and the exact wording where the wording is promised, each checkable by a person or a test. A promise reads "a removed membership shows a panel, not a redirect", never which route answers it. - **Gaps:** a gap the code does not close is one bullet under Gaps, or a backlog row. It is never a ledger row inside another section, and never a temporal hedge. ### The footer "For the agent" is a set of pointers, never an inventory. It holds four things: 1. **Objects:** each with a one-line definition. 2. **Code roots:** directories where the graph should start. 3. **Seams:** the cross-cutting seams, by name. 4. **Checklist and neighbours:** the checklist, and the neighbouring documents with a purpose for each. A feature adds its pages, because an address is what a person points at; a package adds its commands, because those are its public contract. Tables, routes, symbol rosters and file lists belong in the footer no more than in the body; the footer obeys the stability test like every other line, and a footer that grows with every function is the inventory moved down the page. ## The Two Natures — tense and history Every document is a truth document, a record or a queue (principle 1); `SKILL.md` § The three natures gives the split and the genre registry (`templates/Readme.md`) gives each genre's nature. The tense rules follow directly. - **Truth documents:** every genre the registry marks `truth` states what the system *is* and how it works *today*, as if it had always been so. The journey (dates, migrations, progress) lives only in records. - **The one bridge:** an Architecture Decision's **Decision Changelog** tail carries that decision's dated revision history while its body stays current-truth-only; head is truth, tail is provenance. No other truth document carries a dated line, apart from the frontmatter's tooling keys and a dated path inside a link or code span, which cites a record rather than claiming a date. The `maintenance` agent's Health Log is a record of its own (`docs/history/health-log.md`), not a tail. - **Records:** never edited to match the present. A frozen plan stays wrong-in-hindsight; a changelog entry describes what shipped as it shipped. A scope change gets a new dated record that links back. - **Queues:** a row is appended when the work appears and deleted when it is done, drained or promoted, never marked done in place. A row may carry its date; nothing else in a queue is edited. | ❌ Historical narration (a record's) | ✅ Present-tense fact (the truth document's) | | --- | --- | | "Folded in from the `NuStack-X` repo (2026-06-12)." | "Vendor-connector catalogue; one subpath per vendor." | | "Built 2026-06-14; shipped + verified 2026-06-13." | "The session runs as an outer loop of turns over the agent loop." | | "The legacy worker was deleted in the 2026-06-14 fold." | "One worker interprets every workflow definition." | | "ex-`@nurix/mcp-runtime`, M9 Phase C; was X, now Y." | "The MCP client runtime, started by the agent trigger." | | "Build Sequence phases 0–4 are complete." | Nothing; progress lives in the plan or backlog record | | "There is no standalone `skills/components/` — treat any reference to it as stale." | Nothing; delete or repoint the stale references and state only the present design | | "Read first: `docs/history/plans/2026-…-fold.md`" (routing) | "Read first: `docs/architecture/.md`" | - **Dates and progress:** nothing about *when* something shipped, was verified, folded or was removed, and no completion markers: no "phases 0–4 are complete", no per-item `✅ shipped` / `⏳ pending`. Progress tracking is a record's job (the plan, the backlog). `doc-lint` blocks `date-in-truth-doc`, `history-narration` and `progress-marker`, and warns `status-glyph`. - **Stale-reference tripwires:** never "X is gone — treat references to X as stale"; that is a redirect document compressed into one sentence. Delete or repoint every stale reference instead (`stale-tripwire`, and `redirect-doc` for the file-sized version). - **Version and phase framing:** no bare `v1`/`v2` label, no "Phase 1/2", no "the old X", no "supersedes the earlier". There is one design; describe it without its predecessors (`predecessor-frame`). A version naming an external present-tense fact stays: a schema literal like `design-tokens/v2`, a dependency pin like `@0.14.0`. - **Temporal hedges:** "currently", "not yet", "still", "for now" smuggle a ⏳ into a truth document. State the fact without the hedge ("the hook is standalone; nothing in the mount path calls it") and let the backlog record carry the intention (`temporal-hedge`). - **A published artifact's version surface:** release notes and upgrade guides for a shipped package may use version framing (`v1 → v2`), because that is the artifact's public contract. They live beside the artifact or under `docs/operations/`, never in `docs/features/` or `docs/architecture/`. - **Record citations:** by what the record is, never by when it was. `Provenance: AD-002` points to the decision rationale; "decided in AD-002 and shipped 2026-06-13" states a date the reader must now carry. `the dev reset runbook` links to the file; "the 2026-09-13 reset" goes stale at the second reset. - **Routing and index documents:** point only to truth documents as a topic's authority. A "read first" row whose target is a plan or changelog entry is a redirect-for-history; repoint it or drop it. An index *of the records themselves* (a History section listing `plans/`, `changelog/`) is sanctioned. - **A changed system:** the change-story goes to `docs/history/` as a changelog entry, and the truth document simply becomes correct in present tense. The diff is never narrated in place. - **A moved decision:** an edit, never a new document. The AD's affected sections are rewritten to the new truth and the revision appended to its Decision Changelog; no parallel document, no old choice narrated in the body. Worked example of the strip-and-relocate move: [`examples.md`](examples.md) Example 6. ## Net-net — what earns a line A document fails its reader less often by being wrong than by burying its rules under what it repeats (principle 9). The failure arrives one reasonable sentence at a time: each restatement helps where it stands, and the set reads as noise. ### The line test - **A decision of its own:** the line states a rule, its reason, a boundary or a promise, and a reader without it would act differently. Otherwise it is cut. - **One home:** before a rule is stated, the document and its neighbours are searched for it, by a distinctive phrase. Found, it is cited ("(auth, principle 3)") with the one clause of context the sentence needs (principle 7), never restated in new words. - **Once inside the document:** a part's section carries the decisions its principles do not state; a principle repeated as a bullet below it is a duplicate wearing a label. - **One name per concept:** a concept keeps the one name the document set gave it (the term table in `document-sets.md`, or the `objects:` list for a single document); a synonym reads as a second concept. ### What fails it | ❌ | Why it fails | ✅ | | --- | --- | --- | | "The lock exists so that an unvetted organization can look around without creating anything." | Announces a purpose the next bullet states | "**Locked:** signs in and reads; creates and runs nothing." | | A parts table whose every row reads "see principle 4" | Places nothing | No table | | A Relations bullet restating principle 2 in other words | A second statement that will drift from the first | Cut, or cite principle 2 | | A doctrine document whose every rule had a home elsewhere: attribution, key custody, a budget rejection, outbound deadlines | Owns no decision of its own | Each rule moved to its home; the document deleted | | A rule stated in two sibling documents in different words | A reader cannot tell which binds, and the two drift | One home, one citation | | A table of states, then a bullet per state restating its row | Every rule is stated twice, a page apart | The table for what each state allows; bullets only for the reasons | | "Security matters at every layer." · "This section describes how…" | A truism and a ceremony: no decision | Cut; the heading already names the section | ### Port hygiene A document that changes scope (one product's design lifted into platform doctrine, or doctrine applied to one product) has every product name, setting value, code root, build state and product-specific example rewritten for the new scope or cut. Left in place, the residue reads as a rule binding every reader. ### Proof On a doctrine folder, `doc-lint` catches the mechanical half: a restated sentence (`sibling-duplicate`), a concept two documents govern (`objects-shared`), a citation to a principle or heading that does not exist (`citation-unresolved`), a purpose opener (`purpose-opener`). The rest is judgment, and it takes one cold read (`document-sets.md` § Review). ## Self-contained documents and the link surface Instruction files stay lean because an agent pays for them on every load (`instruction-style.md`); a document is read on demand, so it carries what its reader needs to understand the page (principle 7). - **Completeness:** the one or two sentences of context a borrowed concept needs are restated where it is used, because a reader forced mid-paragraph into a second document loses the thread of the first. - **Restatement and citation:** a changing detail (a version, a count, a path list) keeps one canonical home; the restatement carries what the page needs and points at the authority for the rest. Link-don't-copy governs where a fact is *owned*, not how readable the page that uses it must be. - **Inline links:** the minimum that action requires. A link mid-prose is right only where the reader must go there to act on this page, which includes the out-of-scope pointers in a Scope section or a doctrine document's opening. - **The closing link surface:** every other sister document belongs in the document's one closing section: "For the agent" (its neighbours line) in an owning document, "Related documents" in a doctrine document, "Related" elsewhere. Deep relative paths (`../../../../…`) are fragile, since a folder move breaks every one, so they are confined to that block; body mentions use the plain name ("the boundary skill", "`structure.md`"). ## Diagrams Structure at rest is ASCII; behaviour over time is mermaid. A file tree, an on-disk layout, a load-class split, a wireframe: box characters, because the diagram *is* the thing's shape. A sequence of turns, a state machine, a branching flow, a data flow: mermaid, because a renderer tracks the arrows better than a reader tracks them across box art, and the source stays diffable when a step is inserted. - **Documents only:** a diagram belongs in a document read on demand (a feature, system or doctrine document, a procedure). Instruction files never carry one; they load on every turn or invocation, and a sentence or a table carries the same information at a fraction of the tokens. - **Prose as the account:** a diagram restates structure for a reader who scans; a reader who greps must still find everything in the text. In an owning document the flow bullets are the account and the diagram sits beside them, never in their place. - **Role level:** at the model and parts layers a diagram names roles, never a URL, a header or a file (§ Shape — the model first, the detail after). ### ASCII ``` ┌─────────────────────────────────────────┐ │ TITLE │ ├─────────────────────────────────────────┤ │ │ │ ┌──────┐ ┌──────┐ ┌──────┐ │ │ │ A │────▶│ B │────▶│ C │ │ │ └──────┘ └──────┘ └──────┘ │ │ │ │ │ │ ▼ ▼ │ │ Detail Detail │ │ │ └─────────────────────────────────────────┘ ``` - **Characters:** boxes `┌─┐│└┘├┤┬┴┼`; arrows `───▶` `◀───` `│▼` `│▲`. - **Width:** about 70 characters at most. - **Wireframes:** a screen layout carries its page and tab above the frame (`**Page:** /path/:id`, `**Tab:** Tab Name`), `[text]` for a clickable button or badge, `[i]` for an icon followed by its label or count, `v` / `^` for an expand or collapse indicator, and one frame per UI state (collapsed, expanded). ### Mermaid | Diagram | Purpose | | --- | --- | | `sequenceDiagram` | Who calls whom in what order: a session turn, a hand-off between components | | `stateDiagram-v2` | Modes with transitions: a workflow, a record's lifecycle | | `flowchart` | A process with branches, gates or fan-out | | `timeline` | A dated lineage, in records only, never in a truth document | - **Size:** at most 7 participants and 15 interactions per diagram. Past that, split it; an unreadable diagram is worse than the bullets it restates. - **Labels:** under 8 words, no trailing punctuation. - **Direction:** declared on every flowchart (`flowchart TD` / `LR`) so the render is stable. - **Styling:** none. No `style`, no `classDef`, no theme overrides; rendering is the reader's, and the source stays portable across GitHub, Obsidian and a plain editor. ``` flowchart LR A[Plan approved] --> B{boundary} B -->|BLOCK| C[Re-plan] B -->|PASS| D[testing plan-gate] D --> E[Implement] ``` ## Headings and layout - **Hierarchy:** one H1, the document's title; `##` for major sections, `###` for subsections, `####` sparingly. - **Fixed section names:** an owning document's `##` headings are its template's, bare and identical across every document of the genre (`## Scope`, `## Promises`, `## For the agent`), because readers and tooling find them by name. - **Retrieval keys:** search and agents retrieve a section out of context, where a bare `### Failures` reads identically across every document. A generic `###` heading, and every heading in an untemplated document, is qualified by its topic (`### Sign-in failures`, `### Merge rules — data sync`) so it stands alone when retrieved. A short document whose H1 disambiguates can keep bare headings. - **Sentence case:** headings are sentence case; a product, a proper name or a named concept (`The Two Natures`) keeps its own casing. - **No hard-wrapped prose:** a paragraph is one line in the source (`.prettierrc.json` keeps `proseWrap: never`); the renderer wraps it. - **No empty stubs:** a section with nothing real to say is omitted; an explicit "None" is written only where the absence itself is information (`SKILL.md` § Truth documents). - **No file rosters:** a file list belongs in no document. The ownership index and the code graph answer "which file" for every genre, and a folder index describes directories, never files. - **The reference-document layout:** a document that is not an owning genre and whose content is the contract itself (an API reference, an environment registry, a procedure's appendix) opens on its goal, as a `**Goal:**` line or one sentence, and proceeds straight to its contract or procedure sections: ```markdown # [Title] **Goal:** One-line purpose ## [Contract or procedure sections] [Signatures, shapes, steps: the content the reader came for] ``` ## Reference documents A reference document is the deepest genre: signatures, shapes and variables are its content, so the stability test does not apply to it (§ The genres). These rules bind only there, and in a procedure's appendix; an owning document names a symbol only as a seam (§ Owning documents — the body and the footer). ### Function signatures ```markdown ### `functionName(param1, param2, options)` **Goal:** One-line purpose **Input:** - `param1` (type) - Description - `param2` (type, optional) - Description **Output:** `{ field1, field2 }` **Side effects:** State updates, API calls, etc. ``` - **Parameters:** name, type and one-line purpose; `(type, optional)` marks an optional parameter; an object's properties nest beneath it (`options.retry` (boolean), `options.timeout` (number)). - **Return values:** type (`Array