editorial-review

Editorial review for technical prose

This skill describes how to run an editorial review of a piece of technical prose with the help of an independent external reviewer. It does not describe with which tool the reviewer is invoked: the concrete bridge is the responsibility of the slash commands that load this skill.

Purpose

Get an independent second opinion on a single piece of technical prose to catch factual errors, ambiguities and stylistic slips before commit. The external reviewer offers a different but fallible point of view: its output is always critically filtered, never rubber-stamped.

Core principles

1. Two phases, never overlapping. Content first, then style. Content review is done on stable text; style review is done on already-consolidated content. Mixing the two produces scattered reviews and overlapping patches.

2. Independent judgment before invoking the reviewer. Whoever orchestrates the review must read the file in full and form an autonomous opinion before invoking the external reviewer. A baseline is needed: without it, "critical filtering" becomes mere transcription.

3. The reviewer does not modify files. The review is read-only. Patches are applied by the orchestrator. This rule is reinforced in every focus text passed to the reviewer.

4. Critical filtering is mandatory. Not all findings should be accepted. Some reflect reviewer bias (register, terminology), some ignore the user's deliberate project conventions, some are simply wrong. For each rejected finding, record a brief reason.

5. Mandatory post-patch verification pass. If the phase produced any patch, a fresh reviewer invocation on the updated file is required. The pass evaluates not only the file but also the orchestrator's filtering: (a) which previous findings are actually resolved, (b) whether new problems were introduced, (c) whether anything that was clear before became unclear, (d) whether the rejected findings were rejected for sound reasons or whether the reviewer wants to push back. The phase is not closed on the orchestrator's confidence alone, and the second-opinion role extends to the filtering decisions, not just to the patches.

6. Iteration budget. Maximum 3 reviewer invocations per phase, including the verification pass. Beyond that, close the phase and report any open findings explicitly. The budget prevents dispersive loops.

Severity scale for findings

Three levels, used both in the focus texts and in internal tracking.

• blocking: factual error or ambiguity that compromises understanding. Example: a wrong definition, a formula with a sign error, a step that skips a necessary hypothesis.
• significant: imprecision, missing intermediate step, local opacity, internal terminology incoherence, stylistic choice that hurts the exposition, excessive use of dedicated callout boxes. Does not compromise global understanding but degrades quality.
• minor: polishing. No deeper than fine linguistic revision.

A "blocking" finding is a strong claim: use it only when it really applies. Inflating the category empties the signal.

Project conventions of the user's text

The user's project may have its own editorial conventions (register, reader address, notation, terminology, callout boxes, deliberate stylistic choices). These conventions live in the user's repository, typically in a file like AGENTS.md at the repository root. The external reviewer reads them autonomously when present.

This skill does not repeat them: the focus text passed to the reviewer simply mentions AGENTS.md (or the equivalent) as the source.

Override mechanism

The default focus texts below are in English and target generic technical prose. The user can override them by placing custom files in the working repository:

• .claude/multimodel-editorial-review/focus-content.md — overrides the content-phase focus text;
• .claude/multimodel-editorial-review/focus-style.md — overrides the style-phase focus text;
• .claude/multimodel-editorial-review/focus-verify.md — overrides the post-patch verification focus text.

When orchestrating a phase, first check whether the override file for that phase exists in the user's repository. If it does, use its contents as the focus text instead of the default below. This lets users adapt the review to a different language, a specific domain (math, software, biology, history), or project-specific conventions, without forking the plugin.

Default focus text — content phase (English)

Use this as the prompt for the first invocation of the reviewer in the content phase. The variable [FILE_PATH] is substituted before passing the text to the reviewer.

Editorial review of the file [FILE_PATH]. Read the file from the file system.

DO NOT modify any file. The review is read-only: only findings in your output.

Phase: CONTENT.

Focus on:
- factual correctness and precision of definitions, statements, claims;
- expository clarity and logical order;
- internal terminological coherence and coherence with the conventions of the user's project;
- completeness of steps and stated assumptions;
- compliance with the user's project editorial conventions (see AGENTS.md or equivalent at the repository root: that is the authoritative context);
- meaning of any embedded diagrams (TikZ, ASCII art, code blocks): judge them by their semantics, not by the rendering.

Keep observations on content separate from observations on exposition. Do not enter the syntax of the markup language nor stylistic linguistic choices: style is the subject of the next phase.

Severity scale: blocking / significant / minor.
Order of presentation: by decreasing severity.
For each finding: file, line, category, description.

If you find no real problems, say so explicitly.

Default focus text — style phase (English)

Use this for the first invocation of the reviewer in the style phase, only after the content phase has been closed and any patches applied.

Micro-stylistic review of the file [FILE_PATH]. Read the file from the file system, line by line.

DO NOT modify any file. The review is read-only: only findings in your output.

Phase: STYLE.

Focus on:
- rhythm;
- register (the project's stated tone, see AGENTS.md or equivalent for the user's preferred register);
- flow and readability;
- close lexical repetitions;
- unnatural phrasing or inappropriate calques from another language;
- sentences that are too dense, rigid, or over-nominalized;
- compliance with the project's stylistic guidelines as documented by the user.

Do not enter the merit of the content nor the choice of what to include: those were the subject of the previous phase.

Severity scale: blocking / significant / minor.
Order of presentation: by decreasing severity.
For each finding: file, line, category, description.

If you find no real problems, say so explicitly.

Default focus text — post-patch verification

Used after applying patches in the same phase, with a fresh reviewer call that has memory of previous findings.

The orchestrator MUST include in the prompt the list of previous findings with their filtering outcome (accepted, rejected with reason, left open), so that the reviewer can also evaluate the rejections.

Default prompt template (substitute the placeholders):

Verification pass on the file [FILE_PATH] after patch application. Read the updated file. DO NOT modify any file.

The orchestrator has filtered your previous findings as follows:
- ACCEPTED (patch applied): [list of findings]
- REJECTED (with reason): [list of findings, each with the orchestrator's brief reason]
- LEFT OPEN: [list of findings]

Report on:
1. Which previous findings are now actually resolved by the patches.
2. Any new findings introduced by the modifications (regressions of content or clarity).
3. Any opacity introduced in passages that were previously clear.
4. On the REJECTED findings: for each, confirm or push back. If you think the rejection reason is weak or wrong, explain why. If you accept it, say so explicitly.

Same severity scale. Same finding format.

Critical filtering of findings

For each finding returned by the reviewer, the orchestrator chooses one of three outcomes.

• Accepted: the finding is correct and the patch is operationally clear. Apply the modification.
• Rejected: the finding is wrong, conflicts with a deliberate project convention, or reflects a reviewer bias. Record a brief reason.
• Clarification: the finding is potentially valid but not operationally clear. Open a follow-up with the reviewer with a narrow question, without applying patches until clarity is reached.

In case of unresolvable disagreement between the orchestrator's judgment and the reviewer's on a significant or blocking finding, do not decide autonomously. Record the disagreement as an open question in the synthesis and leave the decision to whoever supervises the review (typically the user). The language models involved in the review are both fallible and may carry correlated biases on judgments of clarity and tone: the apparent independence of the second opinion is not always full.

The post-patch verification pass is the explicit moment when the reviewer is given a chance to push back on the orchestrator's rejections: the prompt for that pass lists each rejected finding with the orchestrator's reason and asks the reviewer to confirm or counter-argue. If the reviewer's counter-argument is convincing, the orchestrator can revise the rejection (within the iteration budget) and apply the patch. If the orchestrator still disagrees after the counter-argument, the disagreement goes to "Open questions for supervision" in the synthesis: it is not patched autonomously and is not silently dropped.

Recurring anti-bias rules

Some categories of findings are systematically suspect and warrant a second look before being accepted.

• Requests to "say everything upfront": the reviewer tends to ask for definitions or assumptions to be anticipated when the text is in fact introducing them later for didactic reasons. Verify the order of exposition has not been misunderstood.
• Register flattening: the reviewer tends to flatten the author's voice toward a neutral, impersonal style. Many projects deliberately preserve a recognizable authorial voice. Do not accept the standardization unless the project explicitly requests it.
• "Correct" conventions that are not the project's: the reviewer may propose conventions standard in one tradition (e.g. comma decimal separator, abbreviated logical operators, em-dash use) that conflict with the project's deliberate choices. Check the project conventions before accepting.
• Excessive use of dedicated callout boxes: many projects want callouts (warning boxes, tip boxes, sidebars) to remain rare events. If the reviewer reports excessive use of callouts, this is usually a legitimate finding of at least significant severity.

Phase synthesis format

At the end of each phase, the orchestrator produces a synthesis with the structure below.

# Synthesis — phase [content | style] — [FILE_NAME]

## Findings accepted and applied
(by severity, with brief reference to the patch)

- [blocking] line N: finding description -> patch description
- [significant] line N: finding description -> patch description
- ...

## Findings rejected
(with brief reason for each)

- line N: finding description — reason for rejection
- ...

## Findings still open
(if any remain at the end of the cycle, with severity)

- [significant] line N: finding description — why it remains open
- ...

## Open questions for supervision
(unresolvable disagreements, choices that require user input)

- brief description of the question

## Iterations
Reviewer invocations in this phase: X / 3.
If X = 3 without convergence: state it explicitly.

The synthesis is the only artifact that exits the phase. Whoever supervises the review reads it to decide whether the phase is closed and whether to proceed to the next phase.

Explicit exclusions

The following are never in scope of an editorial review, in any phase:

• markup syntax and warnings (LaTeX, Markdown, AsciiDoc, etc.);
• typographical and formatting choices;
• macros, packages, document preamble;
• compilation/build errors;
• git or commit decisions (those belong to the author).

These exclusions are typically also stated in the user's AGENTS.md for the reviewer; the orchestrator should not accept findings in these categories even if the reviewer produces them by inertia.