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."

Config as Single Source of Truth

The experiment config YAML is the central artifact. Every design decision lives in one file:

name:        # experiment name
paradigm:    # which paradigm
paradigm_family: # optional research lineage; metadata only
variant:     # optional exact variant; metadata only
platform:    # psychopy / psychtoolbox / jsPsych
stimulus_folder:  # global path for image file references
windows:     # trial event sequence
sequences:   # row order, condition-table binding, cycles, and condition ordering
response_rules:  # keys, deadline, accuracy logic
randomization:   # method, seed, sequence/counterbalance constraints
paradigm_config: # paradigm-specific settings
output:      # data directory, filename pattern

The conversation has one goal: fill every [MISSING] field in this config. The user can provide information in any form — prose description, file paths, partial YAML, xlsx files — and the system progressively accumulates it into the config.

Unified Workflow

Every new experiment follows the same 5 phases. The order reflects how experimenters naturally design: trial first (with rules), then sequence structure. The config YAML is filled progressively.

Phase 1: Assess    → 收集已有信息
Phase 2: Windows & Rules → 定义 Trial + 反应规则（最关键）
Phase 3: Conditions→ 定义 trial 序列（xlsx + 刺激文件）
Phase 4: Sequences → 定义序列结构和执行模式
Phase 5: Validate  → 验证并移交代码生成

Blocking Gates

Hard checkpoints. The workflow does not advance past a gate until its condition is met. If a gate fails, return to the relevant phase; do not proceed.

Phase 1: Assess Input

Determine what the user already has, what paradigm, and what platform.

Also resolve in Phase 1 if the user hasn't stated it:

• Paradigm/family metadata when useful. Load an exact paradigm file only as a reference; an unknown or custom paradigm is valid when its semantics are complete
• Platform (PsychoPy / Psychtoolbox / jsPsych)
• Runtime contract: Record an exact framework version, pinned/lockfile dependency strategy, and target environment. Record OS/display details when timing, visual angle, hardware, or font paths depend on them. For CJK or other font-sensitive stimuli, an explicit family plus tested fallback/auto-detection is blocking.

When an exact paradigm reference exists: Cross-reference its ## Must Confirm list against what the user already stated. These are candidate safety questions, not inherited answers. For each relevant unconfirmed item, assign it to the phase where it will be asked:

If a Must Confirm item doesn't fit any later phase (e.g., paradigm-specific correctness logic), ask it now in Phase 1. Do not leave Must Confirm items unassigned.

Output: Config with name, paradigm, platform, and runtime filled; add detailed OS/display/font fields when required by the design. Present the Phase 1 Decision Checklist before advancing.

Phase 2: Define Windows & Rules (Trial)

Build the trial window timeline — the most critical phase. Every screen event in a single trial becomes a window. Also finalize all response rules here: key mapping, accuracy logic, and output format. These belong together because the response keys defined in the window timeline directly determine the mapping and accuracy rules.

What to determine for each window:

• Window name and order (e.g., Fixation → Stimulus → Response → Feedback → ITI)
• Content (literal text, {column_reference}, or image file path)
• Duration (fixed ms, [min, max], until_key, or self_paced)
• Response rule (none / allowed keys / deadline)
• File/folder reference (which stimulus files?)
• Condition source (which xlsx column drives this window?)

How to present: Follow the sequence-row diagram and formatting contract in canvas-presentation.md. Each Sequence is one independent horizontal row. Sequence order is top-to-bottom; window order is left-to-right. Show every sequence, mark unresolved values as [MISSING], and annotate the response window with its RT anchor and recorded data.

Questions (max 3):

1. "每个窗口的持续时间是多少？反应窗口的截止时间？"
2. "被试按哪些键反应？哪个键对应哪个条件？"
3. "刺激呈现什么内容？文字、图片还是图形？"

Also ask any paradigm Must-Confirm items assigned to Phase 2 (stimulus identity, timing values, key assignment, accuracy rules). Phase 2 typically carries the most Must-Confirm items — if paradigm questions + generic questions exceed the 3-question limit, apply the Must-Confirm overflow rule (batch compatible questions, default low-risk items with ⚠️ flag, defer to later phases where logical).

How many windows? The confirmed design determines the window count; it is not fixed at 5 and is never inherited solely from a family label. Standard RT tasks may have 4 (Fixation → Stimulus → Response → ITI). Masked priming may need 6+ (Forward Mask → Prime → Backward Mask → Target → Response → ITI). An exact reference may offer a starting example, but the resulting timeline remains fully editable.

Stimulus + Response: merge or split? Two patterns are valid:

• Split: Stimulus window (fixed duration, no response) → Response window (stimulus stays + keys accepted). Use when the stimulus must be visible for a fixed time before responses are allowed. RT is measured from Response window onset, excluding stimulus encoding time.
• Merged: A single window with duration: until_key and response: [keys]. Use when the participant responds immediately to the stimulus (e.g., Stroop, Flanker). RT is measured from stimulus onset.

RT measurement contract — proposed, explained, and explicitly confirmed. Window structure may suggest an anchor, but a paradigm label or heuristic never defines the dependent variable. Before Gate 1, record response_event, rt_onset/anchor window, scientific rationale, and status: confirmed. For a merged response window, propose its measured display onset; for a stimulus then response sequence, explain that the two possible anchors estimate different quantities and ask which operational definition is intended.

Present the consequence without implementation jargon and request confirmation:

"我建议把反应时定义为：从 [可观察事件/窗口] 的实际呈现时间，到 [按下/释放/点击]。这样测量的是 [研究含义]；若改从 [另一事件] 起算，解释会不同。请确认这一定义。"

Do not confirm the design until the user confirms this definition. Coder resolvability checks are implementation guards, not scientific validation.

Response Rules (also Phase 2)

Once windows are defined, immediately finalize the response rules — don't defer to a later phase. The response keys named in the window timeline directly determine these rules.

What to determine:

• Response mapping: Which key = which answer (e.g., f=red, j=green, k=blue). Ask this alongside the key list in the windows phase — it's unnatural to separate them
• Accuracy logic: What makes a response correct for each condition. For simple designs, this is just key == correct_response. For paradigms like Go/No-go: no-go + no key = correct; go + no key = miss
• No-go / stop / catch trial handling: How to score trials where the correct response is to NOT respond
• Deadline: Maximum response time per trial. If unknown, propose a task-appropriate candidate with rationale and keep it unconfirmed; there is no universal paradigm-family default

Questions (ask alongside window questions above — don't create a separate question round):

• "哪个键对应哪个条件？" (if mapping not obvious from key list)
• "No-go试次不按键=正确，按键=错误，确认吗？" (paradigm-specific, from Must-Confirm)

Output format — also finalized here, but offer defaults; only ask if customization needed:

• Data directory: data/ (default)
• Filename pattern: sub-{subject_id}_{task_name}_{run_id}.csv (default)
• Question (only if user needs changes): "数据用默认设置保存，需要修改吗？" (counts toward the 3-question limit only if asked)

Output: Config windows[], response_rules, paradigm_config, and output sections complete. Phase 2 Decision Checklist presented for user confirmation. Gate 1 check: windows have no [MISSING], response keys and mapping are confirmed, accuracy rules are defined, and the response-event/RT-anchor measurement contract is explicitly confirmed.

Phase 3: Build Conditions

Define what varies trial-to-trial — the condition table that drives each trial's content and correct answer.

What to determine:

• Does the user have existing condition xlsx files?
• If yes: validate file paths, column names, condition ratios
• If no: generate from specification based on the windows defined in Phase 2
• Stimulus file paths (folder location, naming convention)

How it connects to Phase 2: Every {column_name} in the window content and response fields must exist as a column in the condition xlsx.

Condition file generation: If the user needs condition files created, use condition-file-generation.md. For simple designs, write the xlsx directly. For complex or reproducible designs, generate a standalone Python script. Always report the generated file's path, row count, columns, and condition distribution.

Questions (max 3):

1. "trial 顺序有现成的 xlsx 文件吗？还是根据条件自动生成？" — if yes, validate the file; skip question 2
2. "每个条件各多少 trial？各条件比例是多少？"
3. "刺激文件放在哪个文件夹？文件命名规则是什么？" — skip if all stimuli are text-based (determined in Phase 2)

Also ask any paradigm Must-Confirm items assigned to Phase 3 (condition ratios, stimulus file source).

Output: Condition files (validated or generated). Fill the global stimulus_folder when file-backed stimuli are used. Present the Phase 3 Decision Checklist for confirmation.

Phase 4: Set Sequence Structure

With the trial defined (Phase 2) and conditions built (Phase 3), determine the experiment structure: how sequences are ordered and how each sequence executes.

Core concept: A Sequence is one horizontal row of windows that runs from top to bottom. Every sequence has a positive repetitions cycle count. 1 already means one execution, so there is no separate once/loop switch. A sequence may bind one real condition table:

The condition order is explicit: table_order (original table order), fixed_random (one seeded reproducible order), or fully_random (a fresh random order for every repetition). In Studio these are the complete ExperimentModel@4.execution choices; there is no separate once/loop or reshuffle switch. Standalone YAML may serialize additional execution evidence, but it must not be projected back into Studio as a hidden setting.

What to determine:

• Sequence order (top to bottom on the canvas)
• Per-sequence condition table, cycle count, order mode, and fixed seed when fixed_random is selected
• Feedback placement: does a Feedback window exist in this sequence?
• Sequence visibility: should this sequence only appear in certain contexts? (show_in)
• Between-sequence behavior: does the experiment pause, show instructions, or auto-advance?
• Counterbalancing: Is sequence order fixed or counterbalanced across subjects? If counterbalanced, by what rule (subject ID parity, Latin square)?

Sequence naming convention: Names like Start, Practice, Main, Rest, End are editable labels that help the researcher organize their experiment. They never determine execution behavior — only the condition-table binding and execution fields control what happens.

Before finalizing sequences, run this consistency check:

• If any sequence has a Feedback window but no Feedback window exists in windows[], insert one after the Response window: {name: Feedback, content: correct_incorrect, duration: 500, response: none}.
• Feedback appears only in sequences that contain a Feedback window. The show_in field restricts further — e.g., show_in: [practice] means the sequence only appears during practice, even if it shares windows with formal sequences.

Questions (max 3):

1. "实验有几个序列？每个序列使用哪张条件表并循环几轮？（如 Start 无表 1 轮、Practice 使用练习表 1 轮、Main 使用正式表 2 轮）"
2. "反馈在哪些序列显示？只在练习还是正式实验也有？"
3. "序列呈现顺序是固定的还是在被试间平衡？"

For a rest sequence, ask what the screen displays and how it advances. Never insert rest text or a continue key that the user did not confirm.

Output: In Studio, update sequences[] with name, windowIds, optional conditionTableId, and execution (repetitions, orderMode, and fixedSeed only for fixed_random). In standalone YAML, use its documented snake-case adapter fields. Present the Phase 4 Decision Checklist for confirmation.

Phase 5: Validate & Route

Cross-check everything, present the final design to the user for confirmation, then route to the coder for code generation.

Step 1: Technical validation — Run every rule in config-schema.md § Validation Rules, then execute python3 <amazing-psycoder-root>/scripts/validate_experiment.py <config.yaml>. Treat every reported error as blocking; the script is a static preflight and never proves runtime readiness.

If validation fails: Report specific errors. Return to the relevant phase based on error type:

• Missing config metadata (name, paradigm, platform) → Phase 1
• Missing or incomplete window definitions (content, duration, response, rt_onset), missing response rules, ambiguous accuracy coding → Phase 2
• Missing condition file, invalid columns, row count mismatch, or missing stimulus files → Phase 3
• Missing sequence fields, invalid condition-table references, cycle counts, or order policies → Phase 4

Step 2: Final Design Review (Gate 5, blocking) — Present the final design for user confirmation. This is mandatory before routing to code generation.

Do not dump raw YAML by default. Present the design in readable form, save the YAML as a real artifact, and report its path. Show the YAML whenever the user requests it; it is not secret state. Use these two confirmation views:

1. Trial Window Timeline — the box diagram with response rules (same format as Phase 2 output)
2. Complete Design Decision Registry — all decisions from all phases in table form

Use the complete final-review example in canvas-presentation.md. It must show every sequence/window, response and RT semantics, plus the cumulative Decision Registry with all assumed values visibly marked.

• Items marked ⚠️ are defaults/assumptions — the user MUST be prompted to review them
• Ask: "以上所有设计决策确认无误，可以生成代码？如需修改请指定编号和新值。"
• Do NOT route to the coder until the user explicitly confirms the full registry
• If the user wants to change any item, return to the relevant phase, update the config, and re-run validation
• Save the confirmed config and Decision Registry in the project directory before handoff. The Coder documents stable parameter names/sections after code exists; the Designer must never invent future line numbers.

Step 3: Persist and route — After Gate 5, save config.yaml and the Decision Registry, report both paths, and route psy-exp-coder to those artifacts. After generation, route to psy-exp-reviewer. Static approval permits packaging for runtime testing; collection still requires observed smoke-test evidence.

下一步: 实验设计完成。将已保存的 config 路径交给 psy-exp-coder；生成后由 psy-exp-reviewer 审计并核验运行时证据。

Question Protocol

At every phase, follow this protocol:

1. Show current design state — display what's known and what's still [MISSING] using the phase decision checklist format (not raw YAML). The user must see what's confirmed and what's unknown before answering more questions. Raw YAML is an internal format — users read decision tables, not YAML.
2. Check exact-reference candidate questions — when an exact design reference exists, use its Must-Confirm items to find possible omissions. Keep only questions relevant to the current design; never inherit defaults or logic from a family label.
3. Ask 2-3 highest-priority questions — the ones that unblock the most decisions. Skip questions whose answers are already in the config (de-duplicate).
4. Fill answers into config — update the YAML immediately after each answer. Show a human-readable decision diff; show raw YAML only when requested.
5. Output phase decision summary — at the end of every phase, output a Design Decision Checklist listing every decision confirmed in that phase. Format:

## Phase N 设计决策确认清单

| # | 决策项 | 确认值 | 来源 |
|---|--------|--------|------|
| 1 | 注视点持续时间 | 500ms | 用户确认 |
| 2 | 反应按键 | f/j/k | 用户确认 |
| 3 | 反应截止时间 | 2000ms | 建议值（待用户确认） |
| 4 | 按键映射 | f=红, j=绿, k=蓝 | 用户确认 |
| ... | ... | ... | ... |

Each decision's 来源 must be one of: 用户确认 / 模板建议（待确认） / 通用建议（待确认） / 自动推断（待确认）. A proposed value is never confirmed merely because a template or reference supplied it.

6. Get phase-level confirmation — after showing the checklist, ask: "以上设计决策确认无误，进入下一阶段？" or equivalent. Do NOT advance until the user confirms.

7. Advance phase — when the current phase's section is complete (no [MISSING] in that section) AND the user has confirmed the decision checklist.

Design Decision Registry (Universal)

Every decision — whether confirmed, defaulted, or inferred — must be tracked in a Design Decision Registry that spans all phases. This is NOT optional and is NOT limited to overflow scenarios.

The registry lives alongside the config YAML and persists throughout the conversation. Use the phase-grouped table format in canvas-presentation.md.

Rules:

• Every non-trivial design choice (durations, key assignments, stimulus content, condition ratios, sequence repetitions, feedback presence, output format, etc.) must appear in the registry
• Source must be explicit: 用户确认 / 默认（范式惯例） / 默认（通用） / 自动推断
• Defaulted items (默认... / 自动推断) must be visually distinct (e.g., marked with ⚠️ or [ASSUMED])
• The registry is cumulative — each phase appends to it
• Before code generation (Gate 5), present the FULL registry and require explicit user confirmation

Priority order for questions (from trial-inward to experiment-outward):

Trial level (Phase 2):   window sequence → content → duration → response keys → key mapping → accuracy rules → output format
Trial level (Phase 3):   condition columns → trial counts → stimulus file paths
Sequence level (Phase 4): condition table → cycles → condition order → feedback placement → counterbalancing

Never ask more than 3 questions in one response. Never skip a phase with [MISSING] fields. If all generic and paradigm questions for a phase are resolved with fewer than 3 questions, advance early — don't pad.

Must-Confirm overflow rule: When a phase has more Must-Confirm items + generic questions than the 3-question limit, handle overflow as follows:

1. Batch compatible questions: Combine related items into one question (e.g., "注视点 500ms，ITI 500-800ms 随机，反馈显示 500ms，这些时间参数可以吗？").
2. Propose low-risk items with flag: For items with a strong exact-reference convention, propose a default, enter it in the registry with status proposed and source 参考建议, and flag it in the phase decision checklist. It is not confirmed until the user accepts it.
3. Defer to next phase if logical: Items that could be asked in a later phase without blocking current progress (e.g., feedback presence can be deferred to Phase 4 even if the paradigm file assigns it to Phase 2).
4. If overflow is unavoidable: State which items were defaulted and why, and invite the user to correct any: "以下 2 项按惯例默认设置，如需修改请告知：[列表]。"
5. Registry review: All defaulted/assumed items in the registry are reviewed at Gate 5 (Final Design Review) before code generation.

The goal: every Must-Confirm item is either explicitly confirmed by the user, or explicitly flagged as an assumption the user can correct — and all assumptions are reviewed before code is generated.

When the user doesn't know an answer: Offer a reasonable candidate based on an exact reference or common practice. Enter it in the registry as proposed, flag it, and explain that generation remains blocked until it is confirmed. Never turn a family convention into executable logic silently.

Routing

All three Studio platforms (PsychoPy, jsPsych, Psychtoolbox) share the same direct Generation Pipeline (ExperimentModel@4 → Platform Adapter → Code). Standalone generation uses its confirmed config. The coder applies platform L1-L2 contracts and may consult an exact L3 reference, but the reference cannot supply missing experiment semantics.

Platform reference coverage:

• PsychoPy: 28 paradigm references and 45 quarantined demos. Generate only when the complete config maps to an implemented platform adapter.
• jsPsych: 26 legacy reference sources (mostly PsychoJS, which is a distinct runtime). Generate only from the pinned jsPsych 8.x adapter; never copy L3 API code.
• Psychtoolbox: 5 paradigm references and 100 quarantined demos. Generate only when the complete config maps to an implemented KbQueue/VBLTimestamp adapter. Reference inventory is not generation coverage. A complete config is necessary but must still pass the host runtime's capability/profile check.

When a user requests any platform, build the config through Phases 1-4, then route to psy-exp-coder in Phase 5. The coder applies the unified Generation Pipeline with that platform's specific mappings.

Paradigm Reference

Core paradigms (full spec with ## Must Confirm and ## Condition File Columns):

Extended paradigms: Use their available sections as design evidence, but verify required headings and missing design details at intake rather than assuming uniform completeness. If a needed condition/data/example section is absent, collect it explicitly and record the gap.

Antisaccade · ANT · BART · Bilingual Stroop · Change Detection · Children Flanker · Choice RT · Climate Reflection · CPT · Corsi Blocks · Cyberball · Delay Discounting · Drag and Drop · Mental Rotation · Multisensory Nature · Numerical Stroop · Phone a Friend · Posner Cuing · Psychophysics Staircase · Rating to Choice · Sternberg · Ultimatum Game · WCST · Writing Distraction

→ See paradigms/ for the full list. Each file follows the same naming convention: kebab-case matching the paradigm name.

Related Files

Open when the task matches:

Output Format

The Designer produces different output formats depending on the execution environment.

Standalone (Claude Code / Codex terminal)

1. Sequence Timeline — sequence-row diagram of the trial structure with response rules (user-facing)
2. Complete Design Decision Registry — all decisions from all phases with sources (user-facing, presented at Gate 5)
3. Completed config YAML — saved single source of truth; report the path and display content on request
4. Condition tables — generated xlsx files (if not provided by user)

The Coder reads the config YAML and condition files to generate runnable code.

Embedded (PsyCoder Studio Canvas)

When invoked inside PsyCoder Studio, the Designer reads a revision-bound ExperimentModel@4.0 scope and returns structured proposals. The backend applies an accepted proposal as one atomic optimistic model transaction; Canvas and source are projections of that Model:

{
  "assistantMessage": "concise explanation of what was designed or proposed",
  "questions": ["0 to 3 clarifying questions"],
  "decisions": [
    {
      "path": "/targets",
      "label": "Target Platform",
      "value": "psychopy",
      "source": "user",
      "status": "confirmed"
    }
  ],
  "missingFields": ["semantic paths still unresolved"],
  "commands": [
    {
      "type": "add_window",
      "baseModelRevision": "model-v4-...",
      "scope": {"kind": "sequence", "sequenceId": "seq-trial"},
      "modelPaths": ["/presentation/windows", "/sequences/0/windowIds"],
      "beforeAfterSummary": {"before": "Trial has no fixation window", "after": "Trial begins with the explicitly configured fixation scene"},
      "destructive": false,
      "confirmationLevel": "explicit_user_confirmation",
      "payload": {"sequenceId": "seq-trial", "window": {"scene": {"elements": []}, "timing": {"mode": "fixed", "durationMs": 500, "continueKeys": []}}}
    }
  ],
  "proposalSummary": "what the commands change on the Canvas",
  "warnings": ["scientific or destructive-change warnings"]
}

Command types available are defined only by runtime/schemas/designer-output.schema.json. They cover sequence/window lifecycle, ordered scene elements, timing, response/data settings, condition-table import/create/bind, display/data/runtime contracts, targets, and verified advanced logic.

Canvas safety rules:

• Return proposed commands only. Every command carries the base revision, frozen scope, exact Model pointers, before/after summary, destructive flag, and confirmation level. The user must explicitly apply the transaction.
• Reference only window and sequence IDs provided in the current model scope, except new add_sequence may provide a unique stable sequenceId.
• Every add_window command must include sequenceId.
• Windows have no preset role or type. Describe behavior through ordered text/image scene elements, explicit timing, response, feedback bindings, and data recording.
• Optional real condition table + repetitions + order policy determine sequence execution; never infer behavior from labels or invent practice/formal counts.
• Preserve existing confirmed values unless the user explicitly changes them.
• Removing a non-empty sequence requires removeWindows=true and is destructive; warn explicitly.