Writing Review

Writing review

A revision pass over text that already exists. The project's comment and doc rules live in CLAUDE.md's Code Quality and ROADMAP.md Style sections; this skill is the sentence-level pass on top of them, and where the two overlap CLAUDE.md wins. The reference files carry the longer derivations; open one when the summary here is not enough.

• references/register.md: the ten sentence-level tics, a worked rewrite from this repository, coined terms, metaphors, and filler.
• references/commit-messages.md: subject and body conventions, when a body earns its place, what never goes in one, and how to sample the maintainer's voice from the history.
• references/code-comments.md: what to cut from a comment, what rustdoc needs, and what has to stay grammatical.
• references/docs-and-readmes.md: stating the rule, writing at the document's altitude, ROADMAP rows, self-standing plans, and README audience.

The arguments are: $ARGUMENTS

Two ways to run

Bounded. With no paths, the pass is bounded by the working tree: the comments and docs the current diff touches, and the commit message being drafted. This is how the commit skill runs it. Rewording a neighbouring comment the change did not require draws "why this change?" in review and gets reverted, so a line the diff does not touch stays as it is.

Sweep. With paths (files, directories, or a glob), read every comment and doc page under them, apply steps 2 through 5 in place with the Edit tool, run step 6 over the result, and report what changed and what was left alone with the reason. A sweep fixes meaning: contrast tails, historical framing, restatements, unverifiable claims, fragments. It does not chase punctuation tics through untouched sentences; rules 7 and 10 below apply to sentences the sweep is rewriting anyway. After editing Rust files, run cargo clippy -p <crate> --all-targets --all-features -- -D warnings, since clippy::doc_markdown is denied and a bare identifier in a doc comment fails the build, and cargo doc -p <crate> --no-deps when an intra-doc link moved.

Scope

Apply this to prose written for a reader: commit messages, /// and //! doc comments, // comments, README files, docs/ pages, ROADMAP notes, and the prose in plans and reports.

Five kinds of text are out of scope.

• Instruction files written for a model: CLAUDE.md, the skills under .claude/, agent memory. The contrast and negation rules do not apply to them.
• Generated text. The schema views openusd-build emits, and the golden files under its tests/ and fixtures/, are generator output: a wording problem there is fixed in the generator (doc.rs), and the goldens are regenerated, never edited by hand.
• Vendored material under vendor/, and quoted text anywhere: a passage from the AOUSD spec or a C++ doc comment. Fix the framing around a quotation, never the quotation.
• Deliberate authored voice. A warning a README carries on purpose stays.
• Lines the current change does not touch, in the bounded mode.

Step 1: name the artifact and its reader

Each rule below resolves differently depending on who is reading.

Step 2: cut what the reader never asked for

A concern that was only yours. Before keeping an explanatory sentence, ask whether a reader who sees only the final artifact has that question. If the question exists because you worked through an alternative or hit a worry, cut it. A commit body that says a helper's return "sufficed" answers the author's earlier worry; the reader sees the diff and never had it.

A contrast against something the reader cannot see. Strip trailing instead of, rather than, not just, unlike, and no longer clauses, and drop promotional intensifiers (powerful, seamlessly). Explain from the constraint that forces the design. CLAUDE.md states the same rule for comments: "we use A so we don't B", "instead of calling Z", "a subtree walk rather than a full scan" only make sense to someone who saw the alternative.

BAD   An empty taxonomy or interval is refused rather than answering with
      nothing.
GOOD  An empty taxonomy or interval is refused.

A contrast is wanted when both sides are in front of the reader: a body that names a problem and the approach taken, two tests that coexist in the tree, the C++ behaviour a doc comment says this code departs from. The rule targets defending a design against a rejected alternative the reader never raised.

Historical framing. Describe current behaviour in the present tense. No "no longer X", no "used to X", no "now keyed by path". This bites hardest in a squashed commit, where the contrast points at a state that never exists in history.

BAD   asks the attributes whether they may vary over time rather than
      recording that at construction
GOOD  asks the attributes whether they may vary over time

A sentence that restates the one before it. Three forms, all cut:

1. A closing sentence re-expressing a term already used. "EARLIEST is f64::MIN. The read reaches the earliest sample." The name already says it; the second sentence goes.
2. A comment describing the lines directly beneath it. Keep the requirement, drop the "so both are passed" tail.
3. An example re-deriving the rule stated above it.

Check each sentence against the one before it and against the code beneath it. If a reader who understood the previous sentence learns nothing, cut it.

A hypothetical written in the present indicative. An option that was evaluated and not adopted does not have real behaviour. Put its consequences in the conditional: "a per-prim bump would under-invalidate", not "a per-prim bump under-invalidates". Drop concessions that grant a merit before the disqualifying property. Cut forward-looking Status sections; describe the current state.

Vague filler. "wire up the plumbing", "lay the groundwork", "improve robustness". Name the concrete file, function, or change, or say nothing.