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 optional. It asks qualification questions that decide whether someone can enter the linked Study; skip it when qualification is unnecessary.

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 defines what you want to learn, who can participate, and the interview flow. Its script includes:

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 GPT-Live over WebRTC. The participant mic stays open with browser echo cancellation while GPT-Live handles voice activity and interruptions.	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 describes a source moment from an interview. After processing, an interview may produce cards 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, observed behavior, or both
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 summarizes a user problem or pattern supported by one or more Evidence cards. UserTold groups related Evidence into drafts for review.

Open the linked source moments and check the summary against the current product. Correct the grouping if needed, then choose Review. Sending a reviewed Finding to a tracker is a separate action.

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) is separate from delivery state. A reviewed Finding can stay in UserTold while your team decides what to do next.

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 (summary with linked Evidence)
│   ├── 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.