Study Runtime

UserTold interviews are evidence-first: 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. Clean studies capture behavior, then hand that context to a focused talk debrief.

Three Segment Modes

Every segment uses one participant-facing mode.

Observe

The participant uses your product naturally 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 scripted one-way transition text. 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, listens, follows up, clarifies, 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

The evidence-first follow-up mechanism is observe-to-talk handoff:

  1. speak gives the task instructions.
  2. observe captures behavior without interruption.
  3. When realtime_analysis is enabled, the runtime periodically turns bounded speech, site behavior, and page deltas into cumulative private evidence Markdown.
  4. talk starts immediately from the latest valid evidence checkpoint or a small evidence-unavailable fallback. It does not wait for a model call or receive a raw transcript or action log.
  5. After the observation input closes, only a materially changed final evidence checkpoint may update the active talk segment.
  6. The realtime interviewer combines evidence with assigned goals, follows productive grounded episodes, and calls complete_segment when further questions would not improve the record.
  7. Final speak thanks the participant or closes the interview when the script calls for it.

This keeps the research record clean. The participant's struggle remains 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.

See also