/planning-voice-agent-user-interviews

name: planning-voice-agent-user-interviews
description: 'Plan a round of user interviews conducted by PostHog''s AI voice agent (a "robo interviewer") — the automated voice-agent interview product. Captures a UserInterviewTopic (who to target, what to ask, framing context, question list) and calls user-interview-topics-create. ONLY trigger when the user clearly wants an AI voice agent to actually run the interview calls (e.g. "set up robo user interviews", "have the voice agent interview these users"). Do NOT trigger for ordinary user research that does not involve the voice agent — finding or shortlisting users to talk to ("who''d be a good fit to interview about Y"), planning questions for a human-run interview, or analysing feedback are audience discovery, handled with normal data queries, not this skill. Also do NOT trigger for uploading a recorded interview audio file or browsing topics with user-interview-topics-list. When intent is ambiguous, first confirm what kind of research it is and whether they want an AI voice agent to conduct it (see Step 0).'

Planning voice-agent user interviews

Use this skill **only** when someone wants PostHog's AI voice agent — a "robo interviewer" — to actually conduct a round of user interview calls for them. The plan is captured as a `UserInterviewTopic` that the voice agent later runs through, calling each targeted person and working through the questions.

This is a specific product, not a generic research helper. If the user only wants to _find_ or _shortlist_ people to interview, plan questions for an interview a human will run, or analyse feedback they already have, this is **not** the right skill — handle that as ordinary audience discovery / data work (see `querying-posthog-data`) and, at most, mention that the voice-agent option exists.

Step 0: Confirm this is the voice-agent flow

Before doing anything else, make sure the user actually wants the AI voice agent to run the interviews. Many requests that mention "interviewing users" are really about discovering _who_ to talk to, not about handing the conversation to a robot.

• If the user explicitly asked for the voice agent / robo interviews / automated calls, proceed to Step 1.
• If they only asked to find or rank users to interview (e.g. "who'd be a good fit to interview about the inbox?"), treat it as audience discovery: answer it with normal queries and **do not** create a topic. You may add a one-line offer afterwards, e.g. _"If you want, I can set these up as automated interviews run by PostHog's AI voice agent — want me to do that?"_
• If intent is ambiguous, ask first, e.g. _"Quick check on what you're after: what kind of user research is this, and do you want PostHog's AI voice agent to actually run the interviews (it calls people and works through your questions)? Or did you just want me to find the right users to talk to?"_

Only continue past this step once the user has confirmed they want the voice agent to conduct the interviews.

What a complete topic needs

Before calling `user-interview-topics-create`, gather these:

1. **Who to interview** — at least one of:

• `interviewee_emails` — list of email addresses
• `interviewee_distinct_ids` — list of PostHog distinct IDs

2. **What to ask about** — `topic` (required free text) 3. **How the agent should frame the conversation** — optional `agent_context` (extra system prompt) 4. **The questions to work through** — optional ordered `questions` list

Topics snapshot their audience at create time — there is no live cohort link. If the user names a cohort, you (the agent) resolve cohort members to emails/distinct_ids before calling `user-interview-topics-create`. See Step 2 for the resolution flow and the 500-member cap UX.

The API rejects topics with no targeting, so `interviewee_emails` and/or `interviewee_distinct_ids` must end up non-empty.

Step 1: Clarify intent

If the request is vague, ask:

• **Which feature or behavior?** "checkout" might be the button click, the page view, or the payment submission — narrow it down to one event.
• **What do you want to learn?** Why they bounced? What confused them? What alternatives they tried? The goal shapes both the audience and the questions.
• **Which kind of users?** Heavy users (what works), drop-offs (what blocks adoption), at-risk users (what breaks retention), or a mix.

Skip these questions only when the user has already answered them.

Step 2: Pick the audience

Map what the user said to one of these paths:

• **They named a cohort** ("our power users", "trial signups last week") — use `cohorts-list` (or a `system.cohorts` SQL search) to find the cohort, confirm the match, then resolve cohort members to emails/distinct_ids (see "Resolving a cohort" below).
• **They described the kind of person but no cohort exists** — offer to either create the cohort first (`cohorts-create`), then resolve it, or fall back to finding people by behavior (see below).
• **They gave email addresses or distinct IDs** — accept them directly. Skip the cohort lookup.
• **They described a behavior, not a cohort** ("users who tried checkout but didn't finish", "people who used to use dark mode and stopped") — find them by querying their events (see below).
• **They were vague** ("a few customers", "some power users") — ask which they prefer:
• Pick an existing cohort → `cohorts-list`
• Look up specific persons by name or email → `persons-list` with a search query
• Find users by behavior → see below
• Paste a list of email addresses

Each email passes through DRF email validation (display-name format `Paul D'Ambra <paul@x.com>` is accepted alongside plain `paul@x.com`).

Resolving a cohort

Topics snapshot their audience at create time. When the user picks a cohort, you must materialize the member list into `interviewee_emails` (and `interviewee_distinct_ids` for members without emails) before creating the topic.

1. **Count the cohort first.** Cheap query, decid