# Prose Restraint

> Writing discipline for substantive prose (docs, essays, READMEs): suppress over-explaining — state it once, show the implication, keep the omission. Use for 'prose-restraint', 'tighten this writing', 'stop over-explaining', 'trust the reader'.

- Skill: `dylanpulver/prose-restraint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add dylanpulver/prose-restraint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dylanpulver/prose-restraint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: dylanpulver (https://skillmd.com/u/dylanpulver)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/dylanpulver/prose-restraint

---


# prose-restraint — don't do the reader's work

The model's training pulls one way: be helpful — explain, resolve, clarify, complete. In *substantive prose*
that instinct is the enemy. The reader *wants* to draw the conclusion your setup makes inevitable, to feel a
tension before it resolves, to connect the two ideas you placed side by side. Do that work *for* them and the
writing goes flat and faintly patronizing. Restraint isn't fewer words for its own sake (that's mere terseness); it's
**leaving the reader the part they came to do.**

## The moves (apply to a draft, in order)

1. **State it once.** Said it clearly? Don't restate it two more ways "to be sure." The reader got it; the
   restatement tells them you didn't trust them to.
2. **Show the implication; don't spell it out.** Put the facts that make the conclusion obvious, then *stop*.
   The reader completing "…so X" themselves believes it more than being told X.
3. **Cut the throat-clearing and the recap.** The opening that announces what you're about to say, the closing
   paragraph that summarizes what you just said — both are the reader's least favorite parts. Start at the
   substance; end when it's done.
4. **Preserve productive omission / ambiguity.** Where a small gap makes the reader lean in, leave it. Not
   every tension needs resolving in the same sentence it appears.
5. **Stop over-hedging.** The caveat that protects you from an objection nobody was going to make just dilutes
   the claim. Qualify what's genuinely uncertain; assert what isn't.
6. **Kill the obvious "so what."** If the takeaway is plainly inferable from what you wrote, saying it out loud
   insults the inference the reader already made.

Before: "The cache is stale, which means reads return old data — in other words, users may see outdated values."
After: "The cache is stale; reads return old data."

## The two checks (the whole skill, if you only do this)

After a draft, read it once for each:
- **"What am I explaining that the reader could infer?"** → cut it.
- **"Where did I resolve a tension the reader would enjoy holding?"** → restore the gap.

## Boundaries (match restraint to genre — don't over-apply)

- **This is for prose a human reads for understanding or pleasure:** docs, concept notes, essays, READMEs,
  design write-ups, explanations, the corpus's teaching text.
- **NOT for code** — code wants YAGNI and the shortest diff, a different discipline.
- **NOT merely making chat terse** — dropping filler is a different discipline. You can be un-terse *and* restrained:
  restraint is about what you leave to the reader, not word count.
- **NOT for reference material that must be complete/unambiguous** — API docs, runbooks, legal, safety,
  spec. There, completeness and explicitness beat craft; suppressing detail is a bug. Restraint serves the
  reader's *engagement*; reference serves their *lookup*. Know which you're writing.

Overlaps: pair with a terseness pass for chat and YAGNI for code. When the genre is reference, defer to
completeness and switch this off.