empirica-experiment-spec

When a researcher describes an experiment, do this before writing code:

Runtime command policy for this repo:

• •Do not use npm run build/npm test to validate the Empirica app.
• •Only install dependencies with npm install in client/ and server/.
• •Start and run the app with empirica from repository root.
• •If a full integration build check is needed, run empirica bundle from repository root.

1. •Ground yourself in Empirica references before proposing details:
   • •docs: https://docs.empirica.ly/
   • •framework repo: https://github.com/empiricaly/empirica
   • •docs repo: https://github.com/empiricaly/docsv2
   • •project reference map: schema/empirica-reference.json if present

Generalizable Empirica defaults to enforce in every spec:

• •Lifecycle contract first: explicitly map intro/exit (asynchronous) vs rounds/stages (synchronous).
• •Data-scope contract first: define where every variable lives (game, player, round, stage) before implementation.
• •Async server work plan: if timers/workers/external APIs are involved, require explicit Empirica.flush() points.
• •Reliability plan: include deterministic key naming and producer/consumer ownership for every analytic field.
• •Validation plan: require end-to-end run + export schema verification, not code inspection only.

1. •

   Elicit missing requirements:

   • •target population and sample size
   • •multiplayer vs single-player requirements
   • •treatments/factors and assignment constraints
   • •required player count per treatment (do not assume pairwise games)
   • •per-round and per-stage timing
   • •decisions each participant makes
   • •payoff/scoring logic
   • •chat and communication rules
   • •intro flow requirements:
     • •consent behavior (default or custom consent component)
     • •instructions/onboarding content
     • •comprehension or attention checks
   • •exit flow requirements:
     • •exit survey items
     • •participant completion/submission code behavior
     • •debrief content
   • •export variables required for analysis
   • •explicit data scope for each variable:
     • •game scope (game.set)
     • •player scope (player.set)
     • •round scope (round.set, player.round.set)
     • •stage scope (stage.set, player.stage.set)
2. •

   Produce an implementation-ready spec with these sections:

   • •Treatments mapped to .empirica/treatments.yaml
   • •Lobby setup mapped to .empirica/lobbies.yaml
   • •Admin panel plan:
     • •batch composition (how many games per batch)
     • •assignment method choice (complete vs simple)
     • •treatment randomization strategy
     • •treatment test scope: all treatments or named subset
   • •Game lifecycle mapped to server/src/callbacks.js hooks
   • •UI flow mapped to client/src components
   • •Intro/Exit flow (EmpiricaContext mapping):
     • •client/src/App.jsx EmpiricaContext consent, introSteps, exitSteps
     • •explicit ordered arrays of intro/exit React components
     • •expected data keys captured in intro/exit and their scope
   • •UI preview checkpoint:
     • •provide wireframe-level stage screens before coding
     • •ask researcher for feedback and approval
   • •Data schema listing required keys by scope:
     • •player persistent (player.set)
     • •round (player.round.set, round.set)
     • •stage (player.stage.set, stage.set)
     • •game (game.set)
3. •

   Validate feasibility against Empirica Classic primitives used in this repo:

   • •game.addRound, round.addStage
   • •Empirica.onGameStart/onStageEnded/...
   • •player hooks (usePlayer, useRound, useStageTimer, usePlayers)
4. •

   Before finalizing the spec, run a researcher checkpoint:

   • •present a concise "Empirica primitive plan" with:
     • •Treatment(s) and factor mapping
     • •Lobby design
     • •Game composition and assignment method
     • •Round/Stage sequence with timers
     • •What is stored at game/player/round/stage scope
   • •ask for explicit confirmation or requested changes.
5. •

   End with a build plan ordered by file edits and a test plan.

   • •include implementation setup step to configure .empirica/empirica.toml auth placeholders (CHANGE_ME_SRTOKEN, CHANGE_ME_PASSWORD) before admin/testing flows.
   • •test plan must include strict E2E completion criteria:
     • •required participant count per treatment launched
     • •all simulated participants reach final exit
     • •condition-specific interactions exercised for each treatment

Output format:

• •Start with a concise assumptions list.
• •Then provide the final spec in structured bullets.
• •Include an explicit "schema contract" table with: key, scope, unit of analysis, description, producer, consumer, export file target (game.csv, player.csv, round.csv, stage.csv).
• •End with an "Empirica references consulted" list (doc page/repo section names).