Skip to content

scdenney/open-science-skills / codex/referee-response

referee-response

Verified

Organize an author's response to peer review: extract every referee point, order the revision by dependency, flag possible pushbacks, and build the response-letter skeleton the author fills in. Use for revise-and-resubmit planning, response letters, or checking every point was answered.

Referee Response

Turns scattered reviewer comments into an ordered revision plan and a response letter the author fills in. The author writes every substantive answer, including the interpretation of a result and the reason a request is declined; this skill makes sure each point is found, ordered, answered somewhere, and formatted the way editors expect.

Related skills. $journal-review writes a referee report for someone else's manuscript; this skill answers one written about yours. $sci-edit polishes the letter's prose after the author has written the answers. $paper-review-lite and $citation-check are useful before resubmission when a referee's point implies the manuscript needs a fresh audit.

Inputs

One or more referee reports, the editor's decision letter if available, and the manuscript (current draft, and the submitted version if the two differ). If a report is a PDF or Word file, read it with $doc-to-markdown first. Ask once for anything missing that the steps below need; do not guess at a report's content.

Modes

Infer from the request; an argument forces it.

  • plan (default when no letter exists yet): steps 1–3.
  • letter: steps 1–4, producing the letter skeleton.
  • check: step 5 over a letter the author has filled in.

Step 1 — Extract every point

List every distinct request, criticism, or question across all reports and the editor's letter. One row per point, even when a referee bundles several into one paragraph. For each point record:

  • referee (R1, R2, editor), and the location in the report;
  • the point, quoted or closely paraphrased so the author can find it;
  • severity: blocking (the editor or a referee makes acceptance conditional on it), major, minor, optional (a suggestion the author may decline);
  • type: analysis, design, framing, writing, citation, data or code, presentation;
  • whether another referee raises the same point, agrees, or conflicts with it.

Count the points and tell the author the count per referee. A missed point is the commonest reason a resubmission fails, so the list is the deliverable of this step, not a summary of it.

Step 2 — Map dependencies and order the revision

Order the points so upstream changes come first: a new specification before the discussion that interprets it; a reframing before the sections that rest on it; a data correction before every number that depends on it. Group into a sequence (do first → depends on). Flag conflicts between referees as editor-judgment calls and say what each resolution would cost.

For each point in order: the change implied, the manuscript sections and files it touches, whether it needs new analysis, and a rough effort estimate. Where a point would distort the manuscript's argument if taken literally, say so.

Step 3 — Flag the pushbacks, as questions

Not every request should be accepted. Mark the points where a reasoned decline is defensible (the request contradicts the pre-registration, rests on a misreading, asks for an analysis the design cannot support, or would trade a confirmatory claim for an exploratory one) and give the reason. Put each to the author as a question; the decision is theirs. Do not write the decline itself.

Step 4 — Build the letter skeleton

The standard shape editors expect:

  1. Cover note to the editor. Thanks, a two-sentence summary of the main changes, and a pointer to the point-by-point response. Leave the summary as [AUTHOR: two sentences on the main changes].

  2. General response (optional): a short paragraph for changes that cut across several points. Placeholder.

  3. One section per referee, in the order the editor listed them. Within each, every point from step 1 in the referee's own order, as a numbered table or numbered blocks:

    #Reviewer commentResponseWhere in the manuscript
    R1.1quoted or paraphrased point[AUTHOR: …][section / page / line]

    Keep the reviewer's wording in the comment column so the referee recognizes the point. Pre-fill the response column only with the kind of response the plan implies ([AUTHOR: describe the new robustness table], [AUTHOR: reasoned decline, see step 3]), never with content. Where the same point appears under two referees, cross-reference rather than duplicate.

  4. Editor's points, if the letter contains any beyond the referees'.

Write the skeleton to response_to_reviewers.md beside the manuscript unless the author names another path. State how many placeholders it contains.

Step 5 — Check the filled letter

Once the author has written the responses:

  • Every point from step 1 has a non-placeholder response; list any that do not.
  • Every manuscript location cited in the letter exists in the current draft (section headings, table and figure numbers, page ranges); list any that do not resolve.
  • Every response that claims a change names where the change is; every reasoned decline gives a reason.
  • Tone: responses are courteous and specific, never defensive; flag sentences that argue with the referee rather than answer them, and leave the rewording to the author or to $sci-edit.
  • Conflicting referees: the letter says which way the author went and why.

Report the checks as a short list of what passed and what needs the author's attention.

Notes

  • Heritage: grown from a personal referee-response skill (2026-05) into a library skill on 2026-09-02.
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall