review-paper

name	review-paper
description	Substantive referee-style review for academic manuscripts.

Manuscript Review

Produce a thorough, constructive review of an academic manuscript — the kind of report a top-journal referee would write.

Input: $ARGUMENTS — path to a paper (.tex, .pdf, .qmd), or a filename in manuscripts/ or references/papers/.

---

Steps

1. Locate the manuscript. Check:

   • direct path from $ARGUMENTS
   • manuscripts/$ARGUMENTS
   • references/papers/$ARGUMENTS
   • partial matches in manuscripts/ and references/papers/
   • If multiple plausible matches remain and there are 2-3 clear candidates, use request_user_input in Plan mode for a single-choice prompt; otherwise ask conversationally.
     • header: "Manuscript"
     • question: "Which manuscript should I review?"
     • options: one option per candidate with filename as the label and the path as the description

2. Run the fresh-eyes pass first. Read agents/fresh-eyes-reviewer.md, then apply that protocol using only the manuscript. Do not read the project spec, lit review, or analysis scripts before completing the fresh-eyes notes.

3. Read the manuscript in full end-to-end.

4. Read review context after the fresh-eyes pass:

   • references/domain-profile.md for field and venue calibration
   • the most relevant project spec in quality_reports/specs/ if one exists

5. Apply the substantive and adversarial lenses.

   • Read agents/domain-reviewer.md and use it for the deep substance review across all 6 lenses.
   • The substantive review must include Lens 6, the Design-Specific Diagnostics Audit: check whether the paper reports the standard numerical diagnostics demanded by its design (for example, pre-trends evidence for DiD, first-stage F for IV, density and bandwidth checks for RDD).
   • Read agents/adversarial-reviewer.md and use it for the hostile-referee attack.
   • If the user explicitly requested delegated or parallel reviewer work, you may run those reviewer roles as separate subagents and merge the outputs. Otherwise apply the protocols inline.

6. Evaluate writing quality and presentation directly. The skill owns these dimensions even when other reviewer lenses are delegated.

7. Merge all findings into one unified report. Create quality_reports/ if it is missing, then save to quality_reports/paper_review_[sanitized_name].md.

---

Review Dimensions

1. Argument Structure

• Is the research question clearly stated?
• Does the introduction motivate the question effectively?
• Is the logical flow sound (question -> method -> results -> conclusion)?
• Are the conclusions supported by the evidence?
• Are limitations acknowledged?

2. Identification Strategy

• Is the causal claim credible?
• What are the key identifying assumptions? Are they stated explicitly?
• Are there threats to identification (omitted variables, reverse causality, measurement error)?
• Are robustness checks adequate?
• Is the estimator appropriate for the research design?

3. Econometric Specification

• Correct standard errors (clustered? robust? bootstrap?)?
• Appropriate functional form?
• Sample selection issues?
• Multiple testing concerns?
• Are point estimates economically meaningful (not just statistically significant)?

4. Literature Positioning

• Are the key papers cited?
• Is prior work characterized accurately?
• Is the contribution clearly differentiated from existing work?
• Any missing citations that a referee would flag?

5. Writing Quality

• Clarity and concision
• Academic tone
• Consistent notation throughout
• Abstract effectively summarizes the paper
• Tables and figures are self-contained (clear labels, notes, sources)

6. Presentation

• Are tables and figures well-designed?
• Is notation consistent throughout?
• Are there typos, grammatical errors, or formatting issues?
• Is the paper the right length for the contribution?

---

Merge Guidance

Use the reviewer lenses this way:

• Fresh Eyes Read — summarize the five fresh-eyes passes plus the top three clarity issues and the top three things that landed.
• Major Concerns — put Lens 6 CRITICAL missing-diagnostic findings first, then combine other domain-reviewer MAJOR/CRITICAL findings, adversarial fatal flaws, and your writing/presentation findings.
• Minor Concerns — combine domain-reviewer MINOR findings with surface-level issues that are worth fixing.
• Referee Objections — take these primarily from the adversarial lens: fatal flaw, over-claims, alternative explanations, and weakest-link identification concerns.
• What a Desk Editor Might Say — include the adversarial two-paragraph rejection letter.

---

Output Format

# Manuscript Review: [Paper Title]

**Date:** [YYYY-MM-DD]
**Reviewer:** review-paper skill
**File:** [path to manuscript]

## Summary Assessment

**Overall recommendation:** [Strong Accept / Accept / Revise & Resubmit / Reject]

[2-3 paragraph summary: main contribution, strengths, and key concerns]

## Fresh Eyes Read

*How the paper lands on a first-time reader.*

**After title + abstract — one-sentence takeaway:** ...
**After intro — what reader expects:** ...
**Main display standalone?** [Yes / Partially / No — what's missing]
**What stays with the reader:** ...

### Top 3 Clarity Issues
1. [issue with location]
2. ...
3. ...

### Top 3 Things That Landed
1. ...
2. ...
3. ...

## Strengths

1. [Strength 1]
2. [Strength 2]
3. [Strength 3]

## Major Concerns

### MC1: [Title]
- **Source:** [fresh-eyes / domain / adversarial / writing / presentation]
- **Dimension:** [Identification / Econometrics / Design Diagnostics / Argument / Literature / Writing / Presentation / Fatal Flaw]
- **Issue:** [Specific description]
- **Suggestion:** [How to address it]
- **Location:** [Section/page/table if applicable]

[Repeat for each major concern. Lens 6 CRITICAL missing-diagnostic and fatal items should appear first.]

## Minor Concerns

### mc1: [Title]
- **Issue:** [Description]
- **Suggestion:** [Fix]

[Repeat]

## Referee Objections

*These are the tough questions a top referee would likely raise.*

### RO1: [Question]
**Why it matters:** [Why this could be fatal]
**How to address it:** [Suggested response or additional analysis]

[Repeat for 4-6 objections]

## What a Desk Editor Might Say

[Two-paragraph rejection letter. First paragraph: summary plus acknowledged strength. Second paragraph: concrete reason for rejection and what would have to change.]

## Specific Comments

[Line-by-line or section-by-section comments, if any]

## Summary Statistics

| Dimension | Rating (1-5) |
|-----------|-------------|
| Argument Structure | [N] |
| Identification | [N] |
| Econometrics | [N] |
| Literature | [N] |
| Writing | [N] |
| Presentation | [N] |
| Design diagnostics | [N] |
| First-read clarity | [N] |
| Adversarial robustness | [N] |
| **Overall** | **[N]** |

---

Principles

• Be constructive. Every criticism should come with a suggestion.
• Be specific. Reference exact sections, equations, and tables.
• Calibrate to the field's top journals. Use references/domain-profile.md to set the bar.
• Distinguish fatal flaws from minor issues. Not everything is equally important.
• Acknowledge what works. Good research deserves recognition.
• Do NOT fabricate details. If you cannot verify a section or claim, say so.