Methodology

UserTold.ai captures behavioral evidence from real interviews — what users actually did, said, and struggled with — and structures it into machine-readable evidence your agent can reason over.

Evidence Anatomy

An evidence card is a structured observation extracted from an interview. Each card links back to a transcript timestamp and interview recording.

Type	Description
`struggling_moment`	User hits friction, fails a task, or expresses confusion.
`desired_outcome`	User states what they actually want to accomplish.
`workaround`	User invents a substitute behavior to work around a gap.
`context`	Background information about the user's environment or habits.
`other`	Notable behavioral or emotional observation that doesn't fit the above types.

Example quotes:

struggling_moment: "I tried this three times and still can't find billing settings."
desired_outcome: "I just want to export this to CSV without all these extra steps."
workaround: "I usually copy it into a spreadsheet and filter it there."
context: "We run this process every Monday morning before the team standup."
other: "They paused for 30 seconds and then refreshed the page."

Evidence JSON

{
  "id": "sig_abc123",
  "type": "struggling_moment",
  "quote": "I tried this flow three times...",
  "confidence": 0.91,
  "session_id": "ses_xyz789",
  "timestamp_ms": 142300
}

Every evidence card is typed JSON with confidence scores. Your agent reads these via evidence.list (MCP) or usertold evidence list --format json (CLI).

Study Modes

Studies define the interview structure. Each study is a sequence of segments, and each segment uses one of three modes:

Talk — Conversational interview. The AI asks questions and follows up. Best for discovery interviews, debriefs, and understanding context.

Observe — Screen + voice recording while the user completes a task. The assistant stays silent and preserves stuck moments as evidence.

Speak — AI delivers a scripted one-way message out loud. Used for intros, task instructions, transitions, and thanks.

Study Block Patterns

Start from the block sequence that matches the evidence you need:

Talk-only — Planned talk segments for discovery interviews, recent behavior, alternatives considered, and decision criteria.

Task observation — Speak intro + observe task + talk debrief + speak thanks. Replace the task instruction with the actual product behavior you need to observe.

Context then observation — Talk context + observe task or demo + talk probing. Best when you need to understand routines before watching the participant work.

The Evidence Chain

Evidence flows through a structured pipeline:

Evidence → Review packet → Verified work item → Tracker Issue → Resolved Evidence → Recurrence Watch

Evidence: A structured observation from an interview. Linked to transcript timestamp and interview recording.
Review packet: A cluster of related evidence grouped by theme. Has title, description, priority context, evidence links, and source moments to inspect.
Verified work item: A project-aware human or agent checks the linked quotes, transcript or playback context, grouping fit, and product area, then promotes only action-ready packets to delivery work.
Tracker Issue: Created by work.push after verification. Lands in GitHub Issues or Linear with evidence quotes, evidence counts, priority, and interview context.
Resolved Evidence: Linear completion resolves the current linked evidence.
Recurrence Watch: Future similar evidence can resurface for review without claiming attribution.

Evidence vs. Surveys