review-pap

---

name: review-pap description: Run a 6-agent pre-submission review of a pre-analysis plan (PAP) for a specified registration target or journal

You are coordinating a rigorous pre-submission review of a pre-analysis plan (PAP). You will run 6 specialized review agents in parallel and consolidate their findings into a structured report.

Phase 1: Parse Arguments and Discover the PAP

Parse $ARGUMENTS as follows:

• The recognized registration targets are:
  • Trial registries: AEA, EGAP, OSF, ClinicalTrials, ISRCTN
  • Journal standards: AER, QJE, JPE, RESTUD, AEJ, JEEA
  • General standards: top-journal, working-paper
  • (case-insensitive; users can extend this list by editing this skill file)
• If the first token of $ARGUMENTS matches one of these names, treat it as the registration target and treat any remaining text as the main PAP file path.
• If no token matches, treat the entire $ARGUMENTS as a file path and set the registration target to top-journal.
• If $ARGUMENTS is empty, set both to their defaults: no file path (auto-detect) and registration target top-journal.
• If a file path is supplied but turns out to be missing, unreadable, or clearly not the main PAP, fall back to auto-detection and note that fallback in the report.

Store the resolved target as TARGET_REGISTRY for use in Agent 6 and the report header.

If a file path was provided, use it as the main PAP file. Otherwise, auto-detect:

1. Search the current directory recursively for likely PAP files with extensions: *.md, *.txt, *.tex, *.docx, *.pdf (exclude hidden folders, .git, build output, dependency directories).
2. Prioritize files whose names suggest they are the PAP, such as those containing pap, pre-analysis, preanalysis, pre_analysis, registration, analysis-plan, analysis_plan, study-plan.
3. Identify the main PAP document: the file that appears to contain the core analysis plan rather than only a protocol appendix, questionnaire, cover sheet, code appendix, or administrative attachment. If multiple candidates look plausible, prefer the one with hypotheses, outcomes, and analysis specifications.
4. Read the main PAP file and identify references to supporting documents:
   • Power calculations or sample-size worksheets
   • Survey instruments, questionnaires, or interview guides
   • Randomization protocols or sampling frames
   • Code skeletons, mock tables, or shells
   • Data dictionaries or codebooks
   • IRB/ethics protocols
5. Search recursively for likely supporting files and record them if present:
   • Power/sample: files containing power, sample_size, samplesize, mde
   • Instruments: files containing survey, questionnaire, instrument, endline, baseline
   • Randomization: files containing randomization, randomisation, strata, block
   • Code: files containing analysis, code, dofile, do_file, script, mock
   • Ethics: files containing irb, ethics, consent
6. Record:
   • Full path of the main PAP file and each supporting file with its likely role
   • Study title, PI(s)/team, and abstract or research question if available
   • Named registration registry, trial ID, or journal if any
   • Whether any expected supporting file categories were not found

If the PAP is in a binary format such as .pdf or .docx and the environment cannot read it directly, review what is accessible and note the limitation in the final report.

Phase 2: Launch 6 Review Agents in Parallel

In a single message, launch all 6 agents using the Agent tool with subagent_type: "general-purpose". Each agent reads the PAP materials independently. Pass the complete list of PAP and supporting file paths to each agent in its prompt. When constructing Agent 6's prompt, substitute the actual resolved value of TARGET_REGISTRY for every occurrence of TARGET_REGISTRY in that agent's prompt text.

---

AGENT 1 — Clarity, Writing Quality & Pre-specification Completeness

You are a PAP editor reviewing the document for clarity, precision, and pre-specification adequacy. Read all accessible PAP files and focus on the actual prose rather than markup or formatting commands.

What to check:

1. Clarity and readability: Identify sentences and paragraphs that are vague, overloaded with jargon, or too abstract for a reviewer to assess whether the plan is actually binding. Vagueness in a PAP is not just a writing problem — it creates loopholes for post-hoc flexibility.

2. Writing quality: Flag spelling errors, grammar issues, tense inconsistency, undefined acronyms, and inconsistent terminology. Note any section that sounds rushed or incomplete.

3. Structure and signposting: Check whether the PAP clearly states:

   • the research question(s) and hypotheses
   • the study design and setting
   • the primary and secondary outcomes
   • the analysis strategy for each outcome
   • the sample, sampling procedure, and timeline
   • pre-specified subgroup and heterogeneity analyses
   • decision rules for deviations from the plan

4. Pre-specification adequacy: For each hypothesis and analysis, ask: is this specific enough that a third party could reproduce the exact analysis without further decisions? Flag any element that would require judgment calls not resolved by the PAP:

   • outcome definitions that leave room for interpretation
   • analysis specifications that omit functional form, controls, fixed effects, or standard error clustering
   • subgroup criteria that are not operationally defined
   • ambiguous language such as "we will explore", "if appropriate", "as needed", or "we may"

5. Compliance signals: Check for common PAP failures:

   • no primary outcome clearly designated
   • multiple testing problem not addressed
   • no pre-specified rule for handling attrition, non-compliance, or missing data
   • no pre-specified decision rule for the main estimator
   • heterogeneity analyses promised but not operationalized
   • deviations-from-plan policy absent or vague

6. Overpromising: Flag PAPs that commit to analyses unlikely to be feasible or that promise more statistical power than the sample section supports.

Tag every individual issue with [CRITICAL], [MAJOR], or [MINOR] at the start of the line so the consolidation step can rank issues cleanly.

Output format:

## Agent 1: Clarity, Writing Quality & Pre-specification Completeness

### Critical Vagueness or Specification Gaps
[numbered list: Location | Vague element | Why it creates flexibility risk | Suggested tightening]

### Minor Writing Issues
[numbered list: Location | Issue | Suggested correction]

### Structural or Compliance Signals to Fix
[numbered list: Missing or weak element | Where it should appear | Recommended remedy]

The PAP files to review are: [LIST ALL FILE PATHS HERE]

---

AGENT 2 — Internal Consistency, Hypotheses & Outcomes

You are a technical reviewer checking whether the PAP is internally coherent: that the hypotheses, outcomes, sample, analysis plan, and any supporting materials are mutually consistent and operationally aligned.

What to check:

1. Hypotheses vs. outcomes consistency: For each stated hypothesis, verify that there is a clearly designated outcome variable that directly tests it. Flag hypotheses with no designated outcome, or outcomes with no corresponding hypothesis.

2. Primary vs. secondary outcome designation: Is there a clear primary outcome? Are secondary outcomes distinguished from exploratory ones? Are the multiple testing corrections (if any) consistent with how outcomes are designated?

3. Outcome definitions vs. data plan: For each outcome, verify that the PAP explains where the data come from, how the variable is constructed, and which survey item or administrative record corresponds to it.

4. Subgroup and heterogeneity consistency: For every subgroup or heterogeneity analysis claimed, check that the subgroup variable is defined and that it appears in the data collection or sampling plan.

5. Analysis plan vs. research design consistency: Do the estimators, identification assumptions, and standard error choices match the study design? For example: does an RCT analysis plan use an appropriate estimator (ITT, IV, LATE)?

6. Timeline consistency: If phases, waves, endlines, or rounds are mentioned in different sections, verify they match. Flag contradictions across the narrative, timeline, and data-collection plan.

7. Terminology consistency: Identify every key term — treatment arm name, outcome label, subgroup name, estimator name — and flag drift in naming or meaning across sections.

8. Cross-document consistency: If supporting documents (power calculations, instruments, randomization protocols) are referenced, verify they appear consistent with what the main PAP describes.

Tag every individual issue with [CRITICAL], [MAJOR], or [MINOR] at the start of the line.

Output format:

## Agent 2: Internal Consistency, Hypotheses & Outcomes

### Critical Inconsistencies
[numbered list: [Location 1] ↔ [Location 2] | What conflicts | Why it matters]

### Hypothesis or Outcome Coverage Gaps
[numbered list: Hypothesis/outcome | Missing operational support | Recommended fix]

### Terminology Drift
[numbered list: Term | How it varies | Recommended standardization]

### Minor Inconsistencies
[numbered list: same format as Critical]

The PAP files to review are: [LIST ALL FILE PATHS HERE]

---

AGENT 3 — Identification Strategy, Causal Claims & Contribution

You are a skeptical referee evaluating whether the proposed study can credibly answer the stated research question, whether the causal claims are justified by the design, and whether the contribution is meaningful.

What to check:

1. Research question clarity: Is there a precise, testable research question? Or is the question so broad that almost any result would answer it?

2. Identification strategy: What is the source of causal variation? Evaluate:

   • For RCTs: is randomization described with enough precision to assess validity? Is compliance, attrition, and spillover risk addressed?
   • For natural experiments / quasi-experiments: is the identification assumption stated? Is there a credible argument for why it holds?
   • For observational studies: are the selection-on-observables assumptions explicit and defended?

3. Testability of the hypotheses: Are the hypotheses falsifiable as stated? Could the study plausibly produce evidence against them? Flag hypotheses that are framed so that any result is consistent with the theory.

4. External validity and generalizability: Does the PAP address to whom and to what context the results will generalize? Are claims about broader applicability warranted by the study design?

5. Contribution to the literature: Does the PAP explain what existing evidence exists and what gap this study fills? Is the claimed contribution plausible given the research design?

6. Overclaiming and underclaiming:

   • Overclaiming: causal language that exceeds what the design supports; importance claims that exceed the scope of the study
   • Underclaiming: strong features of the design that are not clearly articulated

7. Fit to TARGET_REGISTRY expectations: Based on the study design and named TARGET_REGISTRY, assess whether the PAP meets likely registration or journal standards for rigor, scope, and relevance. Flag design choices that are likely to receive critical scrutiny.

Tag every individual issue with [CRITICAL], [MAJOR], or [MINOR] at the start of the line.

Output format:

## Agent 3: Identification Strategy, Causal Claims & Contribution

### Major Identification or Design Problems
[numbered list: Location | Issue | Why it undermines the study | Fix]

### Overclaiming
[numbered list: Quoted or paraphrased claim | Why it ov