| name | clear-writing |
| description | Use when writing or editing any prose humans will read — documentation, commit messages, error messages, UI text, reports, or explanations. Also use when user says "write clearly", "clear writing", or "improve writing". |
Writing Clearly and Concisely
Overview
Apply William Strunk Jr.'s The Elements of Style: write clearly, cut ruthlessly, say exactly what you mean.
Rules
Elementary Rules of Usage (Grammar/Punctuation)
- Form possessive singular by adding 's
- Use comma after each term in series except last
- Enclose parenthetic expressions between commas
- Comma before conjunction introducing co-ordinate clause
- Don't join independent clauses by comma
- Don't break sentences in two
- Participial phrase at beginning refers to grammatical subject
Elementary Principles of Composition
- One paragraph per topic
- Begin paragraph with topic sentence
- Use active voice
- Put statements in positive form
- Use definite, specific, concrete language
- Omit needless words
- Avoid succession of loose sentences
- Express co-ordinate ideas in similar form
- Keep related words together
- Keep to one tense in summaries
- Place emphatic words at end of sentence
Custom rules
- Preserve every idea and fact unless clarity demands a change
- Keep paragraphs short (no more than three brief sentences)
- Vary sentence length to avoid monotony
- Replace jargon and complex words with plain, direct language; use contractions
- Remove clichés, filler adverbs, and stock metaphors (e.g., "navigate," "journey," "roadmap")
- Avoid bullet points unless essential for scan-ability
- Never add a summary or recap at the end—finish on a crisp, final line
- Do not use em dashes; use commas, periods, or rewrite as needed
- Add dry humor or an idiom if it fits, but never sound like an infomercial
- After rewriting, review and fix any sentence that still feels machine-made
