refine-prose

Files (5)

• SKILL.md
• SOURCES.md · references/
• examples.md · references/
• overcorrection.md · references/
• patterns.md · references/

SKILL.md (first lines)

# Refine prose

Work from the reader's side. Ask what this reader needs in order to
understand or decide, then remove everything that does not serve that.

Most weak prose fails above the word level. It says things the reader did not
need, in an order that hides the point, in phrasing chosen to sound like
writing rather than to say something. Fix those in that order. Word-level
tells come last and matter least.

One move covers most fixes: describe what is present, in literal words, with
the person who did it named.

## Before editing

Settle three things from the request or the text itself:

- **The reader and what they will do with the text.** A busy engineer
  deciding whether to merge reads differently from a friend receiving a
  reply.
- **Whose voice it is in.** Pete's own message or post: read
  `~/.claude/skills/write-as-pete/VOICE.md` and apply it after the passes
  below. Interface strings: read `~/.claude/skills/clean-copy/SKILL.md` for
  what survives on a screen and how to report a batch. Anything else: the
  default register under Voice.
- **The mode.** Rewrite returns revised text. Review reports findings and
  changes nothing. Draft writes new text, then applies the passes to it.

Ask only when the answer would change the edit materially. Otherwise choose
the reading a careful editor would choose and say so in one line.

## Pass 1: Cut what should not exist

Walk each section, paragraph, and sentence down these questions. Delete at
the first one that fires. Do not polish text that should be gone.

1. **Would the reader have wondered this?** Text that answers a question
   nobody had plants the question. A caption saying the preview is rendered
   at the exact profile size makes the reader wonder whether it might not be.
2. **Does something nearby already say it?** A caption under a clear label. A
   summary after a short argument. A recap paragraph. A topic sentence that
   restates the heading. A closing line that repeats the opening.
3. **Does it rule out a failure instead of describing a behavior?** "This may
   look slow but it is not." "Unlike the old cancel, this keeps your files."
   A list of what the change will not do. That is the writer's memory of a
   bug or a debate. The reader was not there and now has a worry they
   arrived without.
4. **Does it announce the text instead of being it?** "In this section we
   will", "Here's the thing", "Let me walk through", "The rest of this post",
   "It's worth noting that", "In short". Delete the announcement and let the
   content stand.
5. **Does it exist to sound like writing?** A quotable line. A punchline
   closing a paragraph. A question answered in the next sentence. A metaphor
   where a literal phrase was available. Replace it with the literal
   statement, or delete it if the statement is already there.

When a cut leaves a stub, remove the container too: the empty hint prop, the
one-line section, the transition into nothing.

Text stays when the reader cannot act without it: a consequence they need
before choosing, a scope or compatibility fact they cannot see, what a blank
state means and what to do next, a unit on a bare number, a condition on a
claim, the connective that shows why one sentence follows another.

A concrete example, a specific observation, and the writer's own judgment
also stay. They are what make prose read as a person's. Keep the judgment as
a claim about this case ("we chose Postgres because we already run it"), not
as a lesson or a moral ("boring wins"). When a draft has none of these, do
not invent one, and do not hand back the summary as if it were the piece.
Say the draft needs an example or a judgment from the writer and mark where
it belongs.

## Pass 2: Put it in the reader's order

- Lead with the conclusion, the decision, the verdict, or the thing that
  happened. Reasons follow. The reader can stop when they have enough.
- One move per paragraph. A paragraph that does two things gets split. A
  paragraph that does nothing the previous one did not gets merged or cut.
- Keep the connectives the reasoning needs: because, so, but, unless, which
  means. Cutting them to sound crisp leaves the reader to rebuild the
  argument.
- Structure follows the content. Lists for parallel items or steps. Headers
  only when a reader will jump between sections. Bold for the one thing a
  scanning reader must not miss. A table for a comparison. Prose for
  reasoning.
- Length follows the thought. Keep text short by leaving out what would not
  change what the reader does next, not by compressing what remains into
  fragments, abbreviations, or arrow chains. A reply can be one line. An
  argument needs its paragraphs. Do not pad a short answer to look
  considered.
- When summarizing a source, reword it in your own indirect speech and mark
  the few exact phrases you keep as quotations.

## Pass 3: Make each sentence state something

- **One idea per sentence.** About twenty words is a working ceiling for
  dense material. A reader holding a lot should not also hold a subordinate
  clause. Split at the clause instead of joining clauses with a semicolon or
  a colon.
- **A named subject doing a concrete verb.** Passive voice is fine when the
  actor is unknown or beside the point. It is a problem when it hides who
  decided. An abstraction doing a human thing hides the person the same way:
  the data does not tell, the decision does not emerge, the bottleneck does
  not move. Someone read, decided, or changed something. Name them, or use
  "you" or "we".
- **Literal over figurative.** Mannered prose substitutes metaphor and
  flourish for direct statement: "a dial worth turning" for "a parameter
  worth varying", "earns its keep" for "still matters", "load-bearing" for
  "necessary". The phrase displays the writer and costs the reader, and the
  metaphor drags in connotations nobody chose. When a literal phrase is
  available, use it. Keep a figure only when it explains something the
  literal phrase cannot, and use it once. A figure repeated through a
  section as its connective tissue has stopped explaining.
- **The domain's own names.** No hyphen-stacked compounds, no coined nouns,
  no label invented earlier in the text and reused as if the reader knew it.
  If a new term is needed, define it once.
- **Describe what is present.** "It's not X, it's Y", "not just X but Y",
  "less like X and more like Y", "rather than merely X", and a list of what
  something is not all assert by ruling out a claim the reader never made.

From petekp/claude-code-setup, MIT.

More from petekp/claude-code-setup