Study Runtime

UserTold interviews capture real product usage, preserve what participants say and do, ask planned follow-up questions, extract reviewable evidence, route work, and watch future interviews for recurrence after Linear completion.

During observation, the runtime stays silent, then hands that context to a talk debrief.

Three Segment Modes

Every segment uses one participant-facing mode.

Observe

The participant uses your product while UserTold captures product usage, speech, clicks, navigation, and available snapshots. The assistant stays silent. Pauses, loops, confusion phrases, and help requests are preserved as evidence for interpretation and debrief.

Best for: usability testing, task completion studies, real workflow observation.

Speak

The assistant delivers a scripted one-way message. Use it for intros, task instructions, transitions, and thanks. It is not a live help mode.

Best for: task handoffs, consent reminders, short setup or wrap-up messages.

Talk

The assistant conducts an active realtime interview. It asks questions, follows up, and can call complete_segment when the planned conversation segment is done.

Best for: discovery interviews, context conversations, and debriefing after an observation segment.

Observe To Talk Handoff

speak gives the task instructions.
observe captures behavior without interruption.
When realtime_analysis is enabled, the runtime periodically turns recent speech, site behavior, and page changes into a running private evidence note in Markdown.
talk starts immediately from the latest valid evidence checkpoint, or from a short fallback when there is no checkpoint. It does not wait for a model call or receive a raw transcript or action log.
Late analysis updates reach the debrief only if they change the picture, so the interviewer does not restart mid-question.
The realtime interviewer combines evidence with the assigned goals and calls complete_segment when further questions would not improve the record.
Final speak thanks the participant or closes the interview when the script calls for it.

The participant's struggle stays visible for debrief and extraction.

Deterministic Advancement

Production scripts advance only by deterministic criteria:

max_duration_s
user Done / step_done
url:<substring>
action:<selector-or-pattern>
complete_segment for talk segments
scripted speak completion

Use URL and action rules when the product exposes a clear completion signal. Use max_duration_s as a safety valve for observation. In talk, the runtime sends a private wrap-up instruction one minute before max_duration_s; the assistant should finish naturally and call complete_segment before the hard limit force-advances. Goals guide analysis and planned debriefs, not observe-mode advancement.

Designing Studies

Usability

{
  "segments": [
    { "id": "intro", "mode": "speak", "title": "Task instructions", "speak_text": "Please complete checkout and think aloud as you go." },
    { "id": "task", "mode": "observe", "title": "Complete checkout", "instruction": "Complete checkout from cart to confirmation.", "conductor_context": "Capture hesitation, errors, page paths, and recovery behavior for the debrief.", "advance_when": "url:/success", "max_duration_s": 420 },
    { "id": "debrief", "mode": "talk", "title": "Discuss experience" },
    { "id": "thanks", "mode": "speak", "title": "Thanks", "speak_text": "Thanks for completing the interview." }
  ]
}

Discovery

Use planned talk segments when the research question is conversational. Split long interviews into focused segments with clear goals so complete_segment has a natural boundary.

How It Connects To Evidence Extraction

After the interview, the captured record feeds evidence extraction:

transcript and participant quotes
navigation and interaction history
observation context and page snapshots
study goals and segment timing
planned debrief answers grounded in observed behavior

This separation keeps the live runtime predictable while still giving extraction enough evidence to explain friction, desired outcomes, workarounds, and recovery.