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 identifiersession_id: string — unique session identifiertrigger_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 contextadvisor_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:
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:
| State | Required | Optional |
|---|
| MEETING_TYPE_SELECT | meeting_type | — |
| ADVISOR_STYLE | advisor_style | — |
| CLIENT_INFO | client_info | — |
| MEETING_GOAL | meeting_goal | — |
| SIGNAL_INFERENCE | all previous fields | — |
| QUESTION_DELIVERY | all previous fields | — |
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
| Artifact | Format | Rendered | Dynamic | Audience |
|---|
| Context summary block | Text block in card | Inline in card | All 3 advisor inputs concatenated | Advisor-only |
| Question lists | 3 questions per style, each as a list item | Inline in card, organized by style header | Random selection from static bank; description text templated per style | Advisor-only |
| Thinking signal lines | Italic text with ⟳ icon | Inline in chat | Regex-matched signal tags | Advisor-only |
| Milestone banner | Gradient banner | Inline in chat | Templated with meeting type name | Advisor-only |
7b. Persisted Output
| Destination | Data Written | Triggers Downstream |
|---|
| Session log | Full session record: meeting type, advisor style, client info, goal, inferred signals, selected questions, timestamp | Quality evaluation, future skill tree / hive-mind training |
| Advisor activity feed | Minimal: { advisor_id, session_id, meeting_type, completed_at } | Usage analytics |
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
| System | Operation | Data | Required / Optional | Purple Lydia | Integrated Lydia |
|---|
| CRM | read | client record (for pre-populating client info) | optional (not used in mockup; advisor types manually) | no | future |
| CRM | read | advisor profile (for skill tree / personalization) | optional | no | future |
| Meeting calendar | read | upcoming meeting details (type, client, time) | optional | no | future |
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
| Condition | Agent behavior |
|---|
| Advisor provides very short inputs | Mockup accepts any text. Implementation should re-prompt gently for more context |
| Advisor selects a meeting type but then corrects themselves mid-flow | No correction mechanism in mockup. Implementation should support starting over |
| Question bank for selected meeting type has fewer than 3 questions in a style | Return all available questions instead of 3; don't duplicate |
| Advisor types min-length responses through all 4 inputs | Questions card still renders; quality depends on input richness |
| Advisor asks a question instead of answering the prompt | No handling in mockup. Future: agent could detect and redirect |
| Session timeout (advisor walks away mid-flow) | Not handled in mockup. Future: session timeout with save-and-return |
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
| Question | Priority | Owner |
|---|
| Should the agent offer pre-populated context from CRM/calendar (client name, meeting type, recent notes) in future versions? | Medium | Product |
| How does the skill tree work — self-assessment quiz, observed behavior scoring, or both? | High | Product / Research |
| What is the feedback mechanism after question delivery — in-line rating, follow-up prompt, or async survey? | Medium | Product |
| Should the Off-track meeting type be added as a standard meeting type in Meghaan's framework, or is it specific to this agent? | Low | Product |
| Should the question bank evolve via LLM augmentation, or remain curator-maintained? | Medium | Product / Engineering |
| Should the agent support "quick mode" (just meeting type + client info, skip style/goal) for busy advisors? | Medium | Product |
| Should questions be filterable by style after delivery (e.g., "show me only scaling questions")? | Low | Product |
| How should the agent handle group meetings (multiple stakeholders, family dynamics) vs. individual client meetings? | Medium | Product |