respond-to-referee

name	respond-to-referee
description	Structure point-by-point referee responses for the sewage-house-prices paper. Classifies each comment (NEW ANALYSIS / CLARIFICATION / REWRITE / DISAGREE / MINOR), produces a tracking document, drafts a response letter in LaTeX, and flags items needing new analysis or user judgment. This skill should be used when asked to "respond to referees", "draft revision", "address referee comments", or "R&R".
argument-hint	[referee report file path]
allowed-tools	["Read","Grep","Glob","Write","Edit","Agent"]

Respond to Referee

Structure a point-by-point response to referee reports for the sewage-house-prices manuscript.

Input: $ARGUMENTS — path to referee report file(s).

---

Project-Specific Context

Manuscript

• Main document: docs/overleaf/_main.tex
• Sections: docs/overleaf/*.tex
• Bibliography: docs/overleaf/refs.bib

Analysis

• Scripts: scripts/R/09_analysis/
• Tables: output/tables/
• Figures: output/figures/

Common Referee Concerns for This Paper

• Short EDM panel (2021-2024) — limited time variation
• LSOA FE may not capture neighbourhood-level sorting
• Spill count vs hours as treatment — which matters more?
• External validity beyond England
• Dry spill identification — rainfall threshold sensitivity
• Multiple testing across 6 radii and multiple specifications

---

Workflow

Step 1: Parse Inputs

1. Read referee report(s) from $ARGUMENTS
2. Read the manuscript (docs/overleaf/_main.tex and section files)
3. Scan existing analysis scripts to know what already exists

Step 2: Classify Every Comment

Assign each referee point a classification:

Class	Action
NEW ANALYSIS	Flag for user — requires new R script or specification
CLARIFICATION	Draft revised text for the relevant section
REWRITE	Draft structural revision of a section
DISAGREE	Draft diplomatic pushback — flag for user review (mandatory)
MINOR	Draft fix directly (typos, formatting, minor edits)

Step 3: Build Tracking Document

Save to output/log/referee_response_tracker.md:

# Referee Response Tracker
**Date:** YYYY-MM-DD
**Journal:** [if known]
**Decision:** [R&R / Major / Minor]

## Summary
- Referee 1: N comments (X new analysis, Y clarification, Z disagree, W minor)
- Referee 2: N comments (...)
- Editor: N comments (...)
- **Total new analyses required:** X

## Action Items (Priority Order)

### HIGH: New Analysis Required
| # | Ref | Point | Status |
|---|-----|-------|--------|
| 1 | R1.3 | [Brief] | TODO |

### MEDIUM: Clarification / Rewriting
| # | Ref | Point | Status |
|---|-----|-------|--------|
| 1 | R1.1 | [Brief] | TODO |

### FLAGGED: Disagreements (require user review)
| # | Ref | Point | Draft Response |
|---|-----|-------|---------------|
| 1 | R2.5 | [Brief] | [Draft] |

### LOW: Minor Edits
- [ ] R1.7: Fix typo on p. 12

Step 4: Draft Response Letter

Generate LaTeX response letter:

\documentclass[12pt]{article}
\usepackage[margin=1in]{geometry}
\usepackage{xcolor}
\definecolor{response}{RGB}{0,0,128}

\begin{document}

\title{Response to Referee Reports: Sewage in Our Waters}
\author{[Authors]}
\date{\today}
\maketitle

Dear Editor,

We thank the editor and referees for their careful and constructive comments.
We have revised the manuscript to address all points raised.

\bigskip

\textbf{Summary of major changes:}
\begin{enumerate}
\item [Major change 1 — addresses R1.3, R2.1]
\item [Major change 2 — addresses R1.5]
\end{enumerate}

\newpage
\section*{Response to Referee 1}

\subsection*{Comment 1.1}
\textit{[Exact quote of referee comment]}

\medskip
\textcolor{response}{%
\textbf{Response:} [Draft response]

\textbf{Paper change:} [Section X, page Y]
}

\end{document}

Save to output/log/referee_response_[date].tex.

Step 5: Diplomatic Disagreement Protocol

When classification is DISAGREE:

1. Open with acknowledgment of the referee's point
2. Provide specific evidence (data, results, published work)
3. Offer partial concession where possible
4. Never say: "The referee is wrong" or "misunderstood"
5. Instead say: "We respectfully note...", "Upon reflection, we believe..."
6. FLAG prominently for user review

---

Principles

• The response letter is the authors' voice. Match their academic tone.
• Never fabricate results. Mark NEW ANALYSIS items as TBD until implemented.
• Flag all DISAGREE items. These need human judgment — never resolve disagreements autonomously.
• Prioritize editor's comments. The editor signals which concerns matter most.
• Track everything. Every referee comment appears in both tracker and response letter.