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):

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

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):
   • --count N — Panel size (default: 5; not applicable for ask)
   • --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.
   • --segments — Activate segment-driven flow; default panel size becomes 15 (not applicable for ask)
   • --panel PANEL — (ask only) Specify the panel survey-id to use (e.g., running-footwear-us-15p-2026-04). Skips auto-detection.
3. 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:

   • Command (concept-test or generate)
   • Free-text research intent (if provided)
   • Panel size (default: 5; or 15 if --segments)
   • Market (default: United States; resolve shorthands like jp → Japan)
   • Mode: topic-only (default) or segment-driven (--segments)

2. Collect missing info:

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

3. 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