reviewing-technical-prose

仓库原始内容

按源仓库内容呈现，保留标题、案例、代码、表格、链接以及原文引用的演示图片。

Reviewing technical prose

REQUIRED BACKGROUND: the technical-writing skill, including references/style.md (banned constructions) and references/truth.md (claim rules).

Overview

Editing is diagnosis. Every edit names the concrete defect it fixes; the smallest edit that fixes it wins. Rewriting natural or approved language without a named defect is itself a defect.

Review the full document, never a summary of it: a reviewer working from a digest invents missing-section findings.

When to invoke, and not

Invoke when reviewing or rewriting someone else's technical text, when producing a findings report on a document, and as the final pass before delivering anything you wrote yourself. Do NOT invoke for code review (only the prose in it), and do not use a review pass to relitigate settled decisions, expand scope, or restyle a document onto your own preferences.

Severity mapping

BLOCKER: hard-rule violations (banned dashes, changelog sections, delivery history in prose) and any claim the cited source does not support or that traces to nothing.
WARNING: banned constructions, structural defects (question headings, buried conclusions, rearrangeable paragraphs), and claims supported only loosely.
OBS: ambiguity, missing polish, and anything an attentive author would likely catch.

Rewriting someone else's text

One requirement above all rules: the content stays identical. Work in this order:

Read the source. Mark every banned construction and word-choice violation.
Write a version. Read it aloud.
Ask three control questions:

Which sentence still sounds like a language model?
Did the rewrite add or drop a fact, number, date, name, source, or claim?
Does the rewrite recreate a removed pattern in a new rhetorical form?

Repairs breed their own tells, so re-scan the rewritten paragraph as if it were source text.

Repair what the control questions surface. An addition and a loss both count as errors, even when the text reads better for it.

Never add a fact to finish a sentence: ask the author or pick a simpler sentence. If a sentence stays wooden after two attempts, rewrite the whole paragraph around its main point. Change only running prose: code blocks, frontmatter, table data, and link targets stay as they are.

The rewrite keeps the document's language. A Dutch document comes back in Dutch, with the structural and truth rules applied as always; the English-specific vocabulary checks are replaced by that language's own list where one exists.
When the author is reachable, the diff is the proposal. Show the rewrite before overwriting their text. Unattended in a repository, the commit is the proposal and review does the same job.

When the source text asserts nothing recoverable (setups, glosses, meaning-sentences), the correct rewrite is deletion plus a marked gap (**[input wanted: <the claim the sentence should make>]**, the claim-level sibling of the core skill's **[source wanted: ...]**) where a real claim should stand. A rewrite full of marked gaps is the intended outcome for claim-free source text, not a failure.

Findings to leave alone

The banned-constructions list helps recognize machine text; it proves nothing by itself, and every pattern also occurs in good human writing. Flag only when several signs coincide in the same paragraph.

Polished grammar and consistent formatting: many writers are professionals, or edited.
One repeated sentence opening: repetition can be rhythm. Fix only when it adds nothing.
One short sentence for emphasis: only a row of fragments is a problem.
Formal words in general: the list names specific words; not every formal word needs simplifying.
A factual contrast: "the pipeline sets the tag, the developer does not" is a statement, not antithesis.
A serious alternative the reader would genuinely weigh: it belongs in the document.
Qualifiers that bound something: scope, assumptions, and safety or legal notes stay. Only the stacking goes.
A reference to the previous situation in a migration doc or release note: there the change IS the subject.
A quoted word: never rewrite inside a citation, a title, or an example that discusses the word.
Metaphor that explains: only the decoration around it goes.
Deliberate awkwardness: a clear fragment or lopsided sentence is not a defect merely because it could be polished.

Review reports

Verdict in the first line, findings ordered most severe first.
Severity vocabulary defined in the report that uses it: BLOCKER (cannot proceed), WARNING (likely rework; fix but not blocking), OBS (worth noting).
Every finding: one sentence stating the defect, a location (file:line, section, task ID), a proposed fix, and a confidence level.
A named empty case ("FINDINGS: none") so a silent reviewer and a clean result cannot be confused.
A document claim contradicted by the code is a defect in the document; report it with the conflicting source. An unrelated bug you noticed in passing is not your finding.
Re-reviews list only what remains.
Acknowledge what is good; a review that only objects is not calibrated.

Delivery checklist

Before any document goes out:

[ ] Matched to the existing documents in the same directory, and added to the README.md index if one exists
[ ] No em dashes, en dashes, or ` -- `; no changelog section or "last updated" field; no ticket keys, phases, or SHAs in prose
[ ] No banned constructions (the technical-writing skill's references/style.md); check at least the summary and the closing paragraphs
[ ] Headings name the content: no question forms, no "What X means", no heading repeated in its first sentence
[ ] Conclusion first at document, chapter, and paragraph level
[ ] Procedures: one action per sentence, with an actor
[ ] Where the document proposes or decides: every non-trivial choice has its reasoning and a serious alternative recorded, and the costs are in, not only the benefits
[ ] Fact and proposal are distinguishable; estimates labeled; unknowns explicitly unknown
[ ] Every claim with a number traces to a source named in the document
[ ] References checked by following them: chapter numbers, relative links, and file names actually exist (they break silently on every restructure)
[ ] Terms consistent and defined at first use; one term per concept
[ ] Read aloud: at least the summary; no row of fragments, no three sentences with the same opening
[ ] Remove-the-name test on the opening and summary: with the product name deleted, a stranger can still tell what the text is about
[ ] Reads cold, reads whole: natural to someone who never saw the conversation or feedback rounds that produced it; one voice throughout, no patchwork seams, no sentence explaining why the document was written this way
[ ] On a rewrite: no fact, number, date, or source added or lost