Revision Skill -- Response to Peer Reviewers

Purpose

Parse reviewer decision letters, classify each comment by type, generate a formal Response to Reviewers document, track required manuscript changes, and coordinate with /analyze-stats or /make-figures when new analyses or visuals are needed.

Activation

When the user provides reviewer comments (pasted text, PDF, or file path), or requests revision of a manuscript, this skill activates. Before proceeding, confirm:

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

Reference Files

• Response-letter voice gallery: ${CLAUDE_SKILL_DIR}/references/r2r_voice.md -- before/after examples, three response skeletons (accept / partial-accept / polite-rebuttal), and a meta-phrase-to-natural conversion table. Read it before drafting the Response to Reviewers document.

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

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, identify which comments require external action:

Comments requiring /analyze-stats: Flag any MAJOR comment that requires new statistical analysis, re-run of existing analysis, additional metric (calibration, NRI, ICC), or sample size recalculation.

Comments requiring /make-figures: Flag any MAJOR comment that requires a new figure 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."

Step 2.5: Revision Numerical Lineage Check (MANDATORY)

Revision-time is the highest-risk moment for numerical hallucinations. A new analysis script written to satisfy a reviewer — typically a comparative arm, a subgroup, or a sensitivity check — frequently hand-enters values copied by eye from the original paper's tables, bypassing the locked extraction CSV. The resulting numbers then flow into the response letter, the revised manuscript, and regenerated figures, and they can be internally consistent everywhere while still being wrong at the source.

Precedent failure pattern — treat as a lived failure, not hypothetical:

An R1 revision introduced a new comparative-arm analysis script to answer a reviewer request. The Fisher exact matrix was hand-typed from the primary source Table, with an adjacent severity-grade column misread as the event count. The script, the revised manuscript, and an accompanying Table all converged on the same direction-reversed numbers relative to what the primary source actually reported.

Non-negotiable actions when Step 2 flags any /analyze-stats re-run:

1. Tag every new numerical claim with [VERIFY-CSV] as it is written into the revised manuscript, response letter, or new table. The tag is a tripwire — it only comes off at Step 7 (Final Verification) after explicit CSV + primary-source back-check.

2. New analysis scripts must read from the locked extraction CSV. Hand-typed matrix(), c(...), or data.frame(...) numerical inputs are PROHIBITED when a CSV row exists. If hand entry is truly unavoidable (e.g., comparative-arm subset not present in the CSV), the line MUST carry a comment citing the CSV coordinate AND the primary-source Table/Figure:

   # source: data_extraction_final.csv row <N> (<first-author> <year>, <arm> only),
   #         verified against <primary source> Table <X>, page <P>
   fisher.test(matrix(c(0, 45, 1, 55), nrow = 2, byrow = FALSE))
   

3. Comparative / arm-specific values must enter extraction_consensus_log.md as separate rows before the analysis script references them. Do not let a new script invent values that never passed through the dual-extraction consensus layer.

4. Revision-time numerical audit table — maintain this inside the response document draft and copy into the final change log:

   New claim (response + manuscript location)	Source script:line	CSV row/col	Primary source (Table/Fig, page)	Match?

5. Gate before Step 3 — do not generate response prose for a MAJOR comment whose new numbers have not yet cleared this check. Prose written around un-audited numbers is very hard to unwind cleanly after a mismatch is found.

Why this matters for reviewer politics: a numerical reversal caught by the reviewer in R2 is far more damaging than the same error caught internally in R1 — it implies extraction integrity problems to the editor and licenses deeper scrutiny of the rest of the data. Treat Step 2.5 as a reputation-preservation gate, not just a QC step.

Step 3: Generate Response to Reviewers Document

Output location: revision/R[N]/response_to_reviewers_R[N].md

Document Header

Response to Reviewers

Manuscript ID: [JOURNAL-XXXXX]
Manuscript Title: [Full title]
Authors: [Last name of first author] et al.
Revision Round: [R1 / R2 / R3]
Date: [YYYY-MM-DD]

We thank the Editor and reviewers for their careful reading of our manuscript
and their constructive comments. We have revised the manuscript accordingly
and provide a point-by-point response below. All changes are shown in the
revised manuscript with tracked changes (or highlighted in yellow).

Per-Comment Response Block

---

**Comment R[X]-[Y]** [MAJ/MIN/REB]

*Reviewer's comment:*
> [Exact text of the comment, quoted verbatim]

**Response:**

[Response text -- format by type below]

**Manuscript change:**
- Section: [Methods / Results / Discussion / etc.]
- Page [X], Line [Y] (in the revised manuscript)
- [Quote the new or changed sentence if short]

Step 4: Response Formats by Comment Type

MINOR Comment

Keep concise (3-8 sentences). Acknowledge, explain the change.

We thank the reviewer for this observation. We have [describe change] in
the [section] section. The revised text now reads: "[new sentence]."

MAJOR Comment

Structured response with four parts: acknowledgment -> new analysis -> key result -> location of changes.

We thank the reviewer for this important suggestion. [State the concern.]

To address this, we [describe new analysis/experiment/rewrite].
[Key result: metric = value (95% CI, lower-upper; P = exact value)]
(All new results MUST includ