Agentic Loops
How UserTold moves from a research plan to source-linked product work:
Study → Interview → Evidence → Finding
See Core Concepts for the product model, MCP Integration for the agent workflow, and /api/openapi for REST contracts.
1. Study
A Study defines what the team wants to learn and how the Interview should run. Its script can combine three modes:
- speak delivers fixed instructions or transitions;
- observe gives the participant uninterrupted time to use the product;
- talk conducts an adaptive interview and can debrief observed behavior.
The Project widget is installed once. Active Studies use their Invitation and Visibility settings to decide where and when an Interview can begin. Pausing or closing a Study stops new Interviews without interrupting one already in progress.
2. Interview
An Interview follows the Study flow and captures the sources the participant consented to share. Depending on the browser, device, and permissions, those sources can include voice, transcript, in-page behavior, page context, and a participant-approved screen recording.
Capture gaps remain visible. A denied permission, interrupted Interview, unsupported screen-share environment, or processing failure does not become inferred Evidence.
Agents can inspect a focused transcript and behavior window around a source moment. They can also request short-lived direct links for available transcript, captions, audio, screen, and event artifacts; artifact bytes are not carried inside MCP tool output.
3. Evidence
Completed Interviews produce source-linked Evidence from what participants said and did. Evidence keeps its source Interview and timestamp so a reviewer or agent can return to the captured record.
Evidence separates:
- the participant's quote;
- observed behavior and context;
- generated or reviewer-authored interpretation;
- review state and links to Findings.
Agents can filter and inspect Evidence, add an annotation, dismiss an unsupported item with a reason, or restore it. Editing review state does not rewrite the captured source.
4. Finding
Related Evidence can support a concise Finding about one underlying product problem. The Finding keeps its Evidence links and can be refined as the team checks source fidelity, grouping, applicability, uncertainty, and current product behavior.
Updating a Finding changes UserTold only. Sending it is a separate, explicit action. By default UserTold selects the Project-configured GitHub or Linear destination; the caller supplies a provider only to override that choice.
When a linked Linear issue reaches a product outcome, UserTold reflects that delivery state while preserving the research record. Later similar Evidence remains available for recurrence review rather than being treated as automatic proof of impact.
Continue with the Quickstart for a first Study or For Agents to choose an agent surface. CLI and MCP describe their current capabilities through built-in discovery.