/revise

name: revise
description: Use when a manuscript comes back with reviewer or editor comments. Numbers every comment, classifies it MAJOR/MINOR/REBUTTAL, drafts a point-by-point response with tracked manuscript changes, routes new analyses to /analyze-stats and writes the cover letter.
metadata:
  triggers: "revise paper, respond to reviewers, revision letter, reviewer comments, major revision, minor revision, resubmit, R1 revision, revision round, response letter, point-by-point response"

Revision Skill -- Response to Peer Reviewers

Activation

When the user provides reviewer comments (pasted text, PDF, or file path) or asks to revise a manuscript, confirm before proceeding:

1. The reviewer decision letter (pasted text or file path) 2. The current manuscript file (`manuscript/manuscript.md`) 3. The revision round number (default: R1) 4. The journal name (affects cover letter format)

---

Step 1: Parse and Number All Comments

Read the full decision letter. Extract every discrete comment from every reviewer and the editor.

Numbering Convention

E-1, E-2, ...       <- Editor comments
R1-1, R1-2, ...     <- Reviewer 1 comments
R2-1, R2-2, ...     <- Reviewer 2 comments
R3-1, R3-2, ...     <- Reviewer 3 (if present)

If a reviewer groups multiple requests in one paragraph, split them into sub-items: `R1-3a, R1-3b, R1-3c`

Classification

| Type | Symbol | Definition | |------|--------|------------| | **MAJOR** | `[MAJ]` | Requires new experiment, re-analysis, new figure/table, or substantial structural rewrite | | **MINOR** | `[MIN]` | Requires text revision, clarification, formatting change, or additional citation | | **REBUTTAL** | `[REB]` | Reviewer is factually incorrect, misunderstood the study, or requests something scientifically unjustified |

5-Category Triage Strategy

Sort every comment into one of five categories; the category sets the response approach and informs (does not replace) the MAJ/MIN/REB classification.

| Category | Reviewer is... | Response | Typical class | |---|---|---|---| | 1. Simple Question (most common) | asking for description, clarification, or minor data | Add the requested text and point to its location; keep the reply short | MIN | | 2. Misunderstanding | misreading the design, population, or analysis | Never say "you are wrong": apologise for the lack of clarity, re-explain, and revise the text so the next reader is not misled | MIN or REB | | 3. Further Discussion | raising context (a different health system or clinical practice) | Acknowledge, explain your study context, add a brief Discussion note if appropriate; the full explanation can stay in the letter | MIN (text change) or REB (disagree) | | 4. Additional Results | requesting a subgroup, sensitivity analysis, or additional metric | Run it (Step 2), add results to the Supplement (main text if important), and say what was done and found; never ignore these requests | MAJ | | 5. Statistical Method Challenge | questioning or asking to change the statistical method | Justify the method with references; if the suggestion is valid, run both analyses and show the results agree | MAJ |

Say a statistician was consulted only if one was: a claim about who reviewed the work is a factual claim to the editor.

Answer careless or off-topic comments too, with the same professionalism. For an irrelevant comment, add a clarifying sentence to Methods or Discussion and say where; that shows effort without conceding a scientific point. For a factually incorrect comment, give referenced evidence framed as "We believe there may be a misunderstanding."

**Unify terms before editing sentences.** When several comments trace back to inconsistent terminology (rater / reader / operator; reference standard / reference set), first build a one-page term table — each term, its definition and where it may appear — apply it across the manuscript, then revise sentences; editing sentence by sentence leaves the same inconsistency elsewhere. Keep terms distinct when they name different things, and check that each statistical term is a standard one.

Output a classified comment list before generating responses:

E-1   [MIN]  Request to shorten abstract
R1-1  [MAJ]  Requires subgroup analysis by scanner type
R1-2  [MIN]  Clarify exclusion criteria rationale
R1-3  [REB]  Claims our sample size is underpowered (we disagree)
R2-1  [MAJ]  Requires additional figure showing calibration curve
R2-2  [MIN]  Add reference to [Author Year]

**Gate:** Present the classified comment list to the user. Confirm classifications (especially REBUTTAL vs MAJOR) before generating responses. A misclassified REBUTTAL generates a response that argues with a valid reviewer point.

---

Step 2: Triage -- Flag External Actions Needed

Before writing responses, flag the comments that need external work:

• **/analyze-stats:** any MAJOR comment that needs new statistical analysis, a re-run of an existing analysis, an additional metric (calibration, NRI, ICC), or a sample size recalculation. A `/self-review` finding carrying `requires_reanalysis: true` (power/MDE re-simulation under the full model, first-visit / one-record-per-subject dedup, an extended- or reduced-adjustment over-adjustment sensitivity, optimism correction of calibration) is always routed here: a prose edit cannot answer it, so it must produce a committed script + CSV whose numbers are then fed back here.
• **/make-figures:** any MAJOR comment that needs a new or revised figure (calibration plot, subgroup forest plot, Bland-Altman, new panel).

Output: "The following comments require statistical analysis before responses can be finalized: R1-1, R2-3. Run /analyze-stats with these tasks, then return to /revise."

**If `/analyze-stats` or `/make-figures` is not installed**, emit the same routing list as a checklist for the author to run manually (the named analysis or figure per comment) and hold those responses as `BLOCKED — pending analysis/figu