Prose Passes

Prose passes

An editing procedure for text that already exists and was written by someone who knows the subject too well. It does not invent content. Each pass asks one question, and the three questions are separate reads.

Run all three even when the request names only one of the problems. The passes feed each other: cutting jargon creates new referents for pass 2 to resolve, and resolving them changes which sentence carries the point in pass 3. A single pass run alone leaves the text in a state the other two were meant to clean up.

This skill is the procedure. The rules it applies live next to it, and it loads them at the points where they are needed:

• human-writing, a sibling skill: AI tells, formatting, and the full versions of the vocabulary and ambiguity rules (sections "Audience and Vocabulary", "The Ambiguity Pass", plus CHECKLIST.md).
• references/academic.md: the same ground recalibrated for papers, theses and funding proposals, where terminology is load-bearing and the panel is mixed. Load it for academic text only.

Step 0: name the audience, before touching a word

Every later judgement is calibrated to this answer, so an unstated audience means you are editing for yourself, and you are never the audience.

Ask who the reader is. If you cannot ask, write the assumption down at the top of your report where the reviewer will see it, and proceed. "Lecturers and students who do not build websites" leads to different edits than "developers evaluating the library".

The rule is not "use simpler words". It is "use words this reader already has". A term can be precise, standard and correct and still stop the reader dead.

The order of the passes is itself a rule

1. Jargon first, because it rewrites sentences.
2. Ambiguity second, because it must run on the rewritten sentences. New words bring new referents.
3. Inverted pyramid last, because it only moves material, and moving material that is still going to change means doing the work twice.

Two more are searches rather than reads and run last, because the three passes above tend to introduce both. Self-congratulation: tightening a sentence is exactly when a writer reaches for a clause saying why the thing was a good idea. Universal quantifiers: moving the claim to the front of a sentence is exactly when a writer reaches for an every to make it land.

Run them as three separate reads, not one merged edit. Reading for rhythm and reading for reference are different attentions, and merged, the first one wins: the ambiguities get skimmed past because you were listening to the sentence.

Before finalising any prose in any pass, load human-writing and apply it.

Pass 1: jargon, calibrated to the audience

Load human-writing, section "Audience and Vocabulary". For academic prose or a proposal, also load references/academic.md, whose triage is the same but whose defaults protect field-standard terminology.

Triage every term of art three ways:

1. The term is the subject. Keep it. It is what the reader came for.
2. Load-bearing but unfamiliar. Keep it and introduce it on first use, in the same sentence, in ordinary words. Later uses stand bare.
3. Incidental. Replace it or cut the clause. It spends attention and buys nothing.

Most unreadable expert prose is category 3 mistaken for category 1.

Entry points carry no unglossed jargon: the title, the lede, every standfirst under a heading, and the first instruction of any instruction set. The reader decides there whether to continue, and decides before any later explanation can reach them.

The private-sense trap is the one that matters. The dangerous words are not the technical ones. A reader who meets "WebSocket" knows they have met a technical word and can look it up. The trap is an ordinary word used in a project-specific sense: chunk, build, source, component, handout, self-contained, linked, fill. The reader recognises it, assigns the everyday meaning, reads on, and is quietly wrong, with no signal that anything happened. Symptom: a word your team says in chat that you would have to explain to a new colleague. Introduce the local sense on first use, or pick a word that carries no local sense.

Never buy readability with accuracy. If the simpler word drops a distinction the text depends on, keep the harder word and gloss it. Cutting the distinction to smooth the sentence leaves the reader confident and misinformed, which is worse than leaving them stuck.

Pass 2: ambiguity

Load human-writing, section "The Ambiguity Pass", for the categories in full with examples. For academic text add references/academic.md, "Pass 2".

Different question from pass 1: does each sentence have exactly one reading?

You are the worst available detector of your own ambiguity, because you know which meaning you meant and every sentence therefore resolves for you. Read as somebody meeting the text cold, with no memory of what it was supposed to say.

Hunt these seven categories:

1. Deictics with no referent. "here", "this", "that", "above", "below", "the same". Test: could a first-time reader point at the thing? Worst where a document nests several things that all get called "this": this page, this repository, this tool, this section.
2. Pronouns with a contested antecedent. Grammar points at the nearest candidate noun; readers point at the one they were already thinking about, and the two often differ.
3. Layout breaks reference. Source order is not reading order. A pronoun whose antecedent sits in another column, a sidebar or a separate block reads as unanchored even when the two are adjacent in the file. Check the rendered output, not the source. Check that "on the right" and "above" are still true at narrow widths where columns stack.
4. Ambiguous agents. "assistant" (a person or a model?), "we", "you", "the user", "somebody". Watch "you" sliding between roles inside one section.
5. One term, several senses. Terms the document itself uses inconsistently: "lecture" as the event, the source file and the output; "notes" as speaker notes and as printed notes. Settle on one sense per term, name the other senses differently, apply throughout.
6. Scope and attachment. Modifiers that could attach to two nouns, negation whose reach is unclear, a qualifier that may or may not cover the last item of a list.
7. False equations. X is Y, X is a/the Y, X means Y, X is what/where Y – German X ist ein/eine/der/die/das Y, X heißt Y, X bedeutet Y – where X is not a Y. The first reading passes, because the idea is right; the second stops, because the two nouns do not name the same thing. "The app is a window you download" – the app is a program, you download it, and it shows a window. "The command line is a clone and an npm install" – the way through it begins with those. Ask the question literally: is X really a Y? If Y is what you do with X, what X needs, begins with, is made of, or shows, replace is with the verb that names the relation. Never with a hedge – "is basically", "ist im Grunde" keep the wrong equation and drop the sentence's only virtue. Real definitions stay ("a chunk is one heading with the text under it"), and so do metaphors the text argues for and supports ("a slide is a frame"); check that the argument is actually on the page. Section 11 of human-writing, "The False Equation", has the table of pairs.

Fix minimally. Name the referent, or split the sentence. Do not rewrite what is already clear. Never buy disambiguation with a precision the source does not support: if you cannot tell which reading was meant, flag it, because silently picking the likelier one turns an ambiguous sentence into a confidently wrong one.

The over-correction risk

"Replace the pronoun with the noun" produces worse prose when applied mechanically, and this failure is common enough that every disambiguating edit needs a second question: is the new sentence also better?, not only "is it less ambiguous?". Two real failures:

• After: "a deck of 16:9 slides ... can read the deck for themselves." The noun was repeated three words after its own introduction, where "it" had exactly one candidate and was never in doubt.
• After: "The report is the cheaper of the two." The sentence compares two activities, so the subject had to stay an activity: "Writing the report is the cheaper of the two."

If the pronoun has one candidate, leave it. If naming the referent flattens the sentence, recast instead.

Pass 3: inverted pyramid

The most important sentence comes first, in every section and every longer paragraph. This is usually moving a sentence that already exists, not writing a new one.

Two checks that catch most of it:

• No paragraph saves its point for its last sentence.
• No section opens with history, context or a caveat before it has said what the thing is.

Pass 3.5: self-congratulation

Not a full read - a search, run after the three passes, because the earlier passes tend to introduce it. Tightening a sentence is exactly when a writer reaches for a clause explaining why the thing being described was a good idea.

Load human-writing, "Tone Patterns to Avoid" section 9 (the praising form) and "Structural Patterns to Avoid" section 19 (the explaining one), for the surface forms and the worked examples. The procedure is:

1. Collect candidates two ways, and the second is not optional:

   • By phrase, from section 9: "earns its place", "the whole point", "not an oversight", "on purpose", "for free", "the honest X", "is the reason this exists".
   • By shape, from section 19, because the explaining form contains none of those phrases and a phrase-only search reports the document clean: "X rather than Y" where both name the same thing; "the one job / question / thing"; "its only …"; a trailing ", which is …" that restates the sentence; a "because" clause about the author's reasoning; a summarising tail ("and those two carry all of it").

2. On each hit run the deletion test: cut the clause and re-read. Ask it as the reader-action test - would a reader now do anything differently, or expect anything different? If not, the clause was admiring or glossing the decision, and it goes.

   Expect the shape search to over-fire, and let the deletion test do the deciding: on one real run it raised 111 candidates across five documents and 2 survived, because "rather than" between two outcomes ("fails the build rather than shipping a broken path") is exactly what a reader needs, while "rather than" between two descriptions of one thing ("adjust a composition rather than replacing it") is the fault. That ratio is the normal result, not a sign the search is miscalibrated.

3. Report the hits you kept as well as the ones you cut, with the reason. A design rationale that a reader needs is not self-congratulation, and the honesty test protects every statement of a limitation, a refusal or a trade-off at full precision.

The failure mode this pass catches is specific: every sentence is individually true, so the vocabulary and ambiguity passes have nothing to object to, and what accumulates is a document that reads as pleased with itself. It is commonest in technical and design writing, where the author knows why every decision was made.

Pass 3.6: universal quantifiers

Also a search rather than a read, and run beside 3.5 for the same reason: the inverted-pyramid pass moves the claim to the front of the sentence, which is where a quantifier gets added to make it land.

Load human-writing, "Tone Patterns to Avoid" section 10. Search both languages for every, each, all, always, never, nothing, none, only, any and jeder, jede, jedes, alle, immer, nie, nichts, kein, nur, and on each hit ask one question: would an exception be a bug someone would fix?

• Yes - it is a guarantee. Leave it absolute. Weakening a tested promise is a worse edit than the one you were making.
• No - the word is emphasis. Delete it and re-read; the sentence is usually still true and usually better. If deleting it leaves the sentence false, name the bounded fact instead.

Never substitute a hedge. "Almost always", "in most cases", "generally", "in der Regel" are the failure mode of this pass. They cost the same words and say less than the universal did.

Two shapes over-fire and are not the fault: a quantifier that states a scope ("it is on every slide of that part" describing what a setting does), and a quantifier counting evidence ("every construction the language has, drawn rather than described" as the documented job of a reference document). On one real run, 114 hits across eight files yielded 18 edits - about a sixth, and that ratio is the normal result. A pass that changes most of its hits has stopped asking the question.

Report the count checked and the count changed. The ratio is the evidence that the question was asked rather than the search run.

The house style, described by tests rather than adjectives

Adjectives are useless to an editor. Any sentence can be defended as "crisp" or "friendly", so a style brief written in adjectives licenses everything and constrains nothing. These four tests can be failed:

1. Checkable-claim test. Every claim can be verified by the reader, or it is cut. "It is the real thing rather than a preview" fails. "Save it and it still opens with the network unplugged" passes. When a claim is unverifiable, weaken it to what is true rather than deleting the information.
2. Scan test. A reader who reads only the first sentence of each paragraph gets the substance. A reader who skims only the bolded phrases gets the argument.
3. Cold-read test. Someone meeting the text with no prior knowledge can resolve every reference and every term.
4. Honesty test. The passages saying what the thing is bad at, who should use something else, and what you give up must survive every pass at full precision. They are the most credible part of the text. Simplifying vocabulary is never a licence to remove a distinction.

Banned patterns, in addition to the catalog in human-writing:

• The three-beat cadence: "Write one file, run one command, get slides." This is the most reliable marketing tell precisely because every clause is individually factual, so vocabulary and claim rules never catch it. Only the rhythm gives it away. Break the parallelism or drop a beat.
• Triads assembled for rhythm rather than because there are three things.
• "not just X, it's Y", "unlock", "seamless", "powerful", "effortless", "simply", "leverage"; rhetorical questions as headings; exclamation marks.
• Hedge-then-claim padding ("It's worth noting that ...").
• Em dashes. If the document has none, it must still have none afterwards.
• Bolding a whole sentence.

Headings name the thing or the benefit, not a clever formulation. Real fix: "Two ideas do the work" became "Slides that fit any screen, colours in one file".

Bold as a scan anchor: at most one bold phrase per longer paragraph, a phrase and never a whole sentence, never two in one paragraph. More than one and the anchor stops anchoring, because the eye has nothing to land on.

Calibration examples

An abstract definition of a fault class produces both over- and under-detection. A model that has seen one worked example of "scope contradiction" finds the class. Read these before starting, and add new pairs here whenever a run turns up a fault class that was not obvious from the rule.

Ambiguity, alternating pronoun

• Before: "The chart is drawn by the browser, and it takes its colours from the theme, so it matches whichever theme is loaded."
• After: "The browser draws the chart and takes the colours from the theme at that moment, so the chart matches whichever theme is loaded."
• Why: "it" alternated between browser and chart inside one sentence.

Ambiguity, scope contradiction

• Before: "with the measurement that found it. Including the ones the measurements missed."
• After: "with the measurement that found it, and the faults no measurement caught."
• Why: a qualifier about the measurement that found a fault cannot cover faults that nothing found. The scope of the qualifier contradicted the sentence it qualified.

Unrequested rationale, an explanation nobody asked for

• Before: "cover: names the title slide. The ten run quiet to loud rather than alphabetically, because the one question the list asks is how much the opening slide should assert itself."
• After: "cover: names the title slide. They are ordered quiet to loud."
• Why: the trailing clause defends the ordering to a reader who wants to pick a title slide. Nothing they do changes when it is cut. It contains none of the section 9 phrases, which is why a phrase search called the page clean through several passes.

Unrequested rationale, the one that must survive

• Kept: "On Windows, unpack the .zip rather than opening it by double-click: Windows shows the contents of a ZIP as if it were a folder, but commands cannot run inside it."
• Why: same shape, opposite verdict. Cut the clause and the reader does the wrong thing. The shape raises the candidate; only the deletion test decides.

Jargon, load-bearing term glossed in place

• Before: "The deck is self-contained."
• After: "The deck is self-contained, meaning the one HTML file carries everything it needs and opens without a network."
• Why: "self-contained" is category 2, load-bearing but carrying a private sense. The everyday reading ("tidy", "complete") is close enough to feel right and wrong enough to mislead.

Verify, and report the numbers

Structural invariants must be counted before and after and compared. Eyeballing a structural change does not detect it, which is the whole reason the counts exist. Count what applies:

• heading count, section count
• navigation or contents entries against heading count
• no new external assets or dependencies
• zero em dashes if the document had none
• for multilingual documents, the same counts on both language versions

For rendered documents (HTML, PDF, slides), check in a real renderer rather than reasoning about the markup. Confirm no horizontal overflow and no heading that now wraps a panel to two lines.

Calibrate any new check in both directions before trusting it. Confirm it fires on a case that has the fault, and stays silent on a case that does not. A check that reports clean while the fault is present is the dangerous failure mode, because it ends the investigation.

Report format

A table, grouped by pass, one row per change:

Then a second list, explicitly: things you judged worth changing and deliberately left alone, each with the reason. That second list is what makes the pass reviewable, because without it the reviewer cannot tell a considered decision from something you never saw.

Then the verification numbers, before and after. For the two search passes, report hits checked and hits changed, not only the changes: a search pass that changed most of what it found has stopped asking its question.

Conditional extras

Load these only when they apply. On plain prose they misfire.

• Text with markup, or a web page: references/markup-and-web.md.
• A document that exists in two or more languages: references/multilingual.md.