Generate a structured response-to-referees document from a referee report and the revised manuscript. Maps each referee comment to the specific revision, classifies coverage (addressed / partially / deferred / disagreement), and drafts polite but firm responses. Use during the R&R (revise-and-resubmit) stage of paper revision.
Produce a complete response-to-referees document by cross-referencing the referee report against the revised manuscript. Classify every concern, draft a courteous response for each, and flag anything unaddressed before submission.
$0 — path to the referee report$1 — path to the revised manuscriptSupported formats and how to read them. In the commands below, FILE stands for the input path being converted — either $0 (referee report) or $1 (revised manuscript). Always use mktemp for the temp file (not a predictable /tmp/... name) so paths with spaces and concurrent runs don't collide, and so untrusted FILE paths can't clobber other temp files via symlink races.
| Format | How to extract text |
|---|---|
.tex, .qmd, .md, .txt | Read directly with the Read tool. |
.pdf |
TMP=$(mktemp --suffix=.txt) && pdftotext "FILE" "$TMP" (poppler-utils; use mktemp -t ... on macOS if --suffix is unsupported). Grep "$TMP". |
.docx | TMP=$(mktemp --suffix=.txt) && pandoc "FILE" -t plain -o "$TMP" (or docx2txt "FILE" "$TMP"). Grep "$TMP". |
.html | TMP=$(mktemp --suffix=.txt) && pandoc "FILE" -t plain -o "$TMP". Grep "$TMP". |
If a required tool is missing or extraction fails, ask the user to provide a plain-text version (.txt or .md) and stop.
Before any parsing or grep, convert non-text inputs (.pdf, .docx, .html) to plain text using the table above. Keep both the temp text file (for grep) and the original (for citation page references).
For every concern:
Grep the plain-text version of the revised manuscript for those terms (and synonyms). Note: Grep only works on text — if the original was any non-text format (for example, .pdf, .docx, or .html), grep the converted temp file from Step 0.Read the surrounding context (±20 lines) to confirm the change addresses the concern.Assign one of four labels to each concern:
| Label | Meaning |
|---|---|
| Addressed | The revision directly resolves the concern with a specific change you can point to. |
| Partially addressed | The revision moves in the requested direction but does not fully resolve the concern (e.g., added one robustness check when the referee asked for two). |
| Deferred | The revision does not change the manuscript on this point but the response will explain why (out of scope, separate paper, conflicting referee, etc.). |
| Disagreement | The author respectfully disagrees with the referee's premise. The response will explain the reasoning and any compromise. |
If you cannot find any evidence of a revision OR a deliberate decision to defer/disagree, mark the concern UNADDRESSED — REQUIRES AUTHOR INPUT and surface it in the warning summary at the end.
For every concern, write a 3–6 sentence response in this structure:
Tone conventions: courteous but firm; never defensive; never quote the referee back at length; use "we" for the author team; avoid "the referee is wrong" — prefer "we respectfully retain our original framing because…".
Write the output to response-to-referees.md (matching the template filename) or a path the user specifies. Use the structure in templates/response-to-referees.md:
The response document's most hallucination-prone content is the set of "we added X on page Y" claims. Hallucinating these gets a paper desk-rejected on sight. Before declaring the response document final, run the Post-Flight Verification protocol from .claude/rules/post-flight-verification.md.
Steps:
claim-verifier via Task with subagent_type=claim-verifier and context=fork. Hand it: the claims table, the verification questions, the path to the revised manuscript. Do NOT include the response draft.Downgrade to the classification the evidence supports:
AddressedPartially addressed or Deferred with an honest rationaleOpt-out: --no-verify flag. Not recommended — the referee will run this check themselves.
After the document is written, include this summary in your final chat message to the user (NOT inside the response document):
## Unaddressed concerns requiring author input
- R1.3: [summary] — no evidence of revision found
- R2.7: [summary] — flagged as deferred but no rationale yet drafted
If everything is covered, the final message should say All concerns addressed or explicitly classified.
response-to-referees.md — the deliverable (filename matches templates/response-to-referees.md)response-to-referees-matrix.csv — machine-readable concern-to-response mapping for tracking across revisionsTip. Before drafting your response, consider running /review-paper --peer --r2 <journal> on the revised manuscript first. It simulates the next referee round against your revisions — catching the "Resolved / Partial / Not addressed" classification mistakes before the real referee does. See .claude/skills/review-paper/SKILL.md.
/review-paper./slide-excellence (works on .tex manuscripts via the domain-reviewer agent).quality_reports/ if you want a permanent record alongside other quality reports.Before reporting completion: