| name | peer-review |
| description | Run a full simulated peer review — dispatch the peer-reviewer and integrity-reviewer agents over the manuscript, dedupe their findings, and produce a referee report with a recommendation. Pre-empt Reviewer 2 before submission |
| user-invocable | true |
Peer Review
Core Rule
Simulate the referee you fear, before the journal assigns one. This skill runs an adversarial, evidence-bound review: it surfaces what a skeptical reviewer would attack — overclaim, unsupported assertions, scope creep, methods gaps, statistical sins — and produces a referee report you can act on. The review reports; it does not silently edit the manuscript. Fixes that touch the thesis, a quantity, methods, or an argument-carrying citation are Protected Claims (CLAUDE.md) and need author sign-off.
The reviewers are bound by the same cardinal rule as the writer: a critique must point at real text and a real problem. No invented weaknesses, no citations the reviewer "expects to see" that don't exist as a demand — every issue cites a section/line.
When to Use
Invoke with /peer-review when:
- A draft is complete and you want a referee report before submission.
- A major section (Discussion, Methods) is settled and you want it stress-tested.
- You are deciding readiness for a target venue (pair with
/journal-fit).
- A reviser wants to know which Reviewer-2 objections are still open.
Scope it: /peer-review for the whole manuscript, or /peer-review sections/methods.tex for one section.
Process
Phase 1: Load the Manuscript and Its Contract
- Read
MANUSCRIPT_MAP.md — Thesis, Contribution, Audience, target venue, Key sources, "Claims that need extra care," and the Structure table. The review judges the manuscript against its own stated thesis and scope — a reviewer's first question is "did they deliver what they claimed?"
- Read the manuscript — every section file in the Structure table (or the scoped file).
- Read
tasks/reviews/_index.md → ## Top Rules — recurring prior critiques. If a reviewer already flagged "you overclaim in the discussion," check it has been addressed; an unfixed Top Rule is a Major issue.
- Note the field overlay in
agent_docs/field/ if one exists — discipline-specific reporting standards the reviewer will hold you to.
Phase 2: Dispatch the Reviewer Agents
Run two specialist agents in parallel — they read the manuscript independently and return findings:
-
peer-reviewer agent — the scholarly referee. Judges:
- Significance & novelty — is the contribution real and clearly distinguished from prior work?
- Soundness — do the methods support the claims? Is the analysis appropriate?
- Claim calibration — does every results/discussion sentence stay within what the evidence licenses? (verb + quantifier + scope)
- Clarity & structure — does each section establish the one claim it owes (
MANUSCRIPT_MAP → Structure)?
- Statistics — effect size + uncertainty reported, not just significance; N, test, and assumptions stated (
agent_docs/statistics.md).
-
integrity-reviewer agent — the research-integrity referee. Judges:
- Sourcing — every substantive claim is cited, the author's own, or common knowledge; no UNSUPPORTED assertions.
- No fabrication — no invented-looking citation, DOI, quantity, or quote; placeholders (
[CITE], [VALUE — verify]) surfaced, not hidden.
- Quote fidelity — quotations verbatim with locators.
- Reproducibility — data/code availability stated; methods sufficient to reproduce (
agent_docs/reproducibility.md).
- Scope honesty — generalization claims match the tested population/matrix.
If the agents are unavailable in this environment, run both review lenses yourself sequentially — but keep them as separate passes (scholarly soundness vs integrity), because they catch different failures.
Phase 3: Dedupe and Triage
The two agents will overlap (an overclaim is both a soundness and an integrity issue). Merge:
- Collapse duplicates — same sentence flagged by both → one issue, noting both lenses.
- Classify severity:
- Major — threatens a central claim, the contribution, soundness, or integrity. Would justify "major revision" or rejection. (Unsupported thesis-level claim, methods that don't support the result, fabrication risk, unaddressed prior Top Rule.)
- Minor — does not threaten the conclusion but should be fixed. (Local overclaim, a missing cite on a secondary claim, an undefined cross-reference, a clarity issue.)
- Order by impact — Major issues first, most central first. A reviewer leads with the objection that decides the paper.
Phase 4: Write the Referee Report
Produce a report in the shape a journal referee submits: a Summary that proves you understood the contribution, then Major and Minor issues, then a recommendation. Keep the reviewer's professional, specific voice — every point names a location and states the fix or the question.
Phase 5: Hand Off, Do Not Auto-Fix
End with a checklist of edits the author can apply. Do not apply them in this skill. Surface Protected Claims explicitly (thesis/quantity/methods/argument-citation changes) so the author decides. Offer to run /claim-check on flagged overclaims and /citation-audit on flagged bibliography issues as the follow-up.
Output Format
# Referee Report — <manuscript title> (simulated)
## Summary (reviewer's understanding)
This manuscript argues <thesis, in the reviewer's words>. The contribution is
<X>, established via <method>. [2–4 sentences showing the contribution was understood.]
## Recommendation
Major revision (Major: 3, Minor: 6)
## Major Issues
1. **[Soundness]** §Discussion ¶3 (discussion.tex:41): The claim "the gate causes
higher tool-call accuracy across task settings" is causal and general, but the
design tests one agent harness and shows association. The conclusion overreaches
the evidence.
→ Restrict to the tested harness and to associational language, or supply the
comparison/identification that licenses the stronger claim. (Protected: verb +
scope change on the central claim.)
2. **[Integrity]** §Results (results.tex:62): "23% baseline hallucination rate" carries
no citation and is not in the data. UNSUPPORTED. → Cite the source or flag
[CITE]; do not assert it bare.
3. **[Prior Top Rule]** tasks/reviews flagged overclaim in the discussion before;
§Discussion ¶5 repeats the pattern. → Apply the existing rule.
## Minor Issues
1. **[Statistics]** §Results: p-values reported without effect sizes or CIs. Add both.
2. **[Clarity]** §Intro ¶2: the gap is stated twice; the contribution once. Invert.
3. **[Cross-ref]** discussion.tex:40: \ref{fig:horizon} has no \label.
4. **[Terminology]** "tool-call accuracy" and "success rate" used interchangeably — lock one (MANUSCRIPT_MAP → Terminology).
5. **[Sourcing]** §Intro: "widely reported" needs at least one cite or reframing.
6. **[Reproducibility]** No data-availability statement.
## Edit Checklist (for the author — not auto-applied)
- [ ] Discussion ¶3: calibrate verb + scope (PROTECTED — confirm)
- [ ] Results: resolve [CITE] on baseline hallucination rate
- [ ] Results: add effect sizes + CIs
- [ ] Fix \ref{fig:horizon}
- [ ] Add data-availability statement
- [ ] Lock terminology to "tool-call accuracy"
## Suggested follow-ups
- /claim-check sections/discussion.tex (the overclaim cluster)
- /citation-audit (sourcing + cross-ref issues)
Pairs With
peer-reviewer agent + integrity-reviewer agent — the two lenses this skill orchestrates (Phase 2). Defined in .claude/agents/; methodology in agent_docs/peer-review.md./claim-check — the targeted follow-up for flagged overclaims (verb/quantifier verification against sources)./citation-audit — the follow-up for flagged bibliography/cross-reference issues./journal-fit — run alongside when the question is also "is this the right venue?"tasks/reviews/ — recurring critiques live here; an unaddressed Top Rule is automatically a Major issue.
Common Rationalizations
| Rationalization | Reality |
|---|
| "My co-authors already read it" | Co-authors share your blind spots and your investment. Simulate the hostile stranger. |
| "Reviewer 2 is just mean" | Reviewer 2 is reading adversarially — which is the correct way to read your strongest claims. Pre-empt them. |
| "These are nitpicks" | A pile of minor issues reads as carelessness and primes the referee to doubt the major claims too. |
| "Let the journal find the problems" | The journal finding them costs you a rejection or a revision cycle. Find them now. |
| "Just fix the issues for me" | Fixes to the thesis/quantities/methods/argument-citations are Protected — they need the author, not the agent. |
Notes
- Reviewing is judgment-heavy — run on the Reasoner model (
CLAUDE.md → Model Selection).
- Feed the outcome back: a critique you keep receiving is a rule. Log it to
tasks/reviews/ and promote to Top Rules if it recurs.
- This is a simulation — it pre-empts likely objections; it does not guarantee acceptance. Its job is to leave Reviewer 2 with less to say.
