review-pap
Run a 6-agent pre-submission review of a pre-analysis plan (PAP) for a specified registration target or journal
claesbackman · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add claesbackman/AI-research-feedback --skill review-papAbout this skill
name: review-pap description: Run a 6-agent pre-submission review of a pre-analysis plan (PAP) for a specified registration target or journal argument-hint: [optional: TARGET] [optional: path/to/pap.tex] allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent disable-model-invocation: true
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)
- Trial registries:
- If the first token of
$ARGUMENTSmatches 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
$ARGUMENTSas a file path and set the registration target totop-journal. - If
$ARGUMENTSis empty, set both to their defaults: no file path (auto-detect) and registration targettop-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:
- Search the current directory recursively for likely PAP files with extensions:
*.md,*.txt,*.tex,*.docx,*.pdf(exclude hidden folders,.git, build output, dependency directories). Also exclude previous review reports and AI-generated commentary:PAP_REVIEW_*.md,PRE_SUBMISSION_REVIEW_*.md,QUICK_REVIEW_*.md,GRANT_PROPOSAL_REVIEW_*.md,code_review_report*.md, and anything inside areviews/folder. These are outputs of earlier review runs, not PAP materials. - 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. - 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.
- 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
- 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
- Power/sample: files containing
- 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.
Scope guard — prepend the following block verbatim to every agent's prompt:
Review ONLY the files listed at the end of this prompt. Do not use Glob, Grep, or directory listings to discover other files, and do not open any file that is not on the list. In particular, ignore any previous review reports (
PAP_REVIEW_*.md,PRE_SUBMISSION_REVIEW_*.md,QUICK_REVIEW_*.md,GRANT_PROPOSAL_REVIEW_*.md,code_review_report*.md, anything in areviews/folder), referee feedback, response letters, notes, README files, and old drafts — none of these may influence your review. Within the listed files, treat commented-out text and\todo{}content as if they do not exist: review only the live text of the PAP.
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:
-
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.
-
Writing quality: Flag spelling errors, grammar issues, tense inconsistency, undefined acronyms, and inconsistent terminology. Note any section that sounds rushed or incomplete.
-
Structure and signposting: Check whether the PAP clearly states:
- the research