70-docs/30-engineering/discovery-script.md

Discovery Conversation Script

⚠️ Design intent, not the present-state map. The turn-by-turn script and adaptive rules below capture the discovery intent; the implementation is now a single Gemini 2.5-flash call per turn with function-calling tools (backend/single_brain.py / brain_tools.py) — there is no scripted question renderer, no orchestrator, no sales_brain / qa_brain split, and no separate faithfulness judge. Present-state authority: README.md §4.

The 10-turn fact-find that turns a stranger into a profiled buyer.

Design principles (inspired by Even.in's tone + insurance-sector buyer-research norms):

1. Plain language. No "PED", no "UIN", no "sub-limit". We're talking to an adult who hasn't read a policy wording end-to-end.
2. Every question explains WHY we're asking. A form feels invasive; a conversation feels helpful. The one-line why-this-matters subtitle is non-optional.
3. Chips, not text boxes. Multi-choice + sliders + toggles. Free-text only when no chip set is honest.
4. Honesty pre-commitment. Right after the first turn, the bot tells the user: "Tell me the truth, even on hard things. Your honest answer protects your claim later — not just my recommendation."
5. Optional, not gated. The user can stop at any time. We surface what we can with partial profiles (insurer-level CSR / complaints) but ONLY personalize the scorecard once profile_completeness >= 0.6.

---

Turn-by-turn script

Turn 0 — Welcome (the bot starts)

"Hi — I'm here to help you find a health policy that genuinely fits you, not the one that pays the highest commission to a broker. I'll ask about 8–10 short questions. Some will feel personal (your health, what you earn). Be honest — every answer is private to this chat, and being upfront about your medical history is the single biggest thing that protects you when you actually need to claim. Ready?"

[Chip: "Let's start" · "Tell me how this works first" · "Just let me browse"]

Turn 1 — Age

"What's your age?"

Why we ask: premium, eligibility, and renewability all hinge on this.

[Slider 18–80, step 1]

Turn 2 — Who's covered

"Who else do you want to cover?"

Why we ask: covering parents or kids changes which policies make sense — some plans price family floaters very differently.

[Multi-select chips: "Just me", "Spouse", "Children", "Parents", "Parents-in-law"]

Turn 3 — Parents' health (CONDITIONAL — only if Turn 2 included parents)

"If you're covering parents, what's the older one's age, and do they have any pre-existing conditions like diabetes, BP, or heart issues?"

Why we ask: parents-with-PED need policies with shorter PED waiting periods and lifelong renewability — that narrows the field a lot.

[Slider for age + chips: "None", "Diabetes", "Hypertension/BP", "Heart", "Cancer", "Thyroid", "Multiple"]

Turn 4 — Your own conditions

"Any pre-existing conditions for yourself? Diabetes, BP, thyroid, asthma, anything chronic?"

Why we ask: this is where honesty matters most. Hiding it gets your premium ₹500 cheaper today and a denied claim of ₹8 lakh later. Insurers can and do find out at claim time.

[Multi-select: "None", "Diabetes", "BP/Hypertension", "Thyroid", "Asthma", "Heart", "Cancer history", "Other"]

Turn 5 — Existing cover

"Do you already have any health insurance — through your employer or that you bought yourself?"

Why we ask: if you already have ₹5L from work, you might need a top-up rather than a full base plan — different product, different price.

[Chips: "None", "Employer only", "Personal policy", "Both" → if any, ask sum insured slider]

Turn 6 — City

"Which city or town?"

Why we ask: cashless hospital network density varies massively. A "16,000-hospital network" means nothing if none are near you.

[Free text + autocomplete] OR [Chips: "Metro", "Tier-1", "Tier-2", "Tier-3 / smaller town"]

Turn 7 — Budget

"Roughly what annual premium budget feels comfortable?"

Why we ask: helps us rank — but if a slightly higher budget materially improves your protection, we'll flag it.

[Slider with 4 markers: <₹15k, ₹15–30k, ₹30–60k, ₹60k+]

Turn 8 — Maternity & near-term events (CONDITIONAL)

"Anything planned in the next 12–24 months — pregnancy, a known surgery, anything you've discussed with a doctor recently?"

Why we ask: most policies have 30-day initial waits and 24–36-month maternity waits. If you need cover soon, that filters the list.

[Multi-select: "Pregnancy planned", "Surgery planned", "Recent hospitalisation", "None of these"]

Turn 9 — Risk preference

"When it comes to surprises in your bill, what do you prefer?"

Why we ask: this single answer decides whether co-pay/deductible plans (cheaper premium, share-of-bill) or full-cover plans (higher premium, predictable bill) fit you.

[Chips: "Lowest premium, I'll accept a 10–20% co-pay", "Balanced", "No surprises — full cover at higher premium"]

Turn 10 — Income (optional, asked last)

"One last optional question — your annual income band. We use it only to gauge how much sum insured fits your risk."

Why we ask: if you earn ₹8L/yr, a ₹50L cover is overkill; if you earn ₹40L/yr, a ₹5L cover leaves you exposed.

[Chips: "Prefer not to say", "<₹5L", "₹5–10L", "₹10–25L", "₹25L+"]

Wrap

"That's all I needed. Here's what I heard: . I'll now show you 3 policies that fit best, with the exact reasons they ranked well for you specifically."

→ Render scorecard cards (now personalised because profile_completeness >= 0.6).

---

Honest disclosure — the trust contract

Right after Turn 0 and again before Turn 4 (own conditions), the bot surfaces a one-line contract:

"Your answers stay in this conversation. They are NOT shared with any insurer until you choose to buy a policy through their channel. Being honest with me about your medical history is also what makes your claim defensible later — because insurers can match disclosed history against hospital records at claim time."

This is the customer-protection framing. It tells the user honesty is self-protection, not insurer-favoring.

---

Adaptive rules

• If the user is in free-form mode (asks questions back to the bot), don't push the script — let them lead. Resume when they ask "what do you recommend?"
• If profile_completeness >= 0.6 after some subset of questions, offer to skip the rest: "I have enough to recommend now. Want to keep going, or see what I'd suggest?"
• Never ask the same question twice. Profile.asked tracks this.
• A user who says "just show me policies" gets the marketplace with insurer-level metrics (CSR / complaints) visible but per-user scorecards GREYED with a "complete your profile to see how this ranks for you" CTA.

---

Implementation notes

The 9-slot fact-find SCHEMA still lives in backend/needs_finder.py::GRAPH — used now as the schema source embedded in the single-LLM system prompt rather than as a scripted question list. Each entry's id, field, is_core, and condition are consumed by the LLM as a structured contract; the prompt_en / prompt_hi strings are no longer rendered to the user (the LLM owns voice + cadence end-to-end via its system prompt + the conversation so far, and records facts through the save_profile_field tool).

To add a new question:

1. Add a Question(...) entry with id, field (which Profile attribute it sets), is_core (boolean — counts toward completeness), optional condition callable, optional parser.
2. Surface the new slot in the single-brain system prompt's 9-slot schema (alongside accepted value shapes + examples) so the LLM knows to capture it. See the system prompt in backend/single_brain.py.
3. Wire any post-capture validation into the save_profile_field handler in backend/brain_tools.py (enum coercion, INR parsing, bounds).
4. Add a row in 70-docs/scorecard-knowledge-graph.md Part B showing how the new input shifts weights.
5. Wire the shift into _profile_tuned_weights() in backend/scorecard.py.

Drift between these places breaks the transparency promise. Keep them in sync.