write-for-humans

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.