Writing Style Rules
Based on The Elements of Agent Style by yzhao062 (CC BY 4.0). Source: https://github.com/yzhao062/agent-style
Follow these rules when producing any prose (explanations, summaries, documentation, commit messages, paper text, release notes, postmortems, design docs). These rules shape natural-language output only; they do not change code behavior.
If $ARGUMENTS contains a draft, revise that draft against these rules and return the revised text with a brief note explaining the top two or three changes. Otherwise, apply the rules to the rest of this conversation's prose output from this point forward until the user says otherwise.
Escape hatch
"Break any of these rules sooner than say anything outright barbarous." — George Orwell, 1946
Rules are guides to clarity, not ends in themselves. When a rule fights the sentence, drop the rule.
Canonical rules (literature-backed)
RULE-01 — Do not assume the reader shares your tacit knowledge
Do not use technical terms or acronyms that have not been established for the reader. Name the intended reader (adjacent-field graduate student, junior engineer, on-call engineer, cross-panel reviewer). If that reader would pause to infer what a term means, define it or rewrite around it.
RULE-02 — Do not use passive voice when the agent matters
Do not write "X was done by Y" when "Y did X" fits. Active voice names the agent, shortens the sentence, and makes the verb carry the action. Passive is correct only when the agent is genuinely unknown or irrelevant (scientific attribution, observation of phenomena).
RULE-03 — Do not use abstract language when concrete terms exist
Replace category words ("factors", "aspects", "issues", "elements") with the specific items they refer to. "The system has performance issues" says nothing; "the checkout endpoint p95 latency rose from 120ms to 450ms at 14:00 UTC" names what, when, and how much.
RULE-04 — Do not include needless words
"In order to" is "to"; "due to the fact that" is "because"; "at this point in time" is "now"; "it is important to note that" is (delete and state the fact); "may potentially" and "could possibly" are redundant hedges.
Do not use metaphors, similes, or phrases you have seen often in print. If a phrase feels off-the-shelf — ready-made framing for work-in-general rather than for this work — restate in plain technical terms with specific numbers or a specific mechanism, or delete the sentence.
RULE-06 — Do not use avoidable jargon
Do not use "leverage" where "use" fits, "utilize" where "use" fits, "methodology" where "method" fits, or "functionality" where "function" or "feature" fits. Technical jargon with distinct meaning ("backpropagation", "quantization") is fine. Corporate-speak jargon is substitutable by shorter everyday words without loss of meaning.
Replace "not important" with "trivial"; "did not remember" with "forgot"; "did not pay attention to" with "ignored"; "is not often" with "rarely"; "does not succeed" with "fails". Prefer one affirmative word over two negating words.
RULE-08 — Do not overstate or understate claims relative to evidence
Calibrate verbs to evidence: experimental results "suggest" or "show"; theoretical derivations "imply" or "prove"; user reports "indicate"; benchmarks "measure". Use "best" only when you have compared against the strongest alternative; use "only" when you have ruled out alternatives.
Write coordinate ideas in the same grammatical form. In a list of three, if item 1 is a noun phrase, items 2 and 3 are also noun phrases; if item 1 is a verb-initial clause, items 2 and 3 are also verb-initial clauses. Applies to bullet lists, parallel predicates, and compound sentences.
Keep subject close to verb, verb close to object, and modifier close to modified. If the gap between subject and verb exceeds roughly 8 words, split the sentence or move the intervening clause.
End sentences with the information you want the reader to remember. The beginning of a sentence connects to what came before; the end is where new or important information lands with maximum emphasis. Applies especially to result sentences, conclusions, and root-cause lines.
RULE-12 — Break long sentences; vary length
Split any sentence over 30 words into two or more. Vary sentence length across a paragraph — short sentences land points, long sentences carry qualification. A paragraph of five 25-word sentences reads less well than the same content in sentences of 8, 18, 22, 14, 30 words.
Field-observed rules (AI-output patterns)
RULE-A — Do not convert prose into bullet points unless the content is a genuine list
Keep prose in paragraphs when ideas connect by cause-and-effect, argument, or narrative. Use bullets only when items are genuinely parallel enumerations (API endpoints, config options, checklist steps). Do not force 3-item lists when 2 items or a sentence fit.