synthetic-userstudies

name

synthetic-userstudies

description

Run synthetic user research sessions natively — no backend required. The agent plays an AI-generated persona and simulates a user interview based on the 4 Ps framework (Persona, Problem, Promise, Product). Use when a user wants to run a user research session, interview a synthetic persona, validate product ideas, generate user personas, or simulate customer conversations. Triggers on "user research", "synthetic persona", "simulate a user", "userstudies", "interview a persona", "validate my idea", or "talk to a user".

Synthetic UX Research

Run user research sessions natively. No backend calls. The agent plays the persona, generates characters, and runs interviews using the same prompts as userstudies.ai.

Session Flow

1. Setup Phase

Collect the 4 Ps. Ask for any that are missing:

Field	Description
Persona	Short description of target user (e.g. "Primary care doctor, US, recently graduated")
Problem	What they're struggling with — in their words
Promise	Value prop in <7 words (e.g. "Single-serve coffee")
Product	Key features / what you're building

If any field is blank or weak, offer to autofill it. See Autofill section below.

Once all 4 Ps are set, confirm them and note the research phase (default: Right Problems — problem discovery). Load principles.md for the phase framework. Then move to character generation.

2. Character Generation

Generate a Character from the Persona description. Follow the schema in schema.md. Output the character as a JSON block so it can be referenced later.

Example prompt to yourself: "Create the most realistic character possible for: [persona]"

3. Interview Mode

Once the character is generated, enter interview mode. You are now the character.

Load prompts.md and follow USER_RESEARCH_PARTICIPANT_PROMPT exactly.

Rules while in character:

• Respond as the character would via SMS: casual, personal, specific
• Use contractions, abbreviations, light emotion — vary length (few words to ~100)
• Share specific stories with sequencing, feelings, and decisions — what they did, not what they think
• If the topic isn't relevant to the character, say so in character
• Never break character unless the researcher explicitly steps out (see below)

After every response, append a --- separator and list 3 suggested follow-up questions the researcher could ask. Use the suggested_questions format from schema.md.

Question guidance: Load questions.md to seed the interview. Follow the interview structure in principles.md: open → get specifics → current behavior → pain → patterns. Suggested questions must be behavioral ("walk me through..."), never hypothetical or leading.

4. Auto-Interview Mode

If the researcher says "conduct interview" or "run the interview", run up to 6 turns autonomously:

• Follow the interview structure from principles.md: setup → specifics → current behavior → pain → patterns
• Pick the next best question from questions.md or the current suggestedQuestions
• Ask it, respond in character, generate next suggested questions
• Stay in problem space — don't drift into solution validation
• Continue until 6 turns or the researcher interrupts
• Then deliver a concise findings summary: behavior patterns first, supporting quotes second

5. Stepping Out of Character

The researcher can say things like:

• "Autofill [field]" → run autofill, stay out of character until done
• "Change the persona" → restart setup
• "Show me the character" → print the Character JSON
• "Let's wrap up" → summarize key insights from the interview

After handling an out-of-character request, ask: "Ready to continue the interview?" before re-entering character.

Autofill

When asked to autofill a field, load prompts.md and follow the corresponding AUTOFILL_*_PROMPT. Format the current conversation as:

user: [message]
persona: [response]
user: [message]
...

Return 1–3 suggestions for the field. Let the researcher pick or edit before locking it in.

Autofill is available at any point — during setup or mid-interview.

Variant Panel Mode (parallel copy/UX testing)

When the goal is comparing N copy/UX variants (welcome messages, paywall copy, chip labels) rather than problem discovery, run a parallel persona panel instead of a single interview:

1. Build 4-6 personas spanning the REAL segment axes: experience level (true beginner with zero holdings → power user with existing tooling), trust posture (scam-wary, sales-wary, data-privacy-wary), language/locale (include a native speaker of each shipped localization), and channel-nativeness. Adversarial personas (skeptic with substitutes, scared beginner) are the most informative — a variant that converts BOTH extremes is a strong signal.
2. Dispatch one delegate_task subagent per persona (respect the concurrency cap; batch if needed). Each goal must be fully self-contained: full persona bio incl. texting style and core fear, the complete text of EVERY variant, and a fixed output format (VARIANT N: [reaction] | TAPS: [choice] | SCORE: n/10, then RANKING and INSIGHT).
3. Require each persona to (a) react think-aloud in their own voice, (b) pick the chip they'd tap OR what they'd type instead (typing-instead-of-tapping is itself a finding), (c) score 1-10, then step out of character for a ranking + one segment insight.
4. For localized products, ask the native-speaker persona to flag clunky translations and suggest natural phrasing — this surfaces real localization bugs (gendered greetings, false-friend verbs) that copy review misses.
5. Synthesize across personas: look for (a) variants that win everywhere (rare, strong), (b) variants that flip meaning by segment (same words read as protection vs. noise vs. exclusion), (c) variants that are "nobody's enemy" (safe floors). Cross-check against third-party research (e.g. NN/g) before recommending.
6. Always state the caveat: N LLM role-plays are directional, not proof. Unanimity across adversarial personas + converging third-party research is the strongest pre-launch evidence available, but say so explicitly.

Walkthrough / Dogfood Panel Mode (testing a product, doc, or curriculum)

When the artifact under test is something the user moves through (a course/lesson, onboarding flow, a multi-step doc, an app), not copy variants, run a walkthrough panel: each persona role-plays being taught / using the artifact, then steps out to report friction.

1. Build 4-6 personas on the REAL audience axes for THIS artifact (skill level, skepticism, time pressure, language/locale, data/permission constraints). Adversarial ones earn their seat: a skeptic finds overclaims, a non-native speaker finds idioms, a "no shareable data / joined mid-way" persona finds missing prerequisites and fallbacks.
2. One delegate_task subagent per persona. Each reads its assigned sections end-to-end, simulates going through them in character, then reports a FIXED per-section block: does the magic moment / payoff land? friction points (quote the line)? demo/prompt that would error/404/return-empty? time feel? one fix. End with a short segment takeaway.
3. Assign coverage so every section gets at least one persona; double-cover the riskiest. Synthesize by CONVERGENCE: an issue two personas hit independently, or an objective bug (a 404, a silent failure, a missing-prerequisite dead end), is high-confidence. A single persona's taste complaint is low-confidence.
4. Capture transcripts of the highest-signal struggles (clearly labeled synthetic) as a deliverable — showing the failure beats describing it.

Single embodied persona in a LIVE browser. When the artifact is a clickable prototype / pitch page with tappable phone mockups (Surge site, Figma export) and the ask is "BE this persona, tap the phones, react, score," run ONE persona embodied end-to-end through real browser_clicks — tap the CTA, re-snapshot to see the value moment mutate in place, then think-aloud + score. Full loop, the many-near-identical-buttons [nth=N] trap, and the "long page → snapshot only shows the top, read document.body.innerText.substring(...) via console instead" workaround: references/embodied-persona-live-browser.md.

Just two personas is a valid panel. One beginner + one expert (e.g. "AI-literate-but-tool-new PM" vs "technical PM who ships prototypes") covers the two ends and is often exactly what the user asks for. The beginner finds missing steps and dead-ends; the expert finds inaccuracy, overclaims, and thin advanced paths. Run each through the WHOLE artifact, not split by section, when there are only two.

For long artifacts, shard by section group, not by persona. A 20-lesson course → one subagent per arc (4-5 lessons), each running BOTH personas through its slice. Don't dump full content into the prompt; tell each subagent to read the files itself from disk and give it the exact file paths.

Testing an AGENT-driven artifact (tutorial an AI executes live)

When the artifact is a lesson/tutorial that a coding agent (Cursor, Claude Code) runs live for the student, the single highest-yield bug class is a demo or hands-on step that depends on a capability, file, or tool the student or their agent does not actually have — invisible to ordinary copy review. Make each persona TRACE every demo prompt as if pasted into a real agent. See references/walkthrough-demo-dependency-checklist.md for the full checklist (out-of-workspace paths, missing browser/screenshot tool, agent-can't-introspect-itself, repo/file the student never created, auth-flow mismatch, fallbacks that are themselves dependent).

CRITICAL: verify the panel's objective claims before acting

Subagent personas confidently assert "objective bugs" they cannot actually check (a subagent with no network declares a URL broken; one without the live file claims a structure mismatch). Convergent persona opinion is NOT verified fact. Before acting on or reporting any claimed objective failure (404, missing file, repo mismatch, broken link), verify it yourself with a real tool (fetch the URL, list the repo, read the file). In this skill's origin session a 2-persona panel called a setup lesson a hard "repo mismatch = silent first-clone failure" BLOCKER; the live repo actually shipped the promised files — the panel was wrong, and only one sub-claim (a single missing file) held. Separate persona findings (directional) from objective claims (must be verified) in the final report.

CRITICAL: calibrate the audience; don't let the weakest persona over-drive fixes

The biggest trap in walkthrough testing. A maximally-fragile persona (true novice, panicking) surfaces useful failure modes but is often a false floor — if the real audience is more capable, fixing for her panic will (a) patronize the actual user and (b) sometimes break things (e.g. demoting a tool/step the fragile persona found scary but that later parts REQUIRE).

• State the real audience explicitly before acting ("typical user is a ChatGPT/Claude-literate PM, not a true novice"). If unstated, ask or assume competence.
• Separate finding from response. The fragile persona's friction is real data; the fix must be sized to the real audience. "Assume competence" is the default — strip hand-holding glosses and anxiety-management for a capable audience.
• Keep skill-independent fixes, revert skill-dependent ones. Silent-failure bugs, missing-prerequisite fallbacks, lost-the-skeptic overgeneralizations, and non-native idiom/accessibility fixes help EVERY user — keep them. "Make the scary step optional / over-explain a common term" usually only serves the false floor — revert it, and verify it didn't break a later dependency.
• Personas are directional, not proof. Convergent + objective findings are what deserve action.

Gate / Paywall Panel Mode (testing ONE blocking flow, not variants)

When the artifact is a single gate the user hits (a paywall, a permission prompt, a forced-trial wall, a verification step) and the question is "do people get through this or bounce," run an adversarial gate panel. This is NOT variant testing (one flow, no A/B) and NOT a walkthrough (one screen, not a journey).

1. Ground the flow in the REAL product, not your guess. Read the actual gating code and copy before writing personas: find the trigger (e.g. showPaymentModalByPreference('connect_account')), the exact button label the user tapped, and the verbatim paywall copy from source. Feeding personas invented copy produces invented findings. Pull the live funnel number too (e.g. PostHog autocapture $el_text taps for the CTA vs. taps that reach the gated action) — a real drop-off % both motivates the study and cross-checks the panel.
2. 5-6 adversarial personas across the bounce axes: has-a-free-substitute (vitamin-not-painkiller), scam/security-wary, ESL/jargon-literal beginner, skeptical power user who names dark patterns, impulsive-but-broke. Each gets a full bio: texting style + core fear + what they tapped and expected. One delegate_task per persona (read-only role-play, no write tools needed).
3. Fixed output block per persona so results aggregate: SCORE: n/10 (likelihood they get through) | FRICTION: one sentence | QUOTE: exact line that hurt/helped | FIX: one change | INSIGHT: one segment insight. Have them react think-aloud in voice FIRST, then state what they actually do (start trial / close / ask someone / abandon), then step out for the block.
4. Read the result as convergence, not average. Unanimous low scores + every persona naming the SAME root cause is the strongest signal a panel gives. The highest-yield finding class here: a sequencing / placement bug — the gate fires on a button whose label promises a different action (tap "Connect your bank" → paywall, not the bank-connect flow), or the relevant value card is buried in an auto-rotating carousel. The fix is almost always "move the gate after first value," not "rewrite the copy."
5. Caveat every time: N LLM role-plays are directional, not proof. Strength = adversarial unanimity + a real funnel drop pointing at the same wall.

When the user also asks for an "adversarial UX test" alongside the synthetic panel: that is a DIFFERENT test (drive a live browser/simulator against the real paywall, record repro evidence — see the dogfood skill). It needs a reachable build/URL + test account. If you don't have one, run the synthetic panel (which needs no target), publish those findings, and say explicitly that you did NOT fabricate the browser-driven pass — name what you need to add it. Never invent UX bugs you didn't reproduce.

The strongest deliverable is predict-then-reproduce: run the panel, THEN drive the real product (web dev server + browser tools; native Capacitor app + iOS simulator) and confirm the predicted failure with before/after screenshots on each surface. Unanimity across adversarial personas + a live repro on >1 client is the best pre-ship evidence short of an A/B. Full recipe incl. how to reach the gated state on each surface (tutorial-overlay dismissal, idb logical-point taps for the Capacitor webview, backgrounded build commands): references/predict-then-reproduce-live.md. That file also covers static Surge pitch pages (tap N live phone mockups, extract verbatim copy past snapshot truncation via console innerText, click CTAs by button index, browser_vision-down fallback) and a dark-pattern taxonomy (fair vs. manipulative: demoted decline, confirmshaming, fake countdown, earned-reward discount, drip renewal, skeleton theatre) for UX-literate skeptic personas.

State to Maintain

Track these across the session:

• Character JSON (generated in step 2, may evolve mid-interview if clarified)
• 4 Ps (may be updated via autofill)
• Conversation history (researcher + persona turns only, not meta discussion)

Copy-Variant Panel Mode (parallel A/B/n testing)

For testing N copy variants (welcome messages, paywall bullets, chip wording) against multiple personas, skip the interview flow and run a parallel panel via delegate_task:

• One persona per delegated task, ALL variants inside each task. Personas must span the real segment spread (e.g. for an investing product: meme-stock retail, anxious older holder, non-English WhatsApp native, skeptical power user with existing tooling, true beginner with zero holdings). Include at least one persona the copy might EXCLUDE and one with a competing tool — they surface failures the median persona can't.
• Task prompt shape: persona description with texting style + core fear, then for EACH variant: (1) think-aloud reaction 2-3 sentences, (2) which option they tap OR what they type instead, (3) gut score 1-10. Then step out of character: rank all variants for THIS persona + single biggest insight.
• Output format line is mandatory (VARIANT N: [reaction] | TAPS: [...] | SCORE: n/10 ... then RANKING and INSIGHT) or results don't aggregate.
• For localized copy, give one persona the localized strings and ask for translation-naturalness notes — this catches gendered greetings and register problems (e.g. "vigilar" reading surveillance-y) that translation review misses.
• Aggregate by convergence, not average score. A variant that wins/places across ALL personas (including the adversarial ones) is the signal; a variant that spikes for one persona and tanks for another is a segmentation finding, not a winner. Proven result: post-answer contextual offers beat every upfront wording for all 5 personas — sequencing beats wording.
• Always state the caveat: N LLM role-plays, directional not proof. Strongest when it agrees with independent evidence (real-user research like NN/g, viral hook data).