Responding to reviewers

From letter to atomic requests

Import the decision letter and it is stored exactly as it arrived, with its sha256; nothing ever rewrites it. Each reviewer's comments are separated on their headings, and each comment is decomposed into the separate things it asks for — “add a confidence interval” and “report the absolute risk difference” are two requests, not one — with a kind (a text change, an analysis to run, data or code to supply, something to state, a citation, or a request you may reasonably decline) and the section or table it points at. Every request's text is a span of the reviewer's own words. Your connected agent can re-kind or re-split a comment; it cannot put its own words in one.

Deciding, not drafting

• There is no box to write the reply in. You record a disposition for each request — changed, will change, disagree, out of scope or deferred — with your reason, and (for “changed”) the tracked changes that made it. The sentences the reviewer reads are composed from that.
• A change addressed to a reviewer request is made with the REVIEWER_REVISION mode, which records the request ids it answers. That record is what lets the letter attribute the change to the point; an edit made at the same time but naming nothing cannot answer it.
• Only a signed-in person may record a disposition: answering a reviewer is a scientific decision about their objection. A connected agent may propose one, and the proposal is stored beside your record, never over it.
• A disagreement is a legitimate answer and needs no change — but it must state the scientific reason, and a blank reason is refused. A silent refusal is not an option the product offers.

Composing the letter

• Compile the response against the release candidate you intend to send. Each point that claims a change is checked against that candidate's frozen document: the change set must be accepted, must name this request, and must be found in the document — by the edited block's hash, by the inserted text, or as an unresolved tracked insertion.
• Locations — “page 4, lines 12–18” — are read from the candidate's own PDF render, never typed. Where a passage could not be matched in the text layer the letter says so instead of printing a number, and the numbers are of Hikma's render, not of the journal's own pagination.
• An analysis is claimed only where the run succeeded, and the run is named.
• A claim the candidate does not carry is printed unresolved with the reason and fails the check RESPONSE_UNBACKED, which refuses the submission package. There is no waiver for it: it is about a sentence addressed to somebody else.

Four separate channels

• Manuscript — the clean current text. It never says that a passage was added or clarified for a reviewer; the REVISION_LANGUAGE check fails a release that does.
• Tracked view — the same document rendered with the changes shown. A projection, not a second document.
• Response letter — composed from records, as above.
• Revision ledger — the change sets with the mode each declared and the requests each names.
• Editorial annotation — comment threads in the manuscript, which are part of neither the manuscript nor the letter.

Export

The compiled letter as DOCX or Markdown. The submission package carries both, plus the reviewers' letter verbatim, and the checklist names every file with its sha256 and says how many points the response answers with a change.