---
name: write-for-humans
description: >-
  Make human-facing text clear, natural, and appropriate for its readers without losing
  technical depth or important meaning. Use automatically whenever Codex creates, rewrites,
  edits, or reviews documentation, READMEs, guides, tutorials, explanations, plans, reports,
  specifications, summaries, release notes, handoffs, UI copy, or other prose people must
  understand. Use alongside file-format or documentation skills. Do not use for code-only
  output, machine-readable data, verbatim quotations, or text whose exact wording must remain
  unchanged.
---

# Write for humans

Write for the reader, not for the model producing the text.

## Understand the reader

Before drafting, infer from the request and available context:

- what the reader wants to understand, decide, or do;
- what the reader probably already knows;
- which facts, terms, and constraints are new to them;
- how much detail they need now.

Do not mistake unfamiliar wording for lack of subject expertise. Clear language must not turn
expert content into beginner content. If a missing fact would materially change the text, ask
one short question. Otherwise, choose a reasonable reader model and proceed.

## Write clearly

- Put the answer, outcome, or required action first.
- Use common, concrete words and direct sentence structures.
- Keep necessary technical terms. Define an unfamiliar term on first use, then use it
  consistently.
- Expand an unfamiliar acronym on first use.
- Make relationships explicit: who does what, what causes what, and which condition controls
  an action.
- Use useful repetition when it prevents ambiguity.
- Avoid idioms, inflated business language, decorative metaphors, vague abstractions, and
  unnecessary synonyms.
- Prefer connected prose for an explanation. Use bullets for choices and numbered lists for
  steps; do not fragment every thought into a list.
- Use headings only when they help the reader find information.
- Keep the tone direct, calm, and respectful. Never call a task “easy” or “simple.”

## Explain in a useful order

For a concept, give the direct answer or mental model, then one concrete example, then explain
how it works. Put limits, trade-offs, edge cases, and formal detail after the core idea.

For instructions, state the goal and expected result, list prerequisites, then give numbered
steps in execution order. Show exact commands or values and place each warning beside the step
where it matters.

## Preserve meaning

Do not simplify by deleting needed conditions, exceptions, numbers, units, warnings,
uncertainty, scope, or causal links. Do not turn a rewrite into a summary unless asked. If
plain wording would make a precise claim vague, keep the precise wording and explain it
underneath.

When adapting source material, run a separate fidelity pass. Compare the result with the
source for numbers, scope, conditions, sequence, causal direction, exceptions, warnings, and
uncertainty.

For documentation, describe only the supported current workflow and intended state. Put
prerequisites before actions, use interface and code terms exactly, and place a warning next
to the step where it matters.

## Review from the reader's position

Before finishing, silently check:

- Can the intended reader understand the first paragraph without hidden context?
- Is the main point easy to find?
- Are unfamiliar terms, pronouns, conditions, and expected results clear?
- Is every detail useful for the reader's goal?
- Did the text preserve the source's scope and meaning?

Revise once if the check finds a problem. Do not print the checklist.

## Independent review gate

Use a fresh reader for any draft that is at least 800 words, is fidelity-sensitive source
adaptation, or informs a consequential legal, medical, financial, security, architecture, or
operational decision. Give `reader-fidelity-reviewer` only the intended reader and goal, draft,
requirements, and source material or stable source anchors. Do not give it the authoring
conversation or reasoning.

Resolve every blocking comprehension or fidelity finding before delivery. If the correction
materially changes the affected passage, rerun the reviewer on that passage. The review is
complete when it reports no blocking issue and the author has performed the self-check above.
If the runtime cannot start a fresh reviewer, say that independent review is unavailable; do
not present the author's self-check as independent evidence.