Core Concepts

UserTold.ai is an agentic user research platform. It runs in-product interviews, captures what users say and do, extracts pain point evidence, groups evidence for review, and helps you push verified work to your tracker while keeping source evidence attached.

The Loop

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 review packets with frequency, intensity, and source context
Act — Project-aware humans or agents decide which verified packets become work and push them 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. No manual transcription, no lost insights, and no delivery handoff detached from its evidence.

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`)	Half-duplex voice conversation via OpenAI Realtime (WebRTC). The participant mic is muted while the AI speaks, then rearmed for the participant response.	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 states: pending → active → completed. 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.

Evidence is the raw material. It feeds into review packets.

Work

A review packet is a grouped set of related evidence cards. UserTold creates review packets so a builder or agent can inspect the pattern before deciding whether it should become delivery work.

A packet should answer:

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 packet is not a solution recommendation. It is triage context.

A work item is a prioritized unit of work backed by user evidence. Work items become delivery-ready only after a project-aware human or agent verifies the packet, applies current product context, and decides the issue should enter the delivery queue.

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 different user segments are affected
Evidence type — firing moments weigh more than workarounds

Work items move through: backlog → ready → in_progress → done

Newly grouped evidence starts in review/backlog. Move it to ready only after verifying the linked quotes, transcript or playback context, grouping fit, and intended product area.

Implementations

When a work item is ready, UserTold.ai can generate a spec with:

User quotes as evidence of the problem
Acceptance criteria derived from evidence types
Linear completion and recurrence context

The spec is pushed to your issue tracker (GitHub Issues or Linear) as a native issue. For Linear handoff, source evidence stays attached, completion sync resolves the current linked evidence, and future similar evidence can surface for recurrence review.

How It All Connects

Project
├── Intake (qualification)
│   └── qualifies → Interview
├── Study (interview script)
│   └── guides → Interview
├── Interview (one conversation)
│   ├── Evidence (extracted insights)
│   │   └── grouped into → Review packet
│   └── Recording, transcript, events
├── Review packet (source-linked triage bundle)
│   └── verified and promoted to → Work item
├── Work item (prioritized unit of work)
│   └── pushed to → Delivery tracker issue (GitHub or Linear)
└── Settings (tracker integration, API keys)