damusix/atomic-claude/atomic-writing

<trigger>

• "draft the README", "write the docs", "improve this prose", "edit the guide"
• "write the spec", "write the design doc", "clean up this doc", "make this readable"
• "clean this up", "tighten this", "edit for tone" — on any file the repo ships
• /documentation editing any indexed surface
• Writing or editing any .md file that ships in the repo

</trigger>

Every file this repo ships has one voice: plain, specific, technical, and visual where the content has a shape. A spec, a README, a design doc, and a command artifact differ in length and structure. They do not differ in voice.

The reason is a contract that reads well to only one party is broken. A spec an agent can walk but a human cannot review is not a contract, and a guide a human enjoys but an agent cannot follow is not documentation. Write for the human. A model reads what a human reads.

<voice_rules>

The one boundary

Nothing else splits. There is no separate "terse technical" voice for specs, designs, CLAUDE.md, or agent prompts.

Same voice, different length

Length is set by the job the surface does, not by a compression quota and not by a house maximum.

Tight is not cryptic. Cutting filler is always right. Cutting the contract to save a line is never right.

Structure before sentences

Clean sentences in the wrong order still produce a document nobody can read. Decide the order first.

A document answers the reader's questions in the order the reader asks them:

1. What is this, and why do I care? Purpose in the reader's terms: what they gain, or what breaks without it. Not mechanism.
2. How does it work? The shape. One diagram or one worked flow, plus the reasoning that connects it.
3. Where is it? Paths, symbols, and entry points, in one table rather than several lists.
4. What will bite me? The constraints where being wrong is expensive.
5. What else does this touch? Pointers to adjacent surfaces.

Not every document needs all five, and a surface with its own defined structure (a spec's checkpoint table, a reference page's lookup tables) keeps that structure. The order does not invert. A page that opens on a path inventory and reaches its purpose in the last paragraph is backwards, however well each paragraph is written.

The opening contract. Before the second ## heading, the reader has seen three things: what the thing is, when to reach for it, and the thing itself — a worked transcript, a real invocation, or the one diagram that carries the model. For a tool the reader will drive, the strongest opener is a transcript; for a config surface or subsystem, the mental model plus its diagram. A page that defers all three past the first screen reads as an inventory, whatever its prose quality. references/exemplar-reference-page.md and references/exemplar-tool-page.md carry finished shapes to imitate.

Name the thing plainly, up front. When a subject's name does not match its paths, its command, or its output, say so in section 1. A reader who cannot map the name to what they see on disk builds no model at all, and every later section pays for it.

Core rules

1. Show the shape. When the content has a shape, draw it. A reader follows a flow faster in a diagram than in a paragraph, and so does a model. Draw it when a picture explains better, write prose when prose explains better, and never add a diagram that only restates the sentence above it — except at the three floors below, where the drawn form is required.

Floors trigger on the draft, not the plan: check what you wrote, not what you intended to write. These are the shapes a writer most reliably leaves trapped in prose.

Prompt artifacts may use Mermaid when the flow carries the instruction and prose would take more lines; otherwise use the ASCII form, which costs fewer tokens at equal clarity. For the full route vocabulary and the discipline caps, see output-styles/atomic.md.

Every diagram makes one claim, and the caption above it states that claim. "The signals pipeline" is a title. "The scan runs before the infer step, so a domain writer never reads a stale substrate" is a claim. If the only caption available is "here is the system", the content is an inventory: write the table instead. The prose must stand without the picture, because a reader on a renderer that does not support Mermaid gets the raw fenced block. The diagram compresses; it does not carry.

Draw as many diagrams as the subject has shapes. A pipeline, a lifecycle, and a request path are three claims, so they are three diagrams, and collapsing them into one canvas or into prose loses all three. There is no cap on how many a page carries; the cap is per diagram, on how much any one of them tries to say.

What a second diagram owes is a second claim and its own heading, not restraint. Two diagrams separated by a single line of text is the thing to fix: either the second says something the first does not, in which case give it a section, or it restates the first, in which case cut it.

Budgets, per diagram: 9 nodes for a flowchart, 6 participants for a sequence, 8 entities for an ER or class diagram. Over budget means the claim is too big, not that the labels should shrink. Split by abstraction level instead.

Layout follows the same discipline: references/mermaid.md's layout table sets the default direction (TD), the side-by-side and label-width limits, and the color ban.

Two things that look like diagrams and are not. Linear steps with no branch and no boundary crossing are a numbered list, and five boxes in a chain are worse than five lines: bigger, harder to diff, harder to search. And reaching for a flowchart is usually a sign the claim has not been decided. If the logic is ordered interaction across a boundary, sequenceDiagram carries time for free. If it is which transitions are legal, stateDiagram-v2 shows illegality by absence and a flowchart cannot.

Label nodes with the real identifier (pruneDeleted, AuthGuard.verify()), not a generic noun ("cleanup", "check auth"). A renamed symbol then turns up in grep; a vague label goes stale in silence. Encode distinctions in shape or line style, not color: {diamond} for a decision, [(cylinder)] for a store, -.-> for async. Color encodes nothing, breaks on dark backgrounds, and fails colorblind readers.

Before writing a Mermaid block into a docs/ file, read references/mermaid.md: it picks the type from the reader's question and lists what breaks rendering. Identifier labels are the reason it matters here, since a bare verify(token) is a parse error and verify("token") is not.

Diagrams belong to explanation and reference. A concepts page or a design doc is where a claim about how something works earns a picture, and a reference page earns one for a data model or a type hierarchy. A how-to is ordered steps the reader is executing, not modeling, so it rarely wants one. A tutorial almost never does: a learner on rails does not need a map of the territory, and a diagram invites exactly the decision-making a tutorial exists to remove.

Place it where it will be maintained. A system map belongs in the README, exactly one; subsystem logic belongs in the page next to the code; why-it-is-built-this-way belongs in the design doc; what-changed belongs in the PR body. Commit the diagram with the code it describes. A diagram that lives somewhere the code change never touches drifts, because nothing forces it to move.

Check that it parses before committing. A Mermaid block with a syntax error renders as a raw fence or an error box, and neither is visible from the source. npx -y @mermaid-js/mermaid-cli -i docs/page.md -o /tmp/out.md extracts every block and reports each pass or fail. It pulls Chromium, so it is slow the first time; in a container running as root it needs -p with a puppeteer config setting --no-sandbox. It also writes sibling .svg files next to the output — delete them if you only wanted the check. Where mmdc is unavailable, re-read the gotcha list in references/mermaid.md against what you wrote, which is where most breakage comes from.

1. Active voice, named actor. Every sentence has a subject doing something. Replace "the decision was made" with "the team decided" or, in docs, "we picked" or "use X". Never let inanimate things perform human verbs ("the complaint becomes a fix", "the architecture emerges").