Human prose
Codex adaptation (2026-09-16) of homeowmorphism/human-prose
by Hang Lu Su. Modified scope and editing guidance for Codex; original
evidence and attribution are retained.
Write for a reader who processes one clause at a time. Each rule below
targets a reading difficulty. Use these as editing defaults, preserving
the user's requested voice, necessary terminology, and the document's
conventions. The evidence base distinguishes
research findings from the original author's preferences. Load it when
discussing the rationale or citations; it is not needed for routine edits.
The rules
- One main idea per sentence. Split overloaded sentences while
keeping connections between ideas explicit (Flesch 1948). Avoid a
string of fragments that makes the argument harder to follow.
- Avoid mid-sentence interruptions. An em-dash aside or a nested
parenthetical suspends a clause the reader must hold open (Gibson
1998). Write a second sentence instead. A short parenthetical label
(like this one) is fine; a clause-length intrusion is not.
- Prefer active voice and concrete verbs. Name who does what when
the actor matters. Replace abstract noun phrases with verbs where
that makes the action clearer (Gough 1965; Coleman 1964).
- Given before new. Open each sentence from material the reader
already has, then add the new (Haviland & Clark 1974).
- No decorative emphasis. Emphasis works by selectivity (Schneider
et al. 2018). Flourishes are seductive details, and those measurably
hurt learning (Rey 2012). Choose emphasis deliberately and sparingly.
- Plain register. Explain unfamiliar terms in plain language before
relying on them. Keep precise technical terms when they help the
audience, and use them consistently. This adapts an upstream style
preference; it is not a restriction on how often a term may appear.
- Name the referent. An abstract noun standing for something else in
the document ("this cost", "that discipline", "the price") makes the
reader search for what it names, and they resolve it against the
nearest candidate rather than the intended one (Haviland & Clark
1974). Name the thing itself when the reference is ambiguous.
- Say it once, then stop. Length is a cost the reader pays whether
or not the words earn it. Cut restatements, preambles, hedges, and
sentences that announce what the next sentence will do. Delete a
sentence when it adds no meaning. Keep qualifications that carry real
uncertainty, evidence, or scope.
The pass
Apply the rules as a dedicated pass after the content is complete, not
while drafting. Rule 8 goes first: cut whole paragraphs before polishing
sentences, or the pass polishes text that should not exist. Keep verbatim
material untouched: quotes, compiler error text, signatures, citations.
Preserve facts, identifiers, links, and code behavior. A prose request
does not authorize unrelated code changes. In source files, respect the
project's comment and documentation conventions; check affected syntax
when a changed delimiter, docstring, or documentation test could matter.
Return the revised prose directly unless the user requested an explanation
of the edits.
1---2name: human-prose-23description: Write and revise clear prose in explanations, documents, comments, docstrings, commit messages, and PR descriptions. Use when drafting human-facing prose or when text feels dense, wordy, or machine-written. Preserve technical meaning and the user's requested voice and format.4metadata:5 source: https://skillmd.com/skills/homeowmorphism/human-prose-26---78# Human prose910Codex adaptation (2026-09-16) of [homeowmorphism/human-prose](https://github.com/homeowmorphism/human-prose)11by Hang Lu Su. Modified scope and editing guidance for Codex; original12evidence and attribution are retained.1314Write for a reader who processes one clause at a time. Each rule below15targets a reading difficulty. Use these as editing defaults, preserving16the user's requested voice, necessary terminology, and the document's17conventions. The [evidence base](references/evidence.md) distinguishes18research findings from the original author's preferences. Load it when19discussing the rationale or citations; it is not needed for routine edits.2021## The rules22231. **One main idea per sentence.** Split overloaded sentences while24 keeping connections between ideas explicit (Flesch 1948). Avoid a25 string of fragments that makes the argument harder to follow.262. **Avoid mid-sentence interruptions.** An em-dash aside or a nested27 parenthetical suspends a clause the reader must hold open (Gibson28 1998). Write a second sentence instead. A short parenthetical label29 (like this one) is fine; a clause-length intrusion is not.303. **Prefer active voice and concrete verbs.** Name who does what when31 the actor matters. Replace abstract noun phrases with verbs where32 that makes the action clearer (Gough 1965; Coleman 1964).334. **Given before new.** Open each sentence from material the reader34 already has, then add the new (Haviland & Clark 1974).355. **No decorative emphasis.** Emphasis works by selectivity (Schneider36 et al. 2018). Flourishes are seductive details, and those measurably37 hurt learning (Rey 2012). Choose emphasis deliberately and sparingly.386. **Plain register.** Explain unfamiliar terms in plain language before39 relying on them. Keep precise technical terms when they help the40 audience, and use them consistently. This adapts an upstream style41 preference; it is not a restriction on how often a term may appear.427. **Name the referent.** An abstract noun standing for something else in43 the document ("this cost", "that discipline", "the price") makes the44 reader search for what it names, and they resolve it against the45 nearest candidate rather than the intended one (Haviland & Clark46 1974). Name the thing itself when the reference is ambiguous.478. **Say it once, then stop.** Length is a cost the reader pays whether48 or not the words earn it. Cut restatements, preambles, hedges, and49 sentences that announce what the next sentence will do. Delete a50 sentence when it adds no meaning. Keep qualifications that carry real51 uncertainty, evidence, or scope.5253## The pass5455Apply the rules as a dedicated pass after the content is complete, not56while drafting. Rule 8 goes first: cut whole paragraphs before polishing57sentences, or the pass polishes text that should not exist. Keep verbatim58material untouched: quotes, compiler error text, signatures, citations.59Preserve facts, identifiers, links, and code behavior. A prose request60does not authorize unrelated code changes. In source files, respect the61project's comment and documentation conventions; check affected syntax62when a changed delimiter, docstring, or documentation test could matter.63Return the revised prose directly unless the user requested an explanation64of the edits.