revise

Files (14)

• SKILL.md
• r2r_voice.md · references/
• revision_values_schema.md · references/
• _quote_match.py · scripts/
• check_density_complaint.py · scripts/
• check_response_claims.py · scripts/
• decision_letter.md · scripts/density_complaint_challenge/fixture/
• v20_longer.md · scripts/density_complaint_challenge/fixture/
• v21_shorter.md · scripts/density_complaint_challenge/fixture/
• v_prev.md · scripts/density_complaint_challenge/fixture/
• verify.sh · scripts/density_complaint_challenge/
• skill.yml
• revision_values.json · templates/
• test_response_claims.sh · tests/

SKILL.md (first lines)

# 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/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:
   ```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, 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:

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills