| 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.
