---
name: writing
description: "Writing that sounds human: strip AI tells (em dashes, filler, hype, tacked-on tricolons), plain language, active voice, reader-first structure. Use when drafting or editing copy, docs, posts, or messages."
---

# Writing

The reader's time is the budget. Every sentence must change what the reader knows or does, or it goes.

## AI tells to strip (scan for each)

- The em dash used as punctuation where a comma, colon, or full stop belongs.
- Filler openers: "It's important to note", "When it comes to", "It's worth mentioning".
- Hype adjectives: powerful, cutting-edge, world-class, effortless. Replace with the fact: a number, a capability, a limit.
- The "not just X, but Y" construction; the tacked-on tricolon ("fast, simple, and reliable") added for rhythm, not meaning.
- Journey, landscape, realm, delve, leverage, seamless, robust vocabulary.
- Hedge stacks: "might potentially be somewhat".
- Question hooks: "Ever wondered how ...?"
- Summary paragraphs that restate the introduction in new words.
- Uniform sentence lengths; every paragraph opening with a transition.

## Rewrite patterns

| Disease | Fix |
|---|---|
| Passive with the actor dropped ("the decision was made") | Name the actor ("the team decided") |
| Nominalisation ("performed an analysis of") | Verb ("analysed") |
| Stacked clauses in one sentence | Split at the second clause |
| Generic claim ("improves performance") | A number or bounded statement ("cuts the page from 800ms to 90ms") |
| Opening with the topic's history | Open with the point |
| "not only X but also Y" | Say Y, or say X; pick one |
| Three items where two suffice | Two |

## Structure

- First sentence states the point. A reader who stops after it must still have the gist.
- Headings are claims, not labels: "Deploys fail on dirty worktrees" beats "Deployment".
- One idea per paragraph; examples over abstractions; active voice by default.

## Docs and posts

- Docs: what it is, why, then how. Commands and outputs verbatim; no placeholder prose the writer meant to replace.
- Posts: the title and hook must be true and specific; the piece delivers exactly what the hook promises. A platform cut keeps the argument only if the point sits in the first paragraph.

## The check

Read it aloud once. Any sentence you would not say to a colleague at a whiteboard gets rewritten; any word you would not use gets cut. Then measure: sentence lengths varied, no tell from the list above, the first sentence carries the point.