Core Concepts

The product model for UserTold.ai: the entities, lifecycle, and boundaries that connect in-product research to evidence-backed delivery work.

The Product Lifecycle

Most research ends with a report. UserTold.ai closes the loop:

Study — define the research and placement
Interview — preserve what the participant said and did as the source
Evidence — extract source-linked analysis
Finding — review a synthesis of related Evidence
Delivery — explicitly send a reviewed Finding; review alone creates no external work
Resolve and watch — Linear completion resolves Evidence and future Interviews reveal recurrence

Projects

A project maps to one product (or product area) you want to research. Everything lives under a project: Studies, Intakes, Interviews, Evidence, and Findings.

Each project has:

A public key (ut_pub_...) for embedding the widget and SDK requests
An optional tracker integration (GitHub or Linear) for explicitly sending reviewed Findings to product triage or delivery

Intakes

An intake is a qualification funnel. Before someone enters an interview, the intake asks a few questions to make sure they're the right participant.

Intakes support:

Multiple question types (text, choice, number, rating)
Qualification rules (automatically qualify or disqualify based on answers)
Capacity limits (stop after N qualified participants)
Consent collection
Custom branding (color, welcome message, thank-you message)

When a participant qualifies, an interview is automatically created and begins.

Studies

A study is the interview script — what the AI should explore with participants. Studies define:

Goals — what you want to learn (e.g., "Understand why users abandon checkout")
Segments — phases of the interview, each with a different interaction style

Conductor Modes

Each segment runs in one of three modes; the study script controls the order:

Mode	Behavior	Best For
Talk (`talk`)	Voice conversation via OpenAI Realtime (WebRTC). The participant mic is muted while the AI speaks by default; studies can opt into native duplex with browser echo cancellation and Realtime VAD.	Deep discovery, probing
Speak (`speak`)	The AI delivers a scripted one-way transition message via TTS playback. Participant mic feeds STT transcription.	Task setup, transitions, thanks
Observe (`observe`)	Silent product-usage capture. Text instruction card shown; speech, clicks, navigation, and available page context are preserved for evidence and debrief.	Usability testing

The usual usability pattern is speak instructions -> observe silently -> talk debrief -> speak thanks/end.

Interviews

An interview is the source record for one conversation with one participant. It captures:

Voice recording (transcribed automatically)
Screen recording (optional)
User interactions (clicks, navigation)
Chat messages
The full transcript

Interviews move through lifecycle states: pending, active, completed, abandoned, or error. Processing status is tracked separately from these states. After completion, the processing pipeline kicks in automatically.

Evidence

An evidence card is a single user moment extracted from an interview. The AI analyzes each completed interview and pulls out one or more of these types:

Evidence Type	`signal_type` value	What It Means
Struggling Moment	`struggling_moment`	The user hit friction, failed a task, or expressed confusion
Desired Outcome	`desired_outcome`	What the user actually wants to accomplish
Hiring Criteria	`hiring_criteria`	Why they chose your product (or a competitor)
Firing Moment	`firing_moment`	What would make them stop using your product
Workaround	`workaround`	A substitute behavior they invented because the product doesn't solve it
Emotional Response	`emotional_response`	A strong positive or negative reaction
Critical Error	`critical_error`	A blocking failure (broken flow, dead end, lost data) observed in product
Recovery Success	`recovery_success`	The user got unstuck — useful to mark where the product already helps
Smooth Completion	`smooth_completion`	The user completed a task with no friction (positive evidence)
No Issue Found	`no_issue_found`	The analyzer ran but found no extractable evidence in this window
Decision Point	`decision_point`	A moment where the user weighed alternatives or hesitated before committing

Use the signal_type value when filtering via API (?type=struggling_moment), CLI (usertold evidence list --type struggling_moment), or MCP (evidence.list { projectRef: 'org/project', signal_type: 'struggling_moment' }). no_issue_found and smooth_completion are positive Evidence — they show where the product already works, and they do not generate Findings.

Each evidence card is self-contained:

A direct quote from the participant (the anchor; everything else is context)
Where it happened — page URL, page title, visible UI element
What the user was doing — their goal at that moment and the preceding actions
What happened after — did they recover, give up, or find a workaround?
A confidence score (how certain the AI is)
An intensity score (how strongly expressed)

Evidence describes the participant's experience — never solutions or implementation direction. Findings synthesize potentially meaningful patterns; product triage and solutions come later.

Findings

A Finding is a source-linked synthesis backed by one or more Evidence cards. Grouping creates draft Findings for review. The canonical Findings API and current public clients use Finding vocabulary; some legacy HTTP compatibility identifiers and internal storage still use tasks, task_signals, and tsk_ references.

A Finding keeps its Evidence links, shared user-experience pattern, uncertainty, and source moments reviewable.

The synthesis is not a solution. A project-aware human or agent chooses Review after checking the Evidence, grouping, product context, and uncertainty. Review does not create external work. Legacy API and MCP clients store this as status: ready.

Priority is calculated from:

Frequency — how many interviews mention this issue
Recency — how recently it was mentioned
Intensity — how strongly participants expressed it
Evidence type — firing moments weigh more than workarounds

Research state (draft, reviewed, closed) and delivery state are independent. Product triage decides whether a reviewed Finding becomes delivery work. Linear delivery distinguishes awaiting product triage, accepted into delivery, completed, declined, and duplicate. Legacy task status remains storage input; decision records expose the lifecycle without changing their existing decision rules.

Newly grouped Evidence creates a draft Finding in legacy backlog. Only reviewed Findings can be sent explicitly.

Delivery handoff

An explicit send creates an evidence-backed issue. Linear uses native Triage or an explicit Backlog fallback; both mean awaiting product triage, not accepted delivery. GitHub remains a direct delivery handoff. Completion, declined, and duplicate remain distinct; UserTold does not follow a duplicate's canonical issue here.

Entity Relationships

Project
├── Intake (qualification)
│   └── qualifies → Interview
├── Study (interview script)
│   └── guides → Interview
├── Interview (one conversation)
│   ├── Evidence (extracted insights)
│   │   └── grouped into → Finding
│   └── Recording, transcript, events
├── Finding (source-linked synthesis; compatibility-backed storage)
│   ├── research state → draft / reviewed / closed
│   └── explicit send → Linear intake or GitHub delivery
└── Settings (tracker integration, API keys)

The recording and Interview events are the source record. Transcripts, Evidence cards, Finding descriptions, priorities, and generated specs are derived views; they do not replace that source.