reviewing-technical-prose

---
name: reviewing-technical-prose
description: Use when reviewing, rewriting, or editing someone else's technical text, when writing a review report on a document, or as the final check before delivering any document. Encodes the severity mapping, the findings format, the what-not-to-flag list, and the delivery checklist. Use before any document ships, even when it looks fine.
---

# 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:

1. Read the source. Mark every banned construction and word-choice violation.
2. Write a version. Read it aloud.
3. 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.

4. 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