empirica-implementation

Use this implementation checklist:

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. •Confirm relevant Empirica references before editing:
   • •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 0.5 Configure required admin auth placeholders before implementation/testing:
   • •open .empirica/empirica.toml
   • •replace CHANGE_ME_SRTOKEN and CHANGE_ME_PASSWORD with real values
   • •use those configured admin credentials consistently in automation/test commands

Generalizable implementation defaults:

• •Preserve lifecycle semantics: intro/exit are asynchronous; rounds/stages are synchronous.
• •Keep scope boundaries strict: game/player/round/stage attributes should be intentional and documented.
• •For async writes outside lifecycle callbacks (intervals, API callbacks, workers), call await Empirica.flush() after set(...).
• •Load env before callback module initialization (dotenv first, then import callbacks) when top-level env reads exist.
• •Prefer stable, explicit shared-state keys for UI/server coordination; avoid implicit state coupling.

1. •

   Before coding, present the UI plan to the researcher:

   • •show proposed participant screens by stage
   • •call out interactions and where each decision is saved (player.stage, player.round, etc.)
   • •request explicit feedback before implementation
2. •

   Translate experiment design into Empirica config:

   • •update .empirica/treatments.yaml
   • •update .empirica/lobbies.yaml
   • •include an admin-run plan that states expected batch and randomization setup
3. •

   Implement lifecycle logic in server/src/callbacks.js:

   • •create rounds/stages in onGameStart
   • •compute outcomes in onStageEnded or onRoundEnded
   • •store all analytic variables with explicit keys
   • •avoid silent defaults for missing critical values
   • •if using async timers/workers/API responses, flush writes (await Empirica.flush())
4. •

   Implement player UI in client/src:

   • •round/stage routing in Stage.jsx
   • •task components in client/src/task-design or new feature folders
   • •profile/summaries in Profile.jsx
   • •intro/exit survey fields in client/src/intro and client/src/exit
   • •wire intro/exit in Empirica-native way in client/src/App.jsx:
     • •use EmpiricaContext props consent, introSteps, exitSteps
     • •provide intro/exit components as ordered arrays
     • •keep each step as a focused React component under client/src/intro or client/src/exit
5. •

   Keep schema keys synchronized across server and client:

   • •every get("key") should have a clear producer set("key")
   • •use stable, analysis-friendly key names and annotate each key with Empirica scope in final report
6. •

   Verify by running Empirica-native flow:

   • •empirica bundle for integration build check
   • •then run autonomous test and screenshot workflow from the testing skill
   • •ensure the autonomous run has strict completion criteria:
     • •all simulated participants reach final exit
     • •treatment-specific mechanics are exercised (not just nominal page traversal)
     • •failures block "test passed" status until resolved

Required output after coding:

• •list of touched files
• •list of new schema keys grouped by game/player/round/stage
• •intro/exit mapping summary:
  • •consent component used
  • •introSteps order
  • •exitSteps order
• •Empirica references consulted
• •remaining assumptions or limits