House Voice

Every document type has a register that works and several that fail. This says which, per type, by pointing at somebody who already writes it well.

Why this exists

The templates in Templates/ specify what sections a document has. Nothing specifies how it should read. So the structure is enforced and the prose is improvised, and improvised prose defaults to whatever register the writer last saw:

• A Decision note becomes meeting minutes — who attended, what was discussed, no statement of what was chosen or what it cost.
• A Handoff becomes a status report — the unmerged branch marked "in progress", which is an adjective standing where a fact should be.
• A Design System note becomes reverent adjectives about craft, with no rule anybody can apply.

Each of those documents passes its template check. Each is useless to the next person.

The selection criterion

A retrievable corpus of that exact document type. Not fame.

This is the whole trick, and it is why the reference files name some people you would not expect and refuse some you would.

An agent cannot imitate a sensibility it has never read. It can imitate a corpus. Ask for "write it like Jony Ive" and you get reverent adjectives about materials, because Ive spoke in product films and left almost nothing written — there is no corpus behind the name, so the model fills the gap with the idea of him. Ask for "write it like a GOV.UK Design System component page" and you get when to use this / when not to use this / how it works / research on this component, because ten thousand pages of exactly that exist and the model has read them.

Fame tells you whose taste was influential. It does not tell you whose prose is imitable. Those are different questions and only the second one helps here.

The failure mode to avoid

Costume. Copying a writer's mannerisms instead of their moves.

Mannerisms are the em-dashes, the short punchy fragment, the rhetorical question. They transfer instantly and buy nothing. Moves are structural: the problem section is longer than the solution section; the counterargument is stated at its strongest before it is rejected. They are what make the document work, and they survive being copied because they are about what the document contains, not how it sounds.

If a rewrite changed the rhythm and not the content, it failed. Check that first.

The second failure is genre collision — applying one type's register to another. A vision document that reads like a spec commits to numbers it cannot defend. A spec that reads like a vision document has a stirring opening and nothing falsifiable under it. The reference files are split by genre for this reason; picking the right file matters more than executing it well.

Procedure

1. Identify the document type

From the template being used, the target folder, or the ask. If it is genuinely ambiguous — someone wants "a doc about X" — read Reference/Writing/Choosing a Document.md in the vault, which is the escalation ladder: which document at which stage, and the cheapest one that still works.

Do not guess between two types. The register differs more between genres than within one, so a wrong pick costs more than a mediocre execution.

2. Check for a local override, then read the reference file

Reference/Writing/House Voice.md in the vault is the team's own map, and it wins. The files here are canon's defaults; a team that has named its own exemplars has done the more valuable thing and their choice governs.

Otherwise, open the matching file:

Optional template packs (canon-pack add <pack>) bring more document types. Their reference files ship here whether or not the pack is installed — a skill costs nothing until it loads, and a template arriving without its voice is the worse failure:

Each file is the same six parts: who to write like · why them · who not to write like and what goes wrong · the moves · what to go read · the pre-save check.

3. Apply the moves that hold everywhere

These are true for every document type in the vault. The reference file adds four to six more that are specific to its genre.

The problem is longer than the solution. If the reader is not convinced the problem is real and precisely shaped, the solution is unreadable — they spend it arguing with the premise. Most weak documents invert this ratio and fail for exactly that reason.

State the counterargument at its strongest. Then reject it for a specific reason. A strawman tells the reader you have not thought about it; a fair statement followed by a concrete rejection is the single largest credibility move available in a technical document.

Mark belief separately from knowledge. "We measured 1.9s at p95" and "I think this is latency-bound" are different claims and must look different on the page. Blurring them is how a guess becomes a requirement three documents downstream.

Follow every abstract claim with a concrete instance. Rule, then example, in that order, adjacent. A principle with no instance is unfalsifiable and gets ignored.

Numbers, not adjectives. "Slow" is a feeling. "1.9s p95 against a 900ms target" is a fact somebody can act on, disagree with, or measure again next month.

State absence in words. "Not measured", "not designed", "nobody owns this" — never a blank cell or a TODO. A blank is indistinguishable from an oversight; a stated absence is a finding somebody can pick up. This is the same rule the design canon applies to resolution rungs, for the same reason.

Cut the throat-clearing. Delete the first paragraph and check whether anything was lost. Usually it was context the reader already has, or an announcement of what the document is about, which the title did.

4. Run the pre-save check

Each reference file ends with five yes/no questions specific to its type. Answer them literally, on the draft, before saving. A "no" is a rewrite, not a caveat to mention in the summary.

When to override, and how

Canon's defaults are opinionated so a new vault is not blank. They are not a house style you inherited and cannot change.

A team should override when it has a better exemplar for its own domain — a regulator's published guidance, a predecessor's document everybody already imitates, a customer whose format you must match. Record it in Reference/Writing/House Voice.md, with the same three fields the shipped files use: who, why them, and what goes wrong without them. An override with no stated reason decays into a preference nobody can argue with.

Do not override to remove the anti-model. The anti-model is doing more work than the exemplar — it names the specific failure the writer is otherwise about to commit.

Notes

Cite, do not paste. The reference files link to the real documents rather than reproducing them. Go read the source when the summary is not enough; a paraphrase of a paraphrase is how a distinctive corpus becomes generic advice.

This does not make a document good. It makes it the right kind of document. A well-voiced spec with no evidence in it is still a bad spec — voice is the last layer, applied to something that already has content.

Do not announce it. A document that mentions which writer it is imitating has failed at imitating them. None of them did that.