persona

AI Persona Panels for Customer Research

Build reusable persona panels, ask open-ended customer questions, and run concept tests on messages, offers, and product ideas.

3-Step Workflow

Inspired by TinyTroupe (Generate Personas → Simulate Interactions → Extract & Analyze):

| Step | What happens | Component | |------|-------------|-----------| | 1. Build Panel | Define your market, generate diverse personas | Panel Builder | | 2. Run Ask / Concept Test | Each persona responds independently in its own subprocess | Simulation Engine | | 3. Review Findings | Structured report with themes, cross-tabs, charts, and verbatims | Analysis Pipeline |

Recommended workflow:

1. /persona generate — build a reusable panel
2. /persona ask — explore motivations, barriers, language, and decision criteria
3. /persona concept-test — compare explicit options when ready for a structured choice task

Quality Guidelines

• Take your time with persona generation. Diverse, detailed personas are the foundation of useful results. Do not skip diversity verification.
• Do not skip validation. Always verify response JSON structure before proceeding to analysis.
• Quality over speed. A 5-persona panel with rich, differentiated responses is more valuable than a 15-persona panel with generic answers.

Quick Reference

| Command | What it does | |---------|-------------| | /persona generate Running shoe shoppers in the US | Build a reusable panel (default 5 personas) | | /persona generate --count 10 Gen Z skincare shoppers in the US | Panel with custom size | | /persona generate --segments Canned coffee drinkers in Japan | Segment-driven panel (default 15) | | /persona ask What frustrates you most about choosing skincare products? | Explore motivations and barriers | | /persona ask Why would you ignore an ad for a new running shoe? | Qualitative reaction before concept test | | /persona concept-test Compare 3 running shoe concepts | Concept test — concepts provided interactively | | /persona concept-test --market japan Evaluate 3 canned coffee concepts | Concept test with Japanese panel |

ask explores open-ended motivations, barriers, and language. concept-test covers any comparison research: product concepts, messaging A/B, packaging, competitive comparisons, feature bundles, and value framing with price context.

For detailed input requirements and output descriptions per command, see references/command-details.md.

Argument Parsing Rules

The text after the command is parsed as follows:

1. Command (required): concept-test, generate, ask
2. Options (optional):
3. --count N — Panel size (default: 5; not applicable for ask)
4. --market MARKET — Target market/country (default: us). Accepts country codes (us, japan/jp, uk, de, fr, cn, kr) or freeform descriptors ("Southeast Asia", "urban Brazil"). Shorthand codes are expanded: us → United States, japan/jp → Japan, uk → United Kingdom, etc.
5. --segments — Activate segment-driven flow; default panel size becomes 15 (not applicable for ask)
6. --panel PANEL — (ask only) Specify the panel survey-id to use (e.g., running-footwear-us-15p-2026-04). Skips auto-detection.
7. Free text (optional): Everything else is the research intent — a natural language

description of what the user wants to research. For ask, the free text is the question itself.

Parsing examples:

/persona concept-test Evaluate 3 new canned coffee concepts
  → type: concept-test, count: 5, intent: "Evaluate 3 new canned coffee concepts"

/persona concept-test --count 8 Compare ad headlines for EV launch
  → type: concept-test, count: 8, intent: "Compare ad headlines for EV launch"

/persona concept-test --segments Canned coffee
  → type: concept-test, count: 15, mode: segment-driven, intent: "Canned coffee"

/persona generate --count 15 Running shoes
  → type: generate, count: 15, market: "United States", intent: "Running shoes"

/persona generate --market japan --count 10 Canned coffee
  → type: generate, count: 10, market: "Japan", intent: "Canned coffee"

/persona concept-test --market japan Evaluate 3 new canned coffee concepts
  → type: concept-test, count: 5, market: "Japan", intent: "Evaluate 3 new canned coffee concepts"

/persona ask What frustrates you most about buying running shoes online?
  → type: ask, question: "What frustrates you most about buying running shoes online?", panel: auto-detect

/persona ask --panel running-footwear-us-15p-2026-04 Why would you ignore this ad?
  → type: ask, question: "Why would you ignore this ad?", panel: "running-footwear-us-15p-2026-04"

/persona ask --market japan What makes this product feel overpriced?
  → type: ask, question: "What makes this product feel overpriced?", market: "Japan", panel: auto-detect

When free text is provided:

• Extract the topic from the intent text
• Determine what information is still missing:
• concept-test: concept/option details (names + descriptions) — ask only if not in intent
• ask: the question is the free text; no additional info required
• If sufficient information is present, proceed without further questions

When no free text is provided:

• Collect all required information interactively (current behavior)

Orchestration Logic

Step 1: Build Panel

1. Parse the user's request to determine:
2. Command (concept-test or generate)
3. Free-text research intent (if provided)
4. Panel size (default: 5; or 15 if --segments)
5. Market (default: United States; resolve shorthands like jp → Japan)
6. Mode: topic-only (default) or segment-driven (--segments)

1. Collect missing info:
2. Extract topic from free text (e.g., "Evaluate 3 new canned coffee concepts" → topic = "Canned coffee")
3. For concept-test: identify concept/option details — ask only if not provided
4. If free text provides sufficient context, skip interactive questions

1. Persona Panel Decision:

a) User explicit instruction:

• "Use existing panel" / "reuse {name}" → load from specified personas/{survey-id}/ directory
• "Generate new personas" or provides segment definitions → new generation
• No instruction → proceed to auto-decision (b)

b) Auto-decision (default is NEW generation):

• Scan personas/ for subdirectories containing manifest.json (ignore _archive/)
• If a manifest's category closely matches the current topic AND market matches (or is absent, treated as "United States") → propose reuse, ask user
• If no match found → proceed directly to new generation (no confirmation needed)

c) New generation flow — two modes:

Topic-only mode (default):

• Skip segment inference entirely
• Infer diversity dimensions inline and generate all N personas in one batch
• See references/topic-only-generation-flow.md for the 4-step flow

(dimension inference, target assignment, generation, manifest creation)

• Do NOT ask user for segment approval — proceed directly

Segment-driven mode (--segments):

• If user provided segment definitions → use them directly
• If topic only → run segment inference (see references/segment-inference-prompt.md)

to generate 3-4 segments → present to user for approval

• Default panel size: 15 personas (3 segments × 5 personas)
• Follow the 4-step generation flow below

### Segment-Driven 4-Step Generation Flow

Inspired by TinyTroupe's TinyPersonFactory plan-based approach: instead of letting the LLM freely generate N personas per segment, first build a deterministic sampling plan, then generate each persona from its slot specification.

Step 1a: Deterministic Count Allocation

Compute per-segment counts deterministically — do NOT delegate count management to the L