Core Concepts

This is the canonical 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:

Interview — AI talks to your users where they already are (embedded in your product)
Extract — Pain points are automatically pulled from every conversation as structured evidence
Review — Related evidence is grouped into draft Work in the backlog with its source context attached
Act — Project-aware humans or agents verify the Work, move it to ready, and push it to GitHub Issues or Linear
Resolve and watch — Linear completion resolves current evidence, and future interviews are watched for possible recurrence

Each piece feeds the next while the source interview stays attached. Evidence is an observation; Work is the source-linked problem being reviewed and delivered. Draft Work starts in the backlog and enters delivery only after project-aware verification moves it to ready. Linear completion resolves the current linked evidence; recurrence is a prompt to review similar future evidence, not proof that a fix worked or failed.

Projects

A project maps to one product (or product area) you want to research. Everything lives under a project: interviews, evidence, work items, intakes, and studies.

Each project has:

A public key (ut_pub_...) for embedding the widget and SDK requests
An optional tracker integration (GitHub or Linear) for pushing work items into the delivery loop

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; observe captures behavior silently, and planned talk segments debrief from that observed context:

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 guarded duplex barge-in where deployment policy permits it.	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 clean usability pattern is speak instructions -> observe silently -> talk debrief -> speak thanks/end.

Interviews

An interview is 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 so result generation and recovery do not blur what happened in the participant session. After completion, the processing pipeline kicks in automatically.

Evidence

An evidence card is a meaningful insight 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're useful for showing where the product is already working, but they don't generate work items.

Each evidence card is self-contained:

A direct quote from the participant (the anchor — everything else is context for this)
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 user's experience — never solutions or implementation direction. It stays in the user's world. Work items and solutions come later.

Work

A Work item is a source-linked product problem backed by one or more related evidence cards. Evidence grouping creates draft Work in the backlog so a builder or agent can inspect the pattern before delivery.

Work should make it possible to verify:

which evidence cards belong together
what shared user experience pattern they show
where the grouping is uncertain
how to replay or verify the source moments

The problem statement is not a solution recommendation. A Work item becomes delivery-ready only after a project-aware human or agent verifies its linked evidence, grouping, and current product context, then moves it to ready.

Priority is calculated from:

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

Work items move through: backlog → ready → in_progress → done, or close as wont_fix.

Newly grouped evidence creates Work in backlog. Move it to ready only after verifying the linked quotes, transcript or playback context, grouping fit, and intended product area. Only ready Work can be exported.

Delivery handoff

When a work item is ready, UserTold.ai can push an evidence-backed issue with:

direct observations and participant quotes
source scope and links
completion and recurrence context

Evidence alone does not prove a root cause or requirement. Linear separates direct Evidence from unverified UserTold interpretation and investigation questions. Source Evidence stays linked; completion resolves it, and recurrence can surface later.

Entity Relationships

Project
├── Intake (qualification)
│   └── qualifies → Interview
├── Study (interview script)
│   └── guides → Interview
├── Interview (one conversation)
│   ├── Evidence (extracted insights)
│   │   └── grouped into → Work
│   └── Recording, transcript, events
├── Work (source-linked problem)
│   ├── created in → backlog
│   ├── project-aware review → ready
│   └── pushed to → Delivery tracker issue (GitHub or Linear)
└── Settings (tracker integration, API keys)

The recording and interview events are the source record. Transcripts, evidence cards, Work descriptions, priorities, and generated specs are derived views that help a reviewer decide what to do; they do not replace or outrank that source.