Prose rules for the kn-86 docs tree

Status: Accepted (the review is the acceptance) Date: 2026-07-29 Applies to: every document in this tree at every tier, plus ADRs, migration notes, commit messages, and PR bodies.

These rules bind prose written for this repo. They are the local override named in the agent-level rules at ~/.agents/writing-rules.md, and they carry the same content so an agent working without that file (a CI or cloud run) has the full set here. When the two disagree, ~/.agents/writing-rules.md is upstream and wins, and this file gets corrected.

Never rewritten to satisfy a rule: quoted text, preserved prose from an earlier author, and locked canon (published titles, canonical proper nouns, in-fiction CIPHER voice lines).

1. Only people and mechanisms act

The deck, the water, the map, the world, a budget, a design, or a spec does not want, wait, remember, hear, answer, celebrate, or decide. The operator acts. Hardware executes a stated rule. This is the correction that recurs most in this repo, so check it before every commit.

Instead of	Write
”the ocean is still ticking"	"guards step on the next turn"
"the water answers"	"the world step resolves"
"the water waits"	"nothing advances until the operator issues a command"
"the water heard that"	"the noise meter rose, and guards test against it"
"hazards announce themselves before they bite"	"a hazard changes the passive texture before it applies its cost"
"the map does the work"	"a rover that steps into a vent is destroyed"
"the deck remembers the operator’s history"	"`cartridge_history` records which modules have loaded"
"the design wants this consequence"	"the operator trades depth for information”

No false agency generally: a complaint does not become a fix, a decision does not emerge, data does not tell. Name the actor. Active voice by default; passive is fine when the actor is the system under description and already established (“the arena is reset at cart-load”).

2. Person

No first or second person in documents: no form of we, us, our, I, me, my, you, your. A document is read by people who do not share the author’s “we”, and “we need X” leaves who owes what ambiguous. Name the actor, or use the imperative: “Run tools/sync-kec-lisp.sh first.”

Sole exception: customer-facing marketing copy addresses the reader as “you” freely.

3. Punctuation

No em dash joining clauses, setting off a phrase, or tacking on an aside. Use a period, a colon, a comma, parentheses, or two sentences. The one exception is a structural separator already fixed by a house heading format (## Tier 2 — Operator spec). Straight quotes and apostrophes only.

4. Banned words and phrases

“worth X” in every variant (worth noting, worth checking, worth a look, worth flagging). If something merits doing, do it this turn and report it as done.
load-bearing, substrate, spine. Name the concrete thing: the C layer, the timer library, the through-line. Code identifiers keep their literal names in backticks.
Adverbs, softeners, intensifiers, hedges: really, just, literally, genuinely, simply, actually, deeply, truly, fundamentally, deliberately, exactly, merely.
Business jargon: navigate, unpack, lean into, landscape, game-changer, double down, deep dive, moving forward, circle back, on the same page.
Puffery: boasts a, vibrant, rich, profound, groundbreaking, renowned, nestled, diverse array.
Significance inflation: stands as, serves as, is a testament to, crucial, pivotal, vital, underscores, reflects broader, symbolizing, setting the stage.
AI-era vocabulary: additionally, delve, intricate, tapestry, align with, enhance, fostering, showcasing, emphasizing, highlighting, valuable insights, resonate.
Copula avoidance. Write “is” and “are” instead of serves as, marks, functions as, features.
Lazy extremes doing vague work: every, always, never, everyone, nobody. Name the case.
Emphasis crutches: Full stop. / Period. / Make no mistake / at its core / at the end of the day / it’s important to note.

Normative rule text (constraints, acceptance criteria, contracts, this file) may use never/always/every where the constraint requires it.

5. Banned frames

Negate-to-emphasize, every variant: “X, not Y”; “not X, it’s Y”; “not just X but Y”; and the same lift carried by “rather than” or “instead of”. State the claim and stop. A negation stays only when it corrects a real prior belief, such as a retired design.
Negative listing. “Not a X. Not a Y. A Z.” State Z.
Throat-clearing openers: any “here’s what / here’s why” construction; it turns out; the truth is; to be honest.
Vague declaratives. “The implications are significant.” Name the implication.
Pull-quotes. A sentence that reads like poster copy gets cut.
Dramatic fragments. “[Noun]. That’s it. That’s the X.”
Rhetorical setups: “What if X?”; “Think about it:”.
Meta-commentary: “The rest of this doc explains…”. The document moves; it does not announce its own structure.
Jargon splatter. Say what happens in plain English first, then give the feature name once in parentheses as a handle. One idea per sentence.
Forced synonym rotation. Reuse the correct term. In technical prose, one term consistently applied is the requirement.
Vague attribution: “Industry reports”, “Experts argue”. Name the source.

6. Rhythm and formatting

Vary sentence length; three consecutive matching sentences gets one broken.
The rule of three is a tell in running prose. Use two items, or one. Lists, tables, and specifications are exempt, since the count is set by the subject matter.
Vary paragraph endings; not every paragraph closes on a punchy one-liner.
No habitual Wh-word openers; lead with the subject or verb.
Sentence case in headings. No emoji as heading decoration or list markers. No skipped heading levels. No thematic break immediately before a heading.
No mechanical boldface on every instance of a chosen term.

7. Machine artifacts

Strip model artifacts before delivery: contentReference, oaicite, turn0search0, [cite:, grok_card, ppl-ai-file-upload, lenticular brackets, stray daggers. Verify external links resolve. Strip utm_source= and other tracking parameters from cited URLs.

8. Check before opening a doc PR

Run the checker against the files the PR authored and read the hits:

~/.agents/bin/prose-check.py FILE

It reports the rule each hit violates. Where the checker is unavailable, the same checks by hand:

grep -nE "—" FILE                                   # em dash
grep -niE "\bworth\b" FILE                          # banned frame
grep -niE "\b(we|us|our|I|my|you|your)\b" FILE      # person
grep -nE ", not [a-z]" FILE                         # negate-to-emphasize
grep -niE "substrate|load-bearing|\bspine\b" FILE   # banned words
grep -nE "oaicite|contentReference|turn0search|utm_source=" FILE

A hit inside preserved or quoted text stays; a hit in newly authored prose gets repaired. A single flagged word is a prompt to look, never by itself proof of a violation. A file whose subject is the rules themselves opts out with the marker prose-check: exempt in its first 500 bytes, as this file does.