ADR 0008: plain writing for the people who review it

Decision accepted (in progress) on 2026-10-10.

Each item below carries its own state: done is in the tree, in progress sits on a branch, planned is decided and queued, proposed is an idea not yet decided, and not built was weighed and declined.

Context

A pull request description is read by a reviewer now and by whoever follows a merge commit to it later. Neither was there when the work happened. Text carries far less tone than its writer hears in it: Kruger and Epley (2005), as their abstract and later summaries report it, found readers identified the tone of an email correctly 50 to 56 percent of the time, while senders predicted 78 percent. Byron (2008) found that work email reads as more negative than its sender meant. Terse, objective text is read as cold, and a reader fills the gap with intent the writer never had.

What the tree shows, measured over all 573 pull requests on 2026-10-10:

• 386 of 494 non-empty descriptions (78 percent) open with a defect. Among the 17 since #558 landed it is 88 percent. Five open with what the change makes possible.
• The judge's own instruction steers it: lead-context asks for "the goal behind the change and why this code stands in its way", and the guard's fixLine repeats it at every refusal. Agents see only the refusal text, so the wording of a denial is the style guide.
• The cold reading comes from structure, not insults. No description says "naive", "hack" or "bogus". What reads as a verdict: absolutes about the past ("has never fired", 149 hits of "never"), a pull request as the subject of a fault ("#341 added ... without regenerating"), a tool given intent ("magus guessed"), and almost no credit to the earlier design (one description in the 141 since #435).
• The 150-word cap of the earlier user-level hook deleted origin sentences to fit, and the attribution check refused product names that were the subject of the change ("the claude-code spell", the Claude Code mod), forcing vaguer rewrites.
• reply-voice refuses every heading, and the shape advice counts every paragraph past the lead as a wall, so a description cannot carry a "how we got here" section today.
• The guard and CI disagree: CI's pr-description runs only the judge, so an em dash, a selling word ("powerful") or an over-budget description passes CI and fails the guard. The selling-word list exists twice (Go writtenFillerWords, Buzz puffery), and so does the attribution pattern set.

What review between people adds, from the sources in the research and from patterns seen in reviews generally:

• A series of pull requests built bottom-up (baseline first, payoff later) reads as cost without payoff when the destination is not stated first.
• Evidence shown late, once a thread has stalled, reads as winning an argument rather than informing.
• "I do not understand this code" often means "I do not understand why this approach"; a description that names the alternatives answers it before it is asked.
• A long back-and-forth that one side experiences as debate reads to an onlooker as a stalemate. A call settles it faster than a fifth reply.
• Confidence reads from evidence and scope; arrogance reads from certainty words the evidence does not carry ("obviously", "as I said").

The same rules are meant for repositories other than this one, written with other people, so nothing in the judge may assume magus, git or GitHub.

Decision

Principles

• Static analysis for writing. These rules are to prose what a linter is to code: specific checks with measured precision, deterministic, and usable in any repository that adopts them. They hold work written with AI assistance to the standard a careful person holds their own work to, and they teach an agent to write that way. They do not hide how the work was made: a team that discloses AI assistance does so in its contributing guide or a label, which the judge never reads.

• Lead with the outcome. The first sentence says what a reader, a user or a maintainer can now do, or no longer has to do. The defect appears as the reason, never as the subject.

• Say how the work came up. A failing run, a measurement, a review, a follow-up to an earlier change, a tangent met on the way. This is history of the project, which is allowed; who or what produced the change is not.

• Describe the situation, never the person or the earlier code's character. "The cache kept the old key after a rename", not "the cache was broken". Where the earlier design's reason is known, say it: "a per-process cache suited one worker; it stops holding at eight".

• A claim covers exactly what was measured. Evidence gets a plain statement; a judgment call is labeled as one with its reason; what is not known is said.

• Deterministic checks belong to the Go judge, not to a skill. A check a regex or a parse can prove costs no tokens and cannot drift between two copies. A skill keeps only what needs meaning.

• One judge, no repository knowledge. The judge reads text and a kind and returns findings. Forges, version control and this repository's budget are inputs from the layer that calls it.

1. The shape of a description

Headings are allowed after the lead, in sentence case, phrased as the reader's question or the section's subject. The stock labels a reply generator emits (Summary, Test plan, Overview, Changes) and bold-label bullets stay refused, because they are the shape of an answer to a prompt the reader never saw.

The lead is exempt from the word budget. The budget, 60 + 50 * U, applies to everything after the lead, so a cut never removes the origin or the reason.

2. Decisions, the guard's vocabulary

The judge enforces nothing of its own. Each rule ships a default decision, deny or advise, the two words a guard rule's default takes, and a workspace sets any rule to off, advise or deny the way magus\guard.builtins overrides a built-in guard rule. A caller denies on deny and never sees off. Since 2026-10-20 advise means graded: each advise finding weighs its rule's measured lower bound on precision, and a text whose grade falls under its kind's minimum gets a grade deny finding (ADR 0006, amendment of 2026-10-20).

• What ships is portable. House style, the rules that encode one repository's conventions rather than plain writing (its glossary, plain-ASCII typography, no author in a description, the doc-comment budgets, the agent-instruction budgets), ships off. Run with no table, the judge holds text to tone, claims, shape and the generated-writing tells alone.
• A repository states its own. This repository turns its house style on in hack/policy/proofread.buzz, a decisions table beside hack/policy/builtins.buzz and kept the same way: a reason beside every entry. A path-scoped entry (blog/**: a post keeps its author's voice) is an exemption with its reason, reported when it no longer matches.
• No profiles. A named profile would be a second spelling of a decisions table. A voice file is not one: it describes one author's measured style and sets no rule's decision, except that it holds tense to advice on that author's change descriptions.
• Every rule is catalogued like a guard rule, as {name, code, decision, catches, why} (proofread rules), and the docs render a page per rule from it. Each rule also has a code in its own PRF prefix through libs/diagnostics, the shared framework magus uses for MGS codes and gopherbuzz for BZZ, so a finding links to its page.
• The findings are a contract. A finding is {source, kind, rule, code, decision, message, match, url, weight}, where weight is what an advise finding costs its text's grade and 0 on a deny finding. Any command that writes the same array, a team's own style checker or a reviewer it drives, feeds the same guard rule and lint, and the same decisions table applies to it. magus ships one judge; it does not have to be the only one.
• The guard rule names itself. pull-request-text answers as workspace:pull-request-text rather than as one anonymous workspace rule, so a repeat shortens, its verdict is stored and the trail can tell it apart. Every rule in hack/policy can do the same.

A small change in this repository, before and after (#570):

Before:
The server's warm caches lagged behind edits. A query after a graph-relevant change
rebuilt the graph inline. Symbol indexes that went stale while no server ran stayed
stale until their project was edited again. An edit during a reindex failed it with
MGS4007, and the indexer backed off for minutes.

After:
The first query after an edit answers from a graph and symbol indexes that are already
current. Until now the graph rebuilt inline on that query, an index left stale while no
server ran stayed stale until its project changed again, and an edit during a reindex
backed the indexer off for minutes.

- The warm graph builds when watching starts and rebuilds in the background 500ms after
  the last invalidation.
- ...

The same change written for a team adds sections only where they carry something. Angle brackets mark what #570 does not record and its author fills in:

Queries to a running magus server answer from a current graph, so the first question
after an edit no longer waits on a rebuild. This came up while <what surfaced it>:
<what was observed>.

## What changes
- ...

## Evidence
- A real root reindex takes 16s, plus up to 11s for the guard index (<command>, <run>).

## Not verified
- <what was not exercised, and why>

3. Claims and evidence

A sentence that states a measurement, a comparison or a completion is a claim, and a claim carries its evidence in the same bullet or sentence.

The hedge rule changes with it. A softener inside a claim stays refused ("may help", "should fix"), because it lets a claim stand with no evidence. A Not verified section, or a sentence that opens with "Not measured", "Not tested" or "Untested", states a limit and is allowed. A writer who is unsure scopes the claim instead of inflating or softening it.

In this repository the guard resolves every output ref a description cites (magus query output <ref>): a ref that does not exist, or names a failed run, is refused. Elsewhere the check is the presence of evidence, not its truth; the skill carries the rest (section 7). The examples are illustrative, not measurements of this tree:

Refused: Fixes the flaky cache test.
Allowed: `TestCacheEvict` passed 50 of 50 runs with `-count=50`; it failed 7 of 50 before.
Refused: Makes startup much faster.
Allowed: Cold `magus ls` drops from 410ms to 260ms (5 runs each, `hack/bench/startup.buzz`).
Allowed: Not measured on Linux; CI's runners report it.

4. Tone rules

Each rule names the posture it catches and how to say the same fact instead. Code spans, quotes, link text and fenced blocks are never judged.

The default follows measured precision. A list with no legitimate sense in this tree denies; a list whose words state invariants elsewhere ("never returns nil") advises, once per pull request, because the repository's own docs use "never" 788 times and every sampled use states a contract.

5. Review replies

A new kind, review-reply, covers a review comment, a review body and a reply in a thread. It takes every tone rule, plus:

The same judge runs on replies a person types (proofread review-reply reads a draft on stdin), and the guard runs it on replies an agent posts. Illustrative replies:

Reads as arrogant: Obviously this needs a lock. As I said, the map is shared.
Reads as unsure:   Sorry, I might be wrong, but maybe this could possibly need a lock?
Reads as expertise: This needs a lock: the map is written from two goroutines
                    (`go test -race` output below).
Judgment, labeled: I'd move the retry into the client: the upstream drops about 1% of
                    calls. Open to keeping it here if you see a cleaner seam.

6. The AI-writing checks move into the judge

The deterministic parts of the stop-slop and humanizer skills and of Wikipedia's "Signs of AI writing" move into libs/proofread. Of 96 pattern families, 52 are word or phrase lists, 20 are structural, 9 heuristic and 15 need meaning. The proposed rules catch 33 of the skills' own 41 "before" examples. Each was measured over 261 docs pages, 665 changelog fragments, 200 merged pull requests and the Go comments; every error-tier rule has zero hits in the docs pages, changelog fragments and pull requests except four wordy sites in the docs, which the change fixes.

Rejected on measurement, because this tree uses them correctly hundreds of times: Wh-sentence openers, passive voice, three-item lists, "-ly" adverbs, bold density and every/always/never as a general ban. Those stay in the skill's judgment list.

What remains a skill, about 150 words: run the judge first; then read for a claim with no specific behind it, false agency, a pull-quote sentence, synonym cycling and padding triads; keep the author's voice; one tell proves nothing. The phrase tables leave both skills once the judge carries them.

7. Where each piece lives

Adding a forge is one table row. Adding a VCS is one more method implementation in vcs/. Adding a check is one Go rule with tests, which the guard and CI pick up because both already run the same judge.

8. What changes together

U3 depends on U1b, U2 and U2b; U4 on U1b's catalog.

9. Settled on review

• The judge speaks the guard's decisions (off, advise, deny), not a severity of its own, and a repository states its preferences as a decisions table, not a profile.
• Rules are named like guard rules and also carry a PRF code, minted through libs/diagnostics in a prefix of their own; no MGS code is spent on a writing rule.
• verdict, absolute, intent and credit start at advise. Each moves to deny only after it has fired on real text and every firing was right.
• The guard judges every reply an agent posts: gh pr comment, gh pr review and review comments posted through gh api.
• idiomatic-hooks pr calls proofread and fails closed without it, so the hook and the judge cannot drift apart. It keeps no regexes of its own.
• long-thread reads its count from -thread-length N, and stays silent without it. The guard passes none: reading a thread is provider I/O a hook cannot afford. A person passes it, or a review flow that has already read the thread through a forge spell.

10. Measuring it

Alternatives

• Keep the problem-first lead and soften the words. Rejected: the coldness the research found comes from the order and the subject of the sentences, not from any word a list could remove.
• Leave tone to a skill. Rejected: a skill spends tokens on every description, drifts from the guard, and cannot run on a reply a person types. The judgment that remains is small enough to state in 150 words.
• Ban absolutes everywhere. Rejected on measurement: "never" states 788 contracts in the docs. The rule advises, and only about the past and about people.
• A separate judge per style. Rejected: two judges disagree within a month, as the Go and Buzz selling-word lists already do.
• Named profiles and a severity of the judge's own. Rejected on review: they spelled again what the guard's decisions and a workspace's override table already say, and a second vocabulary for one idea reads as bolted on.
• An MGS code per writing rule. Rejected: MGS codes name magus's own failures and each carries a hand-written resolution page; a writing rule is a convention, so it takes a guard-style name and a code in a prefix of its own.
• Vale. Rejected earlier (see the vale-port plan): a spell for prose rules put policy in a tool magus ships to users; the Go package is the seam.

Consequences

• Every rule this ADR adds is measured against this tree before it is turned on; an error-tier rule with a false positive here is not an error.
• Denials name the target shape and one example, so an agent that only reads the denial writes the new shape.
• Descriptions grow by a sentence or two in the lead; the budget past the lead is unchanged.
• docs/conventions.md stops claiming every rule is an error; it names the two tiers.
• The tone rules state posture, not warmth. A person still reads text written in their name before it is pushed; the judge does not certify it.