experiment-design

name	experiment-design
description	Design empirical studies through power analysis, pre-analysis planning, QSF parsing, and survey architecture. Use when specifying sampling, measurement, treatment, or analysis before data collection. Not for causal identification alone; use $causal-design.
allowed-tools	Bash(uv*, Rscript*, R*, mkdir*, ls*), Read, Write, Edit, Glob, Grep, AskUserQuestion
argument-hint	[--mode power|design|pap|survey] [qsf-file or project-path]

Experiment Design

Interview-driven design workflow producing design documents, power analysis scripts, and pre-analysis plans.

Modes

Mode	What it produces	Entry point
Power	Power analysis script + sample size table	"How many participants do I need?"
Design	Full design document (hypotheses, conditions, measures, randomization)	"Design my experiment"
PAP	Pre-analysis plan (AEA/OSF/EGAP format)	"Write a PAP"
Survey	Structured survey specification from natural language or QSF	"Build a survey" / "Parse my Qualtrics"

Default: Design. If user provides a .qsf file, auto-select Survey mode.

When to Use

• Designing a new experiment or survey
• Calculating required sample sizes
• Writing or auditing a pre-analysis plan
• Parsing a Qualtrics .qsf file to understand its structure
• Building a survey specification from a natural language description

When NOT to Use

• Running the analysis → data-analysis
• Auditing identification strategy for observational studies → causal-design
• Generating synthetic test data → synthetic-data

Shared References

• Method probing questions: shared/method-probing-questions.md — ask before designing (Experiments/RCTs, Survey sections)
• Validation tiers: shared/validation-tiers.md — tier determines required power and pre-registration
• Escalation protocol: shared/escalation-protocol.md — escalate when design has validity threats
• Engagement-stratified sampling: shared/engagement-stratified-sampling.md — stratify social media samples by engagement
• Inter-coder reliability: shared/intercoder-reliability.md — reliability planning for content analysis designs

---

Mode: Power

Read references/power-analysis-recipes.md for language-specific code patterns.

Workflow

1. Interview — ask for:
   • Primary outcome variable and expected effect size (or domain norms)
   • Design type (between-subjects, within-subjects, factorial, cluster-randomized)
   • Number of conditions/groups
   • Significance level (default: 0.05) and desired power (default: 0.80)
   • Any clustering or stratification
2. Generate script — R (DeclareDesign/pwr) or Python (statsmodels.stats.power)
3. Execute and report — produce a sample size table showing N for power = {0.80, 0.90, 0.95}
4. Write to project — save script to code/power_analysis.R (or .py), results to output/power_analysis_results.md

HPC escalation: If the power analysis uses Monte Carlo simulation (e.g., DeclareDesign with >10k replications, or a multi-design sweep), move execution to [HPC cluster] — drop the simulation script into hpc/ with templates/slurm/array.sbatch (array over seeds/designs). The SHA-logging snippet in the template pins results to the DGP version. See docs/guides/hpc.md.

Effect Size Guidance

If the user doesn't know the expected effect size, guide them:

Source	How to use
Prior literature	"What did similar studies find?"
Pilot data	Calculate from pilot descriptives
SESOI	"What's the smallest effect worth detecting?"
Domain norms	Cohen's benchmarks as absolute last resort (small=0.2, medium=0.5, large=0.8 for d)

Never default to Cohen's benchmarks without acknowledging they are arbitrary.

---

Mode: Design

Workflow

1. Research question interview — structured questions:
   • What is the causal question?
   • What is the treatment / intervention?
   • What is the primary outcome? Secondary outcomes?
   • What is the target population?
   • What is the assignment mechanism? (random, stratified, clustered, matched)
2. Design specification — produce a structured document covering:
   • Hypotheses (directional, with expected signs)
   • Conditions (treatment arms, control)
   • Randomization procedure
   • Outcome measures and scales
   • Sample and recruitment strategy
   • Timeline
3. Identification check — state the estimand, identifying assumptions, and potential threats
4. Write design document — save to docs/experiment-design.md or project-appropriate location
5. Lock the design — record in MEMORY.md Estimand Registry (if project has one) or flag for the user to lock before analysis

This design document is what data-analysis Phase 3 checks for before allowing estimation.

---

Mode: PAP

Read references/pap-template.md for the full template structure.

Workflow

1. Check for existing design — look for design document in docs/, log/plans/, or .context/
2. If no design exists — run Design mode first, then continue
3. Generate PAP — structured pre-analysis plan following AEA/OSF/EGAP conventions:
   • Study information (title, authors, IRB, registration)
   • Design overview (hypotheses, conditions, randomization, sample)
   • Data collection (instruments, timing, blinding)
   • Analysis plan (main specification, inference, multiple testing corrections)
   • Robustness and sensitivity analyses
   • Power analysis (reference or embed results from Power mode)
4. Output — save to docs/pre-analysis-plan.md (or .tex if user prefers LaTeX)
5. Registration prompt — remind user to register at AEA RCT Registry, OSF, or EGAP

---

Mode: Survey

Survey mode is a first-class capability with two entry points: QSF parsing and natural language construction.

Entry Point A: QSF Parsing

When user provides a Qualtrics .qsf file:

1. Parse the JSON — extract survey flow, blocks, questions, embedded data, skip logic
2. Map question types — read references/qsf-parsing-guide.md for type mapping:
   • Matrix, Likert, slider, numeric, constant sum, rank order, best-worst scaling
   • Text entry (single-line, multi-line, essay)
   • Multiple choice (single answer, multiple answer)
3. Detect design elements:
   • Factorial conditions from randomizer blocks and embedded data
   • Attention checks and comprehension checks
   • Known validated scales (read references/known-scales-registry.md)
   • Skip/display logic and branching
4. Produce structured summary — questions, conditions, scales, logic flow, warnings
5. Flag issues — missing attention checks, unbalanced conditions, potential order effects

Entry Point B: Natural Language Construction

When user describes an experiment in natural language:

1. Parse the design — extract factorial structure from text
   • Example: "3 (Source: AI vs Human vs None) x 2 (Product: Hedonic vs Utilitarian)" → 3x2 between-subjects
2. Interview for details:
   • What DVs to measure? (recommend appropriate scale types)
   • What manipulation checks?
   • What attention/comprehension checks?
   • Demographics and control variables?
3. Generate survey specification — structured document with:
   • Survey flow (consent → demographics → manipulation → DVs → manipulation check → debrief)
   • Question text and response options for each item
   • Condition assignments and randomization logic
   • Attention check placement (read references/survey-design-checklist.md)
4. Scale recommendations — read references/known-scales-registry.md for validated scales matching the constructs

Survey Quality Checks

Read references/survey-design-checklist.md for the full checklist. Key checks:

• Attention checks: At least 1 per 5 minutes of survey length. Calibrated pass rates (85-95%). See Krosnick (1991), Meade & Craig (2012).
• Response style mitigation: Flag scales vulnerable to acquiescence bias. Recommend reverse-coding for scales with 4+ items in the same direction.
• Scale quality: Semantic type detection (satisfaction, trust, intention, risk). Reverse-coded item flagging. Well-known scale recognition.
• Order effects: Randomize question order within blocks where appropriate. Flag potential priming from early questions.

---

Cross-References

Resource	When read
references/power-analysis-recipes.md	Power mode
references/pap-template.md	PAP mode
references/survey-design-checklist.md	Survey mode (quality checks)
references/identification-strategies.md	Design mode (identification check)
references/qsf-parsing-guide.md	Survey mode (QSF parsing)
references/known-scales-registry.md	Survey mode (scale recognition)
design-before-results rule	Design + PAP modes produce the locked design
data-analysis skill	Consumes the design document
causal-design skill	For observational identification (not experiments)
synthetic-data skill	For generating pilot data