Preregister

/preregister — Preregistration Document Generator

Produce a registry-ready preregistration document. The user uploads it to a real registry (OSF / AsPredicted / AEA RCT Registry) — this skill writes the prose and structure, it does not submit anywhere.

Why preregister

Preregistration is a written commitment to your hypotheses, design, and analysis plan before you see the data (or, for observational analyses, before you analyse the realised outcome). It separates confirmatory tests from exploratory tests and protects you from p-hacking, HARKing, and forking-paths. Different fields use different registries:

• Political science, psychology, broad social science → OSF (osf.io/registries) is the default. AsPredicted (aspredicted.org) is a popular short form for experiments.
• Economics field experiments → AEA RCT Registry (socialscienceregistry.org) is mandatory for AEA journal submission since 2018.
• Public health / clinical trials → ClinicalTrials.gov or ISRCTN (NOT covered by this skill — use the trial-registry's own template).

When to use

• Before launching an experiment (lab, field, or survey).
• Before collecting observational data on a target population for a specific RQ.
• Before analysing data you have access to but haven't yet examined for the focal hypothesis.
• During R&R when a referee asks for a written preanalysis plan.

When NOT to use

• After you've seen the realised outcomes and want to "preregister retrospectively" — that is not preregistration. The skill will refuse if the input description includes results.
• For exploratory analyses — those don't need preregistration; they need transparent labelling.
• For meta-analyses — use PROSPERO directly, not this template.

Workflow

PHASE 1 — Read inputs

Two input modes:

1. --input <path> — a research spec produced by /interview-me (saved under quality_reports/specs/) or any structured Markdown file. Read the spec and extract: research question, hypotheses (directional!), data source, design, sample, analysis approach. If the spec records a paper type (/interview-me writes it on a **Paper type:** line, e.g. survey-experiment), use it to bias the style choice.
2. No --input — prompt the user for a 1–3 paragraph description of the study, then proceed. If the description omits a directional hypothesis, ask once. Do not fabricate.

Refusal conditions (must be checked before any drafting):

• Description contains realised results ("we found", "the estimate is", "p =") → refuse with: "Preregistration is forward-looking; this description includes results. Did you mean /respond-to-referees or to write a methods section?"
• Description has no testable hypothesis at all (pure exploratory framing) → flag and ask whether the user wants the exploratory analysis version of the OSF template (still useful, but not a registered confirmatory test).

PHASE 2 — Pick the style

Default per field (used when --style is not given):

User can override with --style osf|aspredicted|aea-rct.

PHASE 3 — Generate the document

Read templates/preregistration-template.md. The template has three style sections; only use the section matching the chosen style (don't merge — registries differ).

Common to all styles, the document MUST include:

• Title and authors.
• Date and version.
• Pointer back to the source spec (if --input was given) so traceability survives.

Style-specific sections:

• osf — Hypotheses (directional, numbered) · Design · Sampling Plan · Variables · Analysis Plan · Inference Criteria · Data Exclusions · Missing Data Handling · Exploratory Analyses (clearly labelled as such) · Other.
• aspredicted — 9 numbered fields per the AsPredicted form: (1) data collection status, (2) hypothesis, (3) key dependent variable, (4) conditions, (5) analyses, (6) outliers/exclusions, (7) sample size + stopping rule, (8) anything else, (9) name (study not paper).
• aea-rct — Intervention · Outcomes (primary, secondary) · Primary hypotheses · Sample (target N, eligibility, randomization unit, randomization method) · IRB approval · Trial dates · Power calc · Pre-analysis plan attachment · Status (not yet on the air / ongoing / completed).

Annotate each section with one of:

• MUST — registry requires this; the document cannot be submitted without it.
• SHOULD — strongly recommended; reviewers expect it.
• MAY — optional; include if relevant.

Re-use the MUST/SHOULD/MAY framework from templates/requirements-spec.md. For each MUST that the input did not supply, write [CLARIFY: <specific question>] rather than fabricating content.

PHASE 4 — Cross-checks (before writing to disk)

Refuse to mark the document "ready" if any of these fails:

• Hypothesis directionality. Each hypothesis must contain a direction ("higher than", "increases", "negatively predicts", "no effect" is acceptable as a directional claim under equivalence-testing). Reject "is associated with" without a sign.
• Estimator named. Analysis plan names a specific estimator (OLS, logit, fixest::feols, lme4::lmer, ATT difference-in-means …) and a primary outcome variable. "Regression" alone is insufficient.
• Sample plan numeric. Target N, stopping rule, or power-calc target appear. "As many as possible" is not a sample plan. For RCTs and prospective designs, follow /power-analysis's SKILL.md (read it — the skill is user-invoked only, so it cannot be called from here) to produce the MDE / required-N and a ready-to-paste power paragraph for this field.
• Exclusions ex ante. Outlier and exclusion rules are stated before the data is seen ("we will exclude observations with completion time < 1 minute"). Vague "we'll deal with outliers" fails.
• Internal consistency. If the design is randomised, the unit of randomisation matches the unit of analysis OR the analysis plan addresses clustering. If observational, identification strategy is stated.

For each failure, the document gets a [CLARIFY: …] placeholder; the document is written to disk but flagged in the output summary as "INCOMPLETE — N MUST items unresolved".