madarauchiha-314/the-loop/writing

Writing for a human reader

A reviewer's job is to say yes or no. Every word between them and that decision is a cost you are charging them. Write to be approved, not to be admired.

The rule: say it once, to a named reader, in the fewest words that survive review.

Who is reading

Name the reader before the first sentence. A reviewer of design.md knows the codebase and wants the shape of the change. A capability.md reader wants current behaviour and does not care how it arrived. A ticket comment is read on a phone. The same fact is a paragraph for one and a table row for another.

The spine

Every explanatory document answers four questions, in this order:

1. What was broken — the situation, and why it mattered enough to open a ticket.
2. What we did about it — the resolution, stated as a decision, not a tour.
3. What it costs — the trade-off taken, the thing given up, the risk carried.
4. What to check — where the reader should look first, and what would falsify it.

Front-load each one. A section's first sentence carries its conclusion; the rest is support the reader may skip. Read only the first sentence of every section — if that alone tells the story, the document is shaped right.

Length follows the change

There is no word limit, and there should not be. A two-line bug fix and a new subsystem are both design.md, and a number that fits one is wrong for the other. A cap would only teach you to move prose into an appendix.

The test is not length, it is density: can any sentence come out without losing information? While the answer is yes, the document is too long — at 200 words or 2000. Three cuts nearly always find the slack: the sentence restating the heading, the sentence restating the sentence before it, and the adjective a number would replace.

Concision is about words, not coverage. A gated section stays even when it is empty; say so in one sentence, and why. Deleting ## Security considerations to shorten a document is fraud, not editing.

Prefer a diagram

Describing a structure, a sequence or a state change with three or more named parts? Draw it. Mermaid, always. Then let the prose say only what the diagram cannot — why the arrow points that way, what happens when it fails. design.md carries at least one.

Keep the formal register where it is a contract

These are testable artifacts, not prose, and this skill does not touch them:

• EARS acceptance criteria and abuse cases (WHEN … THEN the system SHALL …)
• RFC-2119 keywords in a specification
• OpenAPI / GraphQL contracts and JSON-Schema description values
• Quoted material, third-party text, committed evidence and code

These are the formal registers of the writing contract (fixed since issue-352). Explanation around them is ordinary prose and follows this skill.

The revise pass

Draft first, cut second — never both at once.

1. Delete every opener that clears the throat before the point.
2. Delete every sentence the reader could reconstruct from the one before it.
3. Replace each evaluative adjective with the number or example behind it.
4. Convert any run of prose that is really a list, a table or a diagram.
5. Read the first sentence of each section in order. If that alone tells the story, stop.

If it does not, the problem is the structure, not the wording.

For the catalogue of writing tells and what to do about each, read `reference/tells.md`.

Related

The token-economy verbosity rule (the-loop skill, reference/token-economy.md) compresses chat narration and preserves specs; this skill governs the artifacts. Third-party skills covering neighbouring ground are implemented natively, not vendored (decision-005, decision-062).