| name | write-well |
| description | Use when writing or editing prose for humans - blog posts, articles, essays, memos, announcements, release notes, post-mortems, narrative documentation. Use when output sounds like corporate-speak, contains hedging or filler adverbs, stacks abstract nouns, opens with throat-clearing, or feels generic and voiceless. |
Write Well
Overview
Clear thinking becomes clear writing. Most prose fails not from missing ideas but from clutter, hedging, and corporate gloss layered over them.
Core principle: No word earns its keep just by being there. If removing it doesn't change the meaning, cut it.
When to Use
Prose for humans: posts, essays, memos, announcements, release notes, post-mortems, narrative docs — and edits to the same. Skip for: code, API tables, syntax docs, verbatim quotes.
The Four Cuts
Apply in order. These catch most failures.
1. Cut filler adverbs and qualifiers
Most adverbs repeat the verb. Most qualifiers dilute it. Strike on sight: very, quite, rather, basically, essentially, actually, literally, slightly, simply, really, just, sort of, a bit, of course, surprisingly, carefully, thoughtfully (when not specifying how).
2. Break concept-noun stacks back into verbs
Two or more abstract nouns chained → rewrite with a working verb.
| Stacked nouns | Working verb |
|---|
| "the implementation of authentication" | "we built authentication" |
| "the operational complexity of maintaining X" | "X was hard to maintain" |
| "an inflection point in our trajectory" | "we changed direction" |
3. Delete throat-clearing
Cut sentences that announce instead of acting: "This is not a confession of failure...", "What follows is an honest account of...", "I want to share a decision directly...", "It is important to note that..."
Just say the thing.
4. Replace long words with short ones
utilize → use · implement → build · prioritize → rank · consolidate → combine · heterogeneity → variety · demonstrate → show · facilitate → help · in order to → to
Before / After
51 words, abstract:
The cognitive overhead of tracing a single request through six hops, the operational complexity of maintaining schema compatibility across teams, and the slow erosion of our ability to refactor across boundaries began to outweigh the autonomy we had gained.
30 words, concrete, rhythmic:
Tracing a request through six services took hours. Schemas drifted. Refactoring across team boundaries became impossible. The autonomy we'd won no longer paid for what it cost.
Verbs replace noun-stacks. One sentence becomes four.
Edit-Pass Checklist
Run in order after drafting:
- Read aloud. Stumbles → rewrite.
- Hunt clutter. Delete every word that, removed, doesn't change meaning.
- Test the lead. Does sentence one make you read sentence two?
- Test the close. Stop at the nearest exit. Don't summarize.
- Voice check. Does it sound like you, or a press release?
Red Flags — STOP and rewrite
- "It is important to note..." / "In order to..." / "There is/are..." starts
- Generic adjectives ("important," "significant") without specifics
- Sentences over 30 words that aren't deliberate
- "Unfortunately," "Surprisingly," "Of course" (telling the reader how to feel)
- Em-dash chains — like this — piling — too many — asides
- Passive voice when the actor is known
- Wall-of-text paragraphs · summary closers
Common Rationalizations
| Excuse | Reality |
|---|
| "It needs to sound professional" | Professional ≠ corporate. Cut anyway. |
| "The reader needs context first" | They need the lead first. Throat-clearing loses them. |
| "Cutting feels like losing nuance" | Nuance lives in the surviving words. |
| "I'll fix it on the next pass" | The next pass is now. Run the checklist. |
Going Deeper
For the full 100-principle canon — including form-specific guidance (interview, memoir, science, business, sports, criticism, humor, travel) — see principles.md.
