Agent Implementation Spec — Questions Agent

> The canonical name used in code, routing, and the UI. Matches the product doc name.

1. Overview

The Questions Agent is an advisor-facing conversational agent that helps financial advisors prepare for client meetings by suggesting contextually tailored questions. The advisor describes the upcoming meeting (type, their typical approach, client background, meeting goal), and the agent returns a curated set of questions organized by question style (open, projective, scaling, follow-up). The agent also infers contextual signals (emotional themes, financial topics, relationship stage) from the advisor's description and surfaces them as a reflection. The question library is grounded in Meghaan Lurtz's 25 Questions framework, structured by meeting type × question style.

2. Entry Point

• Trigger type: user_initiated (advisor-facing, launched from Lydia dashboard or meeting prep view)
• Trigger condition: Advisor has an upcoming client meeting and wants question suggestions
• Prerequisites: Advisor is logged into Lydia. No client data required at init (client info is collected during the flow)
• Entry payload:
  • advisor_id: string — database identifier
  • session_id: string — unique session identifier
  • trigger_source: "meeting_prep" | "dashboard" | "quick_launch"

3. State Machine

State: WELCOME

Purpose: Introduce the agent, signal its purpose, transition into context gathering.

User sees:

• Agent greeting: "Hi, I'm the Questions Agent. I'm here to help you prepare for your next client meeting by suggesting questions tailored to the situation."
• Prompt: "Tell me a bit about the meeting you have coming up."
• Header pill changes from "Standby" to "Active"

Input expected:

• No input at this state (greeting auto-transitions)

Transitions:

• Auto → go to MEETING_TYPE_SELECT

Side effects:

• session_started_at timestamp written
• Header pill toggled to "Active"

State: MEETING_TYPE_SELECT

Purpose: Classify the meeting into one of five context categories that determine which question bank to use.

User sees:

• Agent asks: "First, what type of meeting is this?"
• Quick-reply buttons: "Discovery", "Monitoring", "Plan Presentation", "Introductory Meeting", "Off-track"
• After selection, a thinking signal line confirms: "Good — [selected type]."

Input expected:

• Single selection from quick replies (required)

Transitions:

• On any selection → go to ADVISOR_STYLE

Side effects:

• meeting_type written to context (canonicalized to lowercase key: "discovery", "monitoring", "plan presentation", "introductory meeting", "off-track")
• meeting_type maps to Meghaan Lurtz's meeting framework:
  • Introductory Meeting → Pre-Engagement / Establishment of Relationship
  • Discovery → Understanding Circumstances / Identifying Goals
  • Plan Presentation → Presenting the Plan & Getting Feedback
  • Monitoring → Monitoring the Plan
  • Off-track → (add-on category, not in original 25 Questions framework)

State: ADVISOR_STYLE

Purpose: Understand the advisor's existing approach and communication style so suggestions complement rather than replace their strengths.

User sees:

• Agent asks: "What do you typically ask in meetings like this? Give me a sense of the questions you already like to use."
• Hint text below input with example

Input expected:

• Free text (required; minimum ~10 chars suggested)
• Placeholder: "e.g. Goals and what's on their mind, comfortable going deep"

Transitions:

• On input → go to CLIENT_INFO

Side effects:

• advisor_style written to context
• advisor_style feeds into future skill tree / personalization logic (not yet implemented in mockup)

State: CLIENT_INFO

Purpose: Gather client context — relationship tenure, recent events, relationship quality.

User sees:

• Agent asks: "Tell me about your client — how long have they worked with you, what's your relationship like, and anything happening with them right now?"
• Hint text with example

Input expected:

• Free text (required)
• Placeholder: "e.g. Couple early 50s, client 2 years, sold business, quiet since"

Transitions:

• On input → go to MEETING_GOAL

Side effects:

• client_info written to context

State: MEETING_GOAL

Purpose: Capture the advisor's intended outcome for the meeting.

User sees:

• Agent asks: "What do you most want to achieve in this meeting?"
• Hint text with example

Input expected:

• Free text (required)
• Placeholder: "e.g. Understand what they really want beyond the numbers"

Transitions:

• On input → go to SIGNAL_INFERENCE

Side effects:

• meeting_goal written to context

State: SIGNAL_INFERENCE

Purpose: Analyze the combined context text and display inferred signals to the advisor, demonstrating the agent's reasoning.

User sees:

• Thinking signal line 1: "Reading context… scanning for signals."
• Thinking signal line 2: "Noticed: [comma-separated signal tags]" (e.g., "Noticed: anxiety, retirement, business event")
• The signal tags are derived from regex pattern matching against the concatenated context
• Agent says: "Got it. Pulling questions now…"

Input expected:

• None (automated)

Transitions:

• After signal display and agent message → go to QUESTION_DELIVERY

Side effects:

• inferred_signals written to context (array of signal tag strings)
• Signal categories detected:
  • Emotional: anxiety, optimism, overwhelm, trust gap, life transition
  • Financial: retirement, goals, estate/tax, business event, market concern, couples dynamic, family/education, debt, liquidity
  • Relationship: new relationship, established relationship
  • Default: general context

State: QUESTION_DELIVERY

Purpose: Present the curated question card organized by question style, tailored to the meeting type.

User sees:

• Milestone banner: "Questions Ready — [meeting type]"
• Question card containing:
  • Context summary: a block showing the raw inputs concatenated (advisor style, client info, goal)
  • For each question style that has questions for this meeting type:
    • Header: question style name (e.g., "Open Questions")
    • Description: why this style matters (e.g., "Open commands like 'Tell me about…' lower anxiety…")
    • 3 randomly selected questions from the bank, rendered as a list
  • Question styles displayed (in order): Open, Projective, Scaling, Follow-up
  • Each style appears only if the meeting type has questions in that category

Input expected:

• None (card is display-only)
• User can copy questions, or manually type follow-up questions in the input (disabled by default in mockup)

Transitions:

• The agent enters a terminal state after card delivery; no further prompt
• (Future: follow-up feedback loop — "Did you use any of these? How did they go?")

Side effects:

• Question card rendered in chat
• questions_delivered_at timestamp
• Full question payload logged (which questions were selected from which bank)

Terminal States

• TERMINAL_COMPLETE — Advisor received the question card. Session complete. No explicit completion milestone beyond the "Questions Ready" banner.
• TERMINAL_ABANDONED — Advisor exited mid-flow. Partial context may be discarded.

State Flow Diagram

flowchart TD
    ENTRY([Entry]) --> WELCOME

    WELCOME{Welcome} --> TYPE[Meeting Type Select]

    TYPE --> STYLE[Advisor Style]
    STYLE --> INFO[Client Info]
    INFO --> GOAL[Meeting Goal]

    GOAL --> SIGNAL[Signal Inference]

    SIGNAL --> DELIVER[Question Delivery]

    DELIVER --> T_COMPLETE([TERMINAL: complete])

    WELCOME -. "abandon at any point" .-> T_ABANDONED([TERMINAL: abandoned])

4. State / Context Model

context: {
  // Session metadata
  session_id: string
  advisor_id: string
  started_at: timestamp

  // Inputs collected from advisor
  meeting_type: string           // one of: "discovery", "monitoring", "plan presentation",
                                 //   "introductory meeting", "off-track"
  advisor_style: string          // free text: advisor's typical approach
  client_info: string            // free text: client background, relationship, events
  meeting_goal: string           // free text: what advisor wants to achieve

  // Derived / inferred
  inferred_signals: [string]     // array of signal tags from regex matching
                                 //   e.g., ["anxiety", "business event", "established relationship"]

  // Question bank selection (derived from meeting_type)
  question_bank_key: string      // matches meeting_type; falls back to "discovery"

  // Delivery metadata
  questions_delivered_at: timestamp | null
  selected_questions: {          // logged for analysis
    open: [string],
    proj: [string],
    scaling: [string],
    follow: [string]
  }
}

Field requirements by state:

5. Background Processing

Signal Inference from Context

Builds from: advisor_style, client_info, meeting_goal (concatenated) Updates: Once, after all 3 text inputs collected Output: Array of signal tag strings from 4 categories:

• Emotional: anxiety, optimism, overwhelm, trust gap, life transition
• Financial: retirement, goals, estate/tax, business event, market concern, couples dynamic, family/education, debt, liquidity
• Relationship: new relationship, established relationship
• Catch-all: general context Used for: Thinking signal display, future personalization/feedback loops

Implementation: Regex-based pattern matching (no LLM call). Each pattern tests the lowercased concatenated context text. Multiple signals can match simultaneously. If no signals match, defaults to ["general context"].

Question Selection from Bank

Builds from: meeting_type → selects the question bank sub-object Updates: Once, at question delivery Output: 3 randomly selected questions per question style available for that meeting type Used for: Question card rendering

Question bank structure:

meeting_type → {
  open:    { description, questions: [3+ items] },
  proj:    { description, questions: [3+ items] },
  scaling: { description, questions: [3+ items] },
  follow:  { description, questions: [3+ items] }
}

Each style is only present if the framework defines questions in that category for the meeting type:

• Introductory Meeting: open, proj
• Discovery: open, proj
• Plan Presentation: open, proj, scaling
• Monitoring: open, scaling, follow
• Off-track: open, proj, follow

Adapter Style / Skill Tree (Future)

Builds from: advisor_style, historical session data, explicit skill assessment Not yet implemented. The huddle notes (2026-07-10) discuss:

• A skill tree that determines which communication skills to prioritize based on advisor comfort
• Advisors nervous about emotional depth need different guidance than those confident in it
• The skill tree will eventually enable the agent to detect advisor strengths (e.g., already good at follow-ups) and adjust recommendations
• MVP uses the basic flow without skill tree; skill tree is a post-MVP enhancement

Hive-Mind Learning (Future)

Builds from: Aggregated feedback across all advisors (which questions were used, how they were rated, which elicited better client responses via transcript analysis) Not yet implemented. The huddle notes discuss using meeting transcript data to identify which question phrasings elicit longer, more useful client responses. MVP uses a simpler feedback loop.

6. LLM Interaction Model

• Prompt strategy: No LLM calls in the current mockup. The signal inference is regex-based, and the question bank is a static JavaScript object with random selection. The agent simulates reasoning with "thinking" lines.
• Future enhancement: An LLM could generate custom questions beyond the static bank, refine questions based on advisor style, or assist with signal inference. The current design intentionally keeps the core logic deterministic and transparent.
• Structured output: N/A for current mockup. Question card is rendered from static data.
• Fallback behavior: If meeting type has no matching bank key (edge case), fall back to discovery bank.

7. Outputs

7a. User-Facing Output

7b. Persisted Output

7c. Nothing Persisted

N/A — session data is logged for analysis and future personalization.

8. Loop and Retry Logic

• Satisfaction condition: Each of the 4 input states requires a non-empty response before advancing. Mockup sends the input on Enter; empty text falls back to the next canned response.
• Retry behavior: No explicit re-prompt in mockup for empty or short input. Implementation should enforce a minimum length (10 chars) with a gentle re-prompt if input is too short or appears insufficient.
• Loop limit: Each input state is visited exactly once. No looping within a state.
• Partial completion: The 4-step input sequence is short (4 questions). If the advisor abandons mid-flow, the session can be discarded. No pause/resume shown in mockup.

9. Branching Logic

Decision point: MEETING_TYPE_SELECT Condition: Which quick-reply meeting type is selected Branch A: "Discovery" → contextKey = "discovery" (question bank: open, proj) Branch B: "Monitoring" → contextKey = "monitoring" (question bank: open, scaling, follow) Branch C: "Plan Presentation" → contextKey = "plan presentation" (question bank: open, proj, scaling) Branch D: "Introductory Meeting" → contextKey = "introductory meeting" (question bank: open, proj) Branch E: "Off-track" → contextKey = "off-track" (question bank: open, proj, follow) Default: If bank key is missing (shouldn't happen with controlled input), fall back to discovery

Decision point: QUESTION_DELIVERY Condition: Which question styles exist for the selected meeting type Branch per style: Each available style (open, proj, scaling, follow) renders its header + description + 3 questions. Unavailable styles are omitted.

10. External Integrations

Integration fallback:

• No CRM access → advisor types client info manually (current mockup behavior)
• No calendar access → advisor selects meeting type manually (current mockup behavior)
• All inputs are free-text in MVP; no external system is required

Purple Lydia behavior:

• All context inputs are manual (free text)
• No signal inference from real client data (but regex inference from typed text still works)
• No historical advisor data for personalization

11. Error States and Edge Cases

12. Guardrails and Safety Checks

• What the agent must never say or do: Never suggest questions that could be harmful, manipulative, or elicit traumatic responses. Never diagnose the client. Never contradict the advisor's professional judgment. Never suggest questions that ask the client to disclose legally protected information (health, specific asset values in initial meetings).
• Input validation: No technical validation on advisor inputs. Free text is accepted as-is.
• Output review gates: The question bank is curated by a human expert (Meghaan Lurtz, Ph.D.). No LLM-generated questions in MVP, so output quality is bounded by the curated bank. When LLM-generated questions are added (future), an output gate must verify appropriateness.
• Escalation triggers: If signal inference detects client distress language, the agent could flag that the meeting may need a different approach. Currently not implemented.

13. Observability

• State transitions: Each input state logged with timestamp, session ID, and input length
• LLM calls: None in current MVP
• Context fields in session record: meeting_type, advisor_style (length + truncated), client_info (length + truncated), meeting_goal (length + truncated), inferred_signals, selected_questions (exact list), completion_status
• Quality signals: Session completion rate, meeting type distribution, average input length per field (proxy for engagement), question styles used per meeting type. Future: explicit feedback (thumbs up/down on card, "Did you use these?" follow-up)

14. Open Questions