Respond To Referees

Step 5: Produce the Response Document

Write the output to quality_reports/response-to-referees_<paper-slug>.md or a path the user specifies (not the repo root: scripts/check-repo-hygiene.py rejects an unallowlisted root-level file once it is committed). Use the structure in templates/response-to-referees.md:

1. Header — journal, manuscript ID, revision round, date.
2. Cover paragraph — one paragraph thanking the editor and referees, summarizing the major changes at a high level.
3. Per-referee sections — for each referee, a numbered list of responses produced in Step 4.
4. Concern matrix — at the end, a single table summarizing every concern: ID, classification, promised action, affected files/exhibits, code-rerun status, passport status for any renumbered claim, and response location. This is the obligation ledger — nothing promised in the letter without a row, no row without its evidence trail.

Step 5.5: Post-Flight Verification (MANDATORY, CoVe)

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:

1. Extract revision-location claims — every "we added / we modified / we revised X (page Y, line Z / Section N)" assertion in the response document.
2. Generate verification questions — "Does the revised manuscript actually contain the revision claimed at page Y, line Z? Does it match the description?"
3. Spawn claim-verifier via the Agent tool with subagent_type=claim-verifier, in a fresh context — a named Agent call, not a conversation fork, which would inherit the draft. Hand it: the claims table, the verification questions, the path to the revised manuscript. Do NOT include the response draft.
4. Reconcile: PASS → attach green block. PARTIAL / FAIL → rewrite the affected response entries using the verifier's evidence. A response that says "we added robustness check X on page 34" when X is actually on page 27 (or not at all) is worse than a "Deferred" classification.

Downgrade to the classification the evidence supports:

• Claim verified at location → Addressed
• Claim verified at different location → update the location in the response
• Claim not verifiable in manuscript → downgrade to Partially addressed or Deferred with an honest rationale

Opt-out: --no-verify flag. Not recommended — the referee will run this check themselves.

Step 6: Warning Summary (MANDATORY)

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.

Output Files

• quality_reports/response-to-referees_<paper-slug>.md — the deliverable (structure from templates/response-to-referees.md)
• (Optional) quality_reports/response-to-referees-matrix_<paper-slug>.csv — machine-readable concern-to-response mapping for tracking across revisions

Pre-submission rehearsal

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

Cross-References

• For first-pass manuscript review before receiving referee comments, use /review-paper.
• For substantive content audits during revision, use /review-paper (or /seven-pass-review for a submission-ready draft) — /slide-excellence reviews lecture decks, not manuscripts.
• The response lives in quality_reports/ by default, alongside the other quality reports, as a permanent record.

Verification

Before reporting completion:

1. Confirm every concern has a classification (no orphans).
2. Confirm every "Addressed" or "Partially addressed" classification cites a specific page/section/line.
3. Confirm the warning summary was emitted (even if empty).
4. Confirm the cover paragraph names the journal and manuscript ID correctly.