writing

name	writing
description	Use whenever writing, editing, or reviewing prose — user-facing (docs pages, landing copy, UI microcopy, error messages, release notes) and developer-facing (PR descriptions, issue bodies, commit messages, code comments, and replies in chat, including an answer to the user). Apply the rules while drafting, and run the pre-ship check before presenting the copy.
version	0.1.0

Ship copy without slop

Plain words, definite claims, proof over adjectives, the point first, every word earns its place.

When rules conflict: clarity > concision > character. Personality is fine only when it costs nothing from the first two.

The rules

1. Cut every word that doesn't add meaning

"Omit needless words" is the oldest rule and the one AI prose breaks most. If a sentence survives with a word removed, remove it.

• In order to configure a provider → To configure a provider
• If you're ready to start using the proxy in your project, see our setup guide. → Ready to start? See the setup guide.

2. Use plain words

All readers prefer plain English — the preference grows with reader expertise, so "our audience is technical" is not an exemption. Swap inflated words for the short common one:

Don't	Do
purchase	buy
assist	help
approximately	about
utilize / leverage	use
in order to	to
prior to	before
conduct an analysis	analyze

Watch for hidden verbs: words ending in -ion / -ment / -ance usually bury the verb (make a decision → decide).

3. Make definite assertions

Delete hedges and weak openers. Don't write "It's important to note that avif can sometimes be smaller" — write "avif at quality 50 is 30% smaller here" (or don't claim it).

• Kill: "it's worth noting", "generally speaking", "to some extent", "there is/are", unnecessary "you can".
• Put statements in positive form: He was not very often on time → He usually came late.

4. Active voice, real verbs

Passive voice hides who does what. Test: a form of "to be" + past participle. The srcset is generated by the component on render → The component generates the srcset on render. Passive is fine when the actor doesn't matter.

5. Specifics and proof over adjectives

Adjectives read as spin. A number, an example, or a mechanism beats "powerful", "blazingly fast", "seamless" every time.

• <Image> picks the variant that fits its container, with no JS in the critical path beats A powerful, seamless image optimization experience.
• No grandiose claims. Focus on what the thing actually does; don't market at people.

6. The point first

Lead with the most important thing; no throat-clearing intros ("In today's fast-paced world of web performance…"). In UI and docs, front-load keywords so the copy scans, and make the next step obvious.

7. Length limits

Treat as warnings, not laws: sentences over 25 words get split, paragraphs stay under 5 sentences, microcopy stays under 3 sentences.

Slop patterns to kill on sight

Vocabulary that flags text as generated — replace with plain alternatives: delve, tapestry, testament ("stands as a testament"), pivotal, crucial, robust, showcase, underscore, meticulous, vibrant, intricate, landscape, foster, boasts, realm, harness, illuminate, resonate, navigate (metaphorical), commendable, swift, seamless, leverage, elevate, supercharge, unlock, empower, game-changer.

Structural tells:

• "Not just X, it's Y" and its cousins ("more than a library — a philosophy").
• Rule-of-three everything — triplets of adjectives, three perfectly parallel bullets, symmetrical listicles. Vary the rhythm; asymmetry reads as human.
• Em-dash chains — more than one or two per paragraph is a tell.
• Empty intensifiers — very, truly, incredibly, deeply.
• Hedging filler — see rule 3.
• Self-narrating prose — don't narrate the reader's confusion or the doc's own reasoning ("this is where it looks broken", "the two halves"). State what's true and what to do.
• Coined nouns — don't invent a capitalized concept ("Capture", "the Provenance layer") and lean on it; use words the reader already has. ImageMeta is a real type in this repo, not a coinage; check CONTEXT.md § Glossary before inventing a term.

Per surface

Docs pages (apps/docs)

All the rules apply, plus: copy must be understood on first read — if a sentence needs a second pass, rewrite it. Mirror the register of an existing plain-voiced page. Headings state the finding, not the topic ("The browser picks the variant, not JS", not "Variant selection considerations").

Landing and marketing pages

Rule 5 is the whole game: real strengths, concretely stated, zero grandiose claims. Voice can be warm; it cannot be hype. The three claims that carry this project — container-width selection, self-hosted proxy, framework-agnostic — are specific enough to state plainly. Don't inflate them.

UI microcopy

Under 3 sentences, every word load-bearing. Write like you speak — read it aloud; if it sounds stiff, it is. No jargon the user doesn't already have. Buttons and links are a promise about what happens next: specific, sincere, substantial, succinct. Never bare Learn More or Get Started — say what they get (Copy the proxy URL, See the generated srcset).

Error messages

• State the exact problem — An error occurred is banned. Say what failed and, when known, why.
• No blame words: avoid invalid, illegal, incorrect, forbidden aimed at the user's input framing.
• Show the fix, ideally with an example: Invalid width → Set width to a positive integer, like 640.
• No raw codes or system-speak in user-facing text.

GitHub bodies and comments (PRs, issues, reviews)

Put each paragraph on one line and separate paragraphs with a blank line. Never hard-wrap at 72 or 80 columns. GitHub renders every newline in a PR body, issue body, or comment as a line break, so wrapped prose arrives ragged; the same text in a .md file folds into a paragraph, which is why the habit is invisible until it ships. Wrapping stays correct in commit messages, which git tooling displays in a fixed-width terminal. The block-hard-wrapped-body.sh hook enforces this on gh pr|issue create|edit|comment, including bodies passed as --body-file.

The section order for a PR body is fixed by .claude/rules/git-workflow.md § PR Convention: Goal, What, How, Tests.

Pre-ship check

Before presenting copy, verify:

1. Would the first sentence survive as the only sentence? (Point first.)
2. Any word from the blocklist, or a table-2 swap missed?
3. Any hedge, empty intensifier, or "not just X, it's Y"?
4. Every claim backed by a specific — number, example, mechanism?
5. Sentences under ~25 words, microcopy under 3 sentences?
6. Read it aloud — does it sound like a person?
7. Going to GitHub? One line per paragraph, no hard wrapping.

Sources

• GOV.UK clear-language standard — plain English mandatory, 25-word sentences, word substitutions: https://guidance.publishing.service.gov.uk/writing-to-gov-uk-standards/writing-guidelines/clear-language/
• Microsoft Writing Style Guide, top 10 tips — brevity, verb-first, front-loading: https://learn.microsoft.com/en-us/style-guide/top-10-tips-style-voice
• Mailchimp writing principles — no grandiose claims, communicate don't market: https://styleguide.mailchimp.com/writing-principles/
• US federal plain language — active voice, hidden verbs: https://digital.gov/guides/plain-language/writing
• Strunk & White — omit needless words, definite assertions
• Nielsen Norman Group — 3 Cs of microcopy, error-message guidelines, Learn More/Get Started research: https://www.nngroup.com/articles/
• Wikipedia, "Signs of AI writing" — the slop taxonomy: https://en.wikipedia.org/wiki/Wikipedia:Signs_of_AI_writing