Write Clearly

---
name: write-clearly
description: Draft and revise prose for clarity, precision, concision, unambiguous execution, and honest emphasis using Orwell's rules, classic composition principles, modern plain-language guidance, and a specialized standard for agent instructions. Use for documentation, explanations, reports, emails, UI copy, agent instructions, plans, reviews, specifications, handoffs, or any request to simplify, tighten, clarify, humanize, remove jargon, make text sound less machine-generated, or reduce ambiguous wording while preserving meaning and voice.
metadata:
  website: "https://photostructure.com/coding/"
---

# Write Clearly

Make the intended meaning easy for the intended reader to grasp. Less is more:
precise, concise wording respects the reader's time and attention, and every
needless word spends both. Preserve facts, uncertainty, necessary detail, and
the author's recognizable voice.

## Workflow

1. Identify the reader, purpose, desired response, format, and tone. State only
   assumptions that could materially change the result.
2. Fix structure before sentences. Lead with the conclusion, request, or action.
   Keep one topic per paragraph. Use descriptive headings; use lists or tables
   only when they make real sequences or comparisons easier to scan.
3. Apply Orwell's tests:
   - Replace stale or mixed figures of speech with fresh wording or literal fact.
     Test each surviving figure by its literal image: if the picture cannot be
     drawn ("overarching pillars that undergird", "point a toolkit at a
     problem"), the words were paired by habit or co-occurrence, not meaning.
     Fluent phrasing over an incoherent image is the strongest marker of
     machine-generated prose.
   - Prefer the shortest familiar word that is equally exact.
   - Cut every word that adds no meaning, tone, or useful rhythm.
   - Prefer active voice when it makes the actor and responsibility clearer.
   - Replace needless jargon, scientific language, or untranslated foreign terms
     with an everyday equivalent.
   - Break any rule before producing prose that is false, ugly, or inhumane.
4. Apply complementary checks:
   - Prefer concrete nouns, specific examples, and strong verbs. Turn
     nominalizations into verbs when that exposes the action.
   - Keep necessary technical terms when they are more precise or familiar to
     the reader; define them on first use when needed.
   - Keep subjects near verbs, modifiers near referents, and parallel ideas in
     parallel form.
   - Give each sentence one main thought, but vary sentence and paragraph length
     enough to avoid a mechanical rhythm.
   - Ration signature rhetorical devices: "not X but Y" contrasts, groupings of
     three, staccato sentence fragments, self-validating asides ("and that
     matters"), and pet intensifiers such as honestly, actually, and delve.
     Each is legitimate rhetoric on its own; clustered, they read as
     machine-generated boilerplate.
   - Remove euphemism and abstraction that hide what happened or who is
     responsible.
   - Never gain brevity by changing scope, certainty, causality, intent, or
     voice.
5. Verify the result. Check that the takeaway appears early, actors and actions
   are unambiguous, and every word earns its place. Read it aloud. For
   high-stakes public content, ask representative readers to find and paraphrase
   the key points.

## Executable agent guidance

When revising instructions, plans, specifications, review findings, handoffs,
or other text that an agent must execute literally, read and apply
[the agent-instruction standard](references/agent-instructions.md) after step 4.
It prioritizes explicit scope, conditions, logic, actions, and evidence over
brevity or varied wording.

If missing facts prevent an executable rewrite, identify the blocker and ask
focused questions. Do not silently choose an interpretation or turn common best
practices into new requirements.

## Output

Lead with the finished prose. Explain edits only when asked or when a choice
materially affects meaning. Flag unresolved ambiguity instead of inventing an
interpretation.

Treat every rule as a default. Break it when accuracy, clarity, natural voice,
humanity, audience needs, quoted text, legal language, API names, or house style
requires a better choice.