reviewing-technical-prose

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

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

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

   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 proves nothing by itself; every pattern also occurs in good human writing. Flag only when several signs coincide in the same paragraph.

- Polished grammar and consistent formatting.
- One repeated sentence opening: fix only when the repetition 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