writing-style

name	writing-style
description	Use when producing substantial prose -- docs, READMEs, design notes, PR descriptions, commit messages, long explanations, or report writeups. The full Strunk & White economy rules, the cut-list of needless constructions, the AI-tell vocabulary blocklist, and cadence guidance. The two always-on guardrails (no em-dashes, avoid AI tells) live in AGENTS.md.

Writing style

These rules govern prose I read: explanations, summaries, comments, docs, commit messages, and PR text. They are about prose quality and are separate from the communication principles in AGENTS.md.

Punctuation and formatting

• No em-dashes. Use a spaced double hyphen ( -- ) or a spaced en-dash instead.
• Bold serves skimmability, not emphasis. Reading only the bolded text should form a coherent outline. Bold defined terms and lead-in labels, not random phrases for stress.

Prose economy (Strunk & White)

• Use active voice, definite assertions, and the positive form ("forgot", not "did not remember").
• Omit needless words. Cut "the fact that", "in the case of", "the question as to whether" (use "whether"), and "in a X manner" (use the adverb). Delete "very" and "certainly" when they carry no quantity.
• Replace "owing to the fact that" with "because" and "in spite of the fact that" with "though".
• Use parallel structure for coordinate ideas, keep subject and verb close, and put the emphatic word at the end of the sentence.

Avoid AI tells

• No antithetical reframes ("It's not just X -- it's Y"), no "From X to Y" sweeps, no importance puffery ("pivotal", "a testament to", "stands as").
• Vary cadence. Mix sentence lengths; avoid lists of exactly three and stacks of three adjectives.
• Avoid hedge clusters (may / might / could / potentially) and symmetric both-sidesing of asymmetric questions.
• Minimize: delve, tapestry, realm, landscape, navigate (as metaphor), underscore, showcase, leverage, robust, multifaceted, intricate, seamless, journey, ever-evolving.
• Topic-swap test: if a paragraph would survive swapping its subject for an unrelated one, it carries no content. Cut it or rewrite it with specifics.