Add Prolific readiness audit and decision register

[htsukamoto5]

Stacked on #1 (chore/vendor-multiplayer-bundles), because that branch is the only state that currently runs — main still points at the broken npm 0.1.0 pins — and READINESS.md cites vendor/ throughout. Happy to rebase onto main once #1 lands.

Documentation only. No behaviour change. Code work sits in #14, deliberately branched off #1 rather than off this PR so the two do not block each other.

What this adds

READINESS.md — an audit of both reference-game builds against what a live paid Prolific run actually requires. Findings were verified by reading the four vendored bundles, not by trusting the header comments, which turned out to matter.

DECISIONS.md — every open decision in one table with a suggested answer, the reasoning in one line, and what it costs to reverse. Grouped by when each decision stops being deferrable rather than by topic, and ending in a publish-time launch checklist. Read this one first if you want the decisions rather than the reasoning behind them.

The three findings that block a paid run

No pairing mechanism for strangers. lobbyTrial has no timeout, and the plugin default is null, so wait() is unbounded: an unmatched participant waits forever with no exit and no completion code, and therefore cannot be paid. Entries are removed only on an explicit disconnect() — no heartbeat, no beforeunload anywhere in the bundles — so against persistent room state a live participant is matched with a ghost and then times out every round. The spectator overflow path is also a dead end with no code. (#6, #10)

No partner-dropout handling. round_timeout sets its timer at round start, so when it fires the timeline advances and starts a fresh timer. A survivor grinds through ~71 minutes of dead waiting on Hawkins, ~15 on C&WG, and is never told anything, because the plugin has no partner-status UI at all. They abandon, so one dropout burns two payments. (#5)

No data save target. initJsPsych() takes no options; the only egress is a voluntary download button on the final screen. Every participant who does not finish contributes zero data — including exactly the sessions needed to characterise attrition. (#3, #4)

The corrected claim

Both HTML headers and README.md asserted that swapping adapter-multiplayer-local for -firebase required no other change to the file. It is not a drop-in. SEED reads ?mp_session=, which the LocalAdapter constructor generates via history.replaceState; Firebase will not produce it, so every dyad silently falls through to the same literal seed and receives an identical trial order — confounding item order with trial number, the exact confound the seeding exists to prevent. No error, valid-looking data. persistParticipant is also LocalAdapter-only. Tracked as #9, to ship in the same change as the swap.

Platform and infrastructure findings

Added after checking Prolific's documentation and DataPipe's source rather than reasoning from assumptions. Several of these constrain issues that were already open:

• Prolific provides no matching infrastructure and does not guarantee pairing, and there is no appointment or slot-booking feature — time-window studies are explicitly "at the researcher's own risk." Burst launch via schedule-publish is the entire simultaneity lever, so Pairing: build a rolling waiting room (room bucketing, ghost expiry, odd arrivals) #10 cannot be delegated to the platform.
• Unmatched participants must be paid and must not be rejected, minimum $0.14/min. The suggestion is to pay the full task rate instead, because a floor-rate payment loses to returning the study and teaches people to abandon the lobby.
• Returns are not rejections. Prolific advises returning rather than rejecting to protect approval rate, so no approval-rate prescreener catches serial abandoners — the platform is structurally blind to the failure mode that costs us most.
• DataPipe's sessions counter increments per save call, not per participant. With per-round saving one C&WG participant consumes seven sessions, so sizing maxSessions to a participant count caps a run about a seventh of the way through and drops every later save silently. Read from functions/src/api-data.ts, not from the docs, which do not mention it.
• An OSF 409 on a duplicate filename is the one save failure that is not retried, so per-round chunks need a nonce rather than just a round number.

Also added

• Ethics / IRB (§6) — a hard blocker with the longest lead time of anything in the document, and previously absent. Focused on what is unusual here: retained chat between strangers, withdrawal in a dyad where the DVs are jointly produced, third-party data transfer, and payment policy for screened-out and unmatched participants.
• Pre-registration (§7) — carries the only hard deadline that is not upstream-gated, since it must be locked before the first paid participant. That makes it the real deadline on the Decide: are partial (aborted) dyads usable for analysis? #8 analysis decision. Notes that the 20-dyad target is an assumption carried through the cost model rather than a powered number.
• An agreed execution order, since the phase-1/2/3 grouping is by upstream dependency and is not the order to work in.
• All amounts converted to USD, since that is what participants are paid in, and the cost model rebuilt on a suggested $15.00/hr.

Recommendation recorded in the file

Run C&WG as the first paid study, not Hawkins: ~25 min vs 55 min moves pair-based attrition economics by about 3× ($465 vs ~$1,500 for 20 usable dyads), and it keeps the survivor-grind failure mode bounded at 15 minutes instead of 71.

Also worth saying

The replication logic itself is in good shape, and the audit says so explicitly — parameters verified against both papers and hawkrobe/tangrams, an unusually thorough set of faithfulness comments, a per-round data spec covering every stated DV, and chat_transcript built from the group snapshot so the full dialogue survives a partner dropout. The gap is entirely in the run infrastructure around the experiment.

Action items are filed as #3–#13, grouped into the same phases as the work plan in the file, with the upstream-blocked ones labelled blocked-upstream.

🤖 Generated with Claude Code