psy-exp-designer

Psychological Experiment Designer

Version

v1.4.0 — unified evidence-gated contract, 2026-07-23. Sub-skill of amazing-psycoder.

Purpose

Convert psychological experiment ideas into a complete experiment specification (config YAML) through progressive refinement, then route the validated config to psy-exp-coder. Do not generate implementation code in this skill.

Design Philosophy

Let the user own design decisions while the system enforces explicit semantics, progressive confirmation, traceable assumptions, and a complete config before code generation. Paradigm references suggest questions; they do not own the design.

Paradigm References Are Non-Authoritative

paradigm and paradigm_family classify a design and may select an optional knowledge reference. They never select executable logic or initialize hidden experiment fields. The user's confirmed windows, condition model, correctness rules, randomization constraints, feedback, and data schema are authoritative.

Do not collapse variants into a family implementation. Classic color-word, semantic, emotional, bilingual, and numerical Stroop may require different stimulus schemas, factors, derived variables, correctness rules, and analysis interpretations. If no exact reference exists, continue as a custom design and derive every semantic rule from the user-confirmed config.

When Not to Use

Route implementation/debugging to psy-exp-coder, readiness audits to psy-exp-reviewer, and answer quick platform API questions directly.

Core Model

Model every experiment as Experiment → Sequence → Window → Data. Require one trial-summary row per trial; add a linked event-level table when a trial has repeated responses, trajectories, adaptive steps, drag events, or other one-to-many observations. Never force repeated events into a single lossy cell.

Red Lines

Hard prohibitions. These must never be violated — no exceptions, no "just this once."

#	Rule	Applies to	Why
1	No code generation before trial window timeline is complete	All platforms	Code written without a validated window sequence will have structural errors that are expensive to fix
2	No assumed response mapping	All platforms	Which key means what answer must be confirmed with the user. Guessing invalidates accuracy data
3	No blocking sleep in timing-critical or interactive windows	PsychoPy, jsPsych	Blocking waits make timing and abort handling unreliable. Use frame/timeline scheduling; never use a setup wait as an RT source
4	No event.getKeys(maxWait=...)	PsychoPy	Blocks the event loop. Use keyboard.Keyboard with win.callOnFlip(kb.clock.reset)
5	No data saved only at end of experiment	All platforms	Crash = all data lost. Save incrementally per trial or per sequence with try/finally
6	No silent filling of [MISSING] values	All platforms	Every [MISSING] must be resolved by asking the user or offering an explicitly-flagged default
7	Font-sensitive/CJK text needs an explicit font strategy	All platforms	Record a suitable family/path/fallback for the target runtime and verify glyphs and layout visually; browser fallback stacks are acceptable when tested
8	No skipping relevant design decisions	All platforms	Exact paradigm references may suggest questions, but only the actual experiment specification determines what must be confirmed
9	No rt_onset omitted on response windows	All platforms	Incorrect or missing RT onset invalidates all reaction time data. The coder will refuse to generate if absent
10	No code delivery without reviewer pass	All platforms	All generated code must pass through psy-exp-reviewer before data collection. Programming → Coder → Reviewer is a mandatory chain