Revise

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

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.

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/figure until the committed script + CSV (or figure file) returns. Reviewer-response numbers always trace to a produced artifact, never to a model estimate.

Step 2.5: Revision Numerical Lineage Check (MANDATORY)

A script written to satisfy a reviewer (a comparative arm, a subgroup, a sensitivity check) often hand-enters values copied by eye from the original paper's tables, bypassing the locked extraction CSV; the numbers are then consistent everywhere and wrong at the source. In one R1 revision a hand-typed Fisher matrix read an adjacent severity-grade column as the event count, and the script, manuscript, and Table all carried the same direction-reversed result.

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 comes off only at Step 7 (Final Verification), after an 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, so no new value skips the dual-extraction consensus layer.

4. Revision-time numerical audit table — maintain it inside the response document draft and copy it 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, because prose written around un-audited numbers is very hard to unwind after a mismatch is found.

Step 3: Generate Response to Reviewers Document

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

Read ${CLAUDE_SKILL_DIR}/references/r2r_voice.md before drafting: before/after examples, three response skeletons (accept / partial-accept / polite-rebuttal), and a meta-phrase-to-natural conversion table.

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: acknowledge, describe the change, and quote it: "The revised text now reads: '[new sentence].'"

• MAJOR: acknowledgment -> new analysis -> key result -> location of changes. All new results MUST include the 95% CI and exact p-value. New text added to the Results section states findings only; interpretation belongs in the response letter or the Discussion.

  [Acknowledge; state the concern.]
  To address this, we [describe new analysis/experiment/rewrite].
  [Key result: metric = value (95% CI, lower-upper; P = exact value)]
  This finding [supports / strengthens / does not change] our original
  conclusion because [brief interpretation].
  We have added: [Table X / Figure X / Supplementary Table X] showing [content];
  Methods revised: Page X, Lines Y-Z; Results revised: Page X, Lines Y-Z.

• REBUTTAL: polite but firm; open with acknowledgment, restate the reviewer's claim fairly, then give your position with evidence. Do not capitulate without scientific justification. Where it helps, add a clarifying sentence to the manuscript and quote it.

Cite only references verified via /search-lit with a confirmed DOI or PMID; mark any other as [UNVERIFIED - NEEDS MANUAL CHECK]. Never invent a clinical definition, diagnostic criterion, or guideline recommendation: flag an unconfirmed one with [VERIFY] and ask the user.

The acknowledgment lines in the skeletons are placeholders. Repeating one opener ("We thank the reviewer for this important suggestion.") down the letter is itself an AI-tell, so vary them.

Response-Letter Voice & AI-Tell Avoidance

A response letter is a reviewer-facing scientific argument, not an internal change log. The AI-tell patterns are defined once in humanize references/ai_patterns.md (patterns 22-24); references/r2r_voice.md carries the authoring guidance. The rules:

1. Write the change and the science, not the editing mechanism. State what changed and why, and quote the new sentence. No version prefixes ("v2 adds..."), no "softened N phrases", no grep/verification language, no internal FIX codes, no bare "No further manuscript change" stubs. Describing a new analysis you ran ("we performed a sensitivity analysis and found X") is the science, not a tell.
2. No § symbols, no internal draft line numbers. A revised-manuscript page/line, stated once as referring to the revised manuscript, is fine.
3. Succinct and non-defensive, especially on R2+. A satisfied reviewer gets one sentence. No cross-reviewer lobbying ("Reviewers 2 and 3 also accepted this") and no defensive meta-comments ("we confirm this statement is unchanged and not softened"). Fold methodology disclosure (multiplicity, a SAP deviation) into the response to the comment it answers, never a separate front section, and never drop it. Split a multi-point reviewer paragraph into separate comments, each with its reviewer sentence quoted.

Mandatory pre-submission scan

Before circulating or uploading, run /humanize on both the response letter and the cover letter. The response-letter scan is patterns 22-24 plus 13 (em dash), 16 (filler), and 19 (§) in humanize references/ai_patterns.md. Hold the letter to the manuscript's classical-style bar (/write-paper references/section_guides/step7_1_classical_qc.md): zero § symbols, no (Methods §X) self-references, em dashes kept low, and the heading style the target journal actually publishes.

Response-claim verification gate (MANDATORY, deterministic)

The single source of truth is the revised manuscript, not the response prose. A letter that says "we added the sentence '…'" or "we now cite Tariq et al. [15]" must be verifiable in the body. Run the gate before sending:

python3 ${CLAUDE_SKILL_DIR}/scripts/check_response_claims.py \
  --response revision/response_to_reviewers.md \
  --manuscript manuscript/manuscript.md --strict

Add --out qc/response_claims.json to write the verdicts to qc/response_claims.json.

RESPONSE_QUOTE_UNVERIFIED (a quoted added sentence absent from the body) and RESPONSE_CITATION_UNVERIFIED (an added citation whose token is nowhere in the body) are real discrepancies, since the gate ignores vague, paraphrased claims: either insert the promised edit or correct the response wording. RESPONSE_QUOTE_UNRESOLVED is minor and does not fail --strict: the quoted words are all present in order but separated by extraction debris (a reference column bled in from a two-column PDF, proof line numbers, a footnote marker, a hyphen split across a line). Look at it by eye; do not delete a quote because of this verdict — accurate quotes have nearly been deleted that way. When a body bracket holds only numbers (',' or ';' separated, ranges with the common dashes, '~', '--' or '---', spaces and pandoc's escaped \[5\] allowed), a numeric citation counts only as a whole element or inside a range: a claimed [5] is not satisfied by [15]. A bracket that mixes numbers and words ("[5, see also 8]", "[5, p. 12]") keeps the older prefix match, so "[15, p. 3]" still satisfies [5] there; check such citations by eye. The response letter is read as typed: a claim written in pandoc form ("[5]", "[5--7]") is not recognised as a citation claim and is not checked.

To check the numbers themselves, declare the audit table (Step 4) as revision_values.json (copy ${CLAUDE_SKILL_DIR}/templates/revision_values.json; schema in references/revision_values_schema.md) and add --values revision_values.json: a declared value missing from the paragraph or table row that holds its anchor is RESPONSE_VALUE_MISMATCH (major).

Known limits: without --values, quote CONTENT is not compared. A quote that differs from the body's sentence by a number (the letter says 0.92, the body 0.87) or by a negator ("not", added or dropped) is graded like extraction debris, minor RESPONSE_QUOTE_UNRESOLVED, and --strict passes; comparing the letter's numbers with the body's was withdrawn because both sides vary in format. --values checks declared numbers only, and a paragraph with superscripts or x10^n is RESPONSE_VALUE_NOT_ASSESSED. Read every UNRESOLVED quote by eye for a flipped finding. A citation claim passes when ANY of its cited tokens is in the body, so "we now cite [15] and [16]" passes with only [15] inserted; check multi-citation claims by eye. A claim is read as a citation claim only when its verb says so ("cite", "reference"): "We added the citation [15]" or "We have added a reference to X [15]" is not checked. Read any added citation by eye; reading past the verb was withdrawn ("reference standard" fired).

If a reviewer called the manuscript too long or too dense, prove the body got shorter. Answering a density comment point-by-point adds a sentence per point, so the revision that responds to "shorten this" comes back longer. This gate is arithmetic:

python3 ${CLAUDE_SKILL_DIR}/scripts/check_density_complaint.py \
  --comments revision/decision_letter.md \
  --previous manuscript/manuscript_R0.md \
  --revised manuscript/manuscript.md --strict

DENSITY_COMPLAINT_UNADDRESSED fires only when the decision letter contains a density/length complaint AND the body word count (Introduction through Discussion, citation markers excluded) did not fall; with no complaint it stays silent. When it fires, cut or move detail to the supplement; do not defend the length by adding a paragraph that explains it.