revise

# 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

| 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 |

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:
   ```r
   # 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.