write-clearly ยท diff
git:20260728.f95e109 to git:20260809.a0c27fa
11 added, 1 removed. Audit A to A.
---
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, or reduce ambiguous wording while preserving meaning and voice.
+ 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.
---
# Write Clearly
Make the intended meaning easy for the intended reader to grasp. 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.