LetsBeBiz-Site/docs/superpowers/specs/2026-04-01-voice-discovery-pivot-design.md

Voice Discovery Mode — Design Spec

Overview

Pivot the voice mode from a "faster way to fill out the configurator" into a standalone consultative discovery experience. Exploratory users — people who don't yet know exactly what they need — get a warm, conversational entry point separate from the typed configurator. The conversation is free-flowing and consultant-like, structured data is captured silently, and the user receives a personalized brief at the end.

Entry Point & Framing

Placement

A new standalone section on the landing page, positioned after the services or process section — wherever the natural "I'm interested but not sure" moment occurs. Completely decoupled from the configurator.

Copy Direction

• Headline: Warm and inviting — "Not sure where to start?" or "Still figuring out what you need?"
• Subtext: "Tell us what you're thinking and we'll figure it out together. You'll get a personalized brief at the end."
• CTA button: "Let's talk" — styled distinctly from the configurator's CTA.
• Both EN and FR translations required.

Behavior

Clicking the CTA scrolls to / reveals the voice conversation panel inline on the page. No route change, no modal. The panel expands in place, keeping the user grounded in the site context.

Configurator Changes

• Remove the ModeToggle component and mode state from WizardContainer.tsx.
• The configurator becomes typed-form-only — the "I know what I want" path.
• No other changes to the configurator itself.

Voice Conversation UI

Layout

A dedicated panel, roughly the same width as the configurator card but taller. Three zones stacked vertically:

1. Agent header — LetsBe branding mark, agent name, connection status dot. Similar to current but slightly more prominent.

2. Orb + transcript area — Orb is larger (24-28 units instead of 20). Live transcript below it with significantly more vertical space (max-h-72 or similar instead of current max-h-40). Proper autoscroll using scrollIntoView on the bottom ref. Selection chips are removed — no visible evidence of structured data capture.

3. Controls — Mic toggle and end call button. Same as current, cleaner without chips.

Mobile

Panel goes nearly full-width on small screens. Transcript takes most of the viewport height. Orb may scale down slightly. Controls stay fixed at the bottom for thumb reach.

Contact Confirmation Card

When the agent captures name and email, a small inline card appears (above controls or below transcript) showing the captured values with inline edit affordance. The agent says "I've got your details on screen — look right?" User can tap to edit, then confirm. This replaces the verbal spell-back entirely.

Requires a new tool (e.g., request_contact) that the agent calls to surface the card, rather than collecting contact info verbally.

During Brief Generation

After contact confirmation and complete_brief trigger:

• Connection is closed (already fixed).
• Panel transitions to a generating state — orb morphs to loader or StepGenerating-style progress indicators.
• Transcript remains visible so the conversation doesn't vanish.

On Completion

Transitions to the same StepComplete view (brief preview + book a call CTA). The brief content will be richer due to deeper conversation, but presentation is the same.

System Prompt & Agent Behavior

Tone

The agent is a conversational consultant, not an interviewer with a checklist. No numbered topic list to work through. The prompt gives the agent a goal: "understand what this person needs deeply enough to write a compelling brief."

Behavioral Guidelines

• Follow the user's thread. If they talk about a frustration, dig into it. Don't redirect to the next "topic."
• One question at a time. This stays — it works.
• Offer perspective, not just questions. "That sounds like it might be more of a systems problem than a website problem." The agent has opinions, not just a clipboard.
• Reference LetsBe naturally. "We've done something similar for a hospitality client" — not a feature list.
• 2-3 sentences per response. Prevents monologuing.

Structured Data Capture

update_selections tool stays. The agent is never instructed to "cover these topics." It maps what it hears to predefined values silently. If the conversation never touches timeline, that field stays empty — that's fine.

Brief Generation

conversationSummary is the primary payload. The prompt instructs the agent to include everything discussed: pain points, current tools, what they want to keep vs change, business context, decision-makers, what success looks like. Structured fields (services, industry, timeline) are metadata that helps organize the brief, not the substance.

Brief Content Philosophy

The brief should be diagnostic, not prescriptive:

• Deep on their world — pain points, current tools, what's broken, customers, what success looks like.
• Deep on what matters — priorities and trade-offs surfaced in conversation.
• LetsBe's perspective — a few sentences of informed opinion on what the real problem is.
• High-level on implementation — no stack recommendations, no architecture, no specific deliverables.
• No timeline/cost — "that's what the call is for."

The brief should make the user feel understood and make the follow-up call feel like a warm continuation, not a cold intro.

Contact Collection

The agent asks for name and email when the conversation reaches a natural conclusion — "I think I've got a great picture of what you need. Let me put a brief together — what's your name and email?" No forced timing. The request_contact tool surfaces the on-screen card for verification.

Language

Both EN and FR system prompts, same as now.

Reconnection Handling

Exploratory conversations run longer than form-filling. If the WebSocket drops mid-conversation:

• Preserve the transcript on disconnect.
• Show a "reconnect" option instead of just an error.
• On reconnect, seed the new Gemini session with the transcript so far (as context in the system prompt or initial message) so the agent can pick up where it left off.
• The structured selections captured so far are preserved in state.

Technical Changes

Files to Modify

• VoiceAgentProvider.tsx — Refactor handleToolCall so conversationSummary is the primary brief input. Add state for contact confirmation card (name + email captured, pending user confirm). Add reconnection logic (preserve transcript, re-seed on reconnect). Connection teardown on brief completion already fixed.

• VoiceAgent.tsx — New layout: larger orb, bigger transcript area, no selection chips. Add contact confirmation card component (inline editable name + email). Fix autoscroll with scrollIntoView. Guard controls for brief-complete state (already done). Mobile-responsive layout.

• gemini-live.ts — Rewrite buildSystemPrompt() for both locales with consultative tone. Adjust complete_brief tool description to emphasize conversationSummary. Add request_contact tool declaration that surfaces the on-screen card.

• WizardContainer.tsx — Remove ModeToggle component import, mode state, and the voice mode rendering branch. Remove handleVoiceComplete and VoiceAgentProvider wrapper (these move to the new section).

• ModeToggle.tsx — Delete entirely.

• New: Discovery section component — New section component for the landing page with warm copy, CTA, and expandable voice panel. This is where VoiceAgentProvider and VoiceAgent now live.

• Landing page — Add the new discovery section at the appropriate position.

• i18n message files (en.json, fr.json) — Add translations for discovery section copy. Update voice-related strings as needed.

• Email template — Verify the brief email template handles longer, more narrative content gracefully. Adjust if needed.

What Stays the Same

• WebSocket connection to Gemini Live API
• Audio worklet recording + playback pipeline
• update_selections tool (used silently now)
• /api/configure route and brief generation logic
• /api/gemini-token route
• StepComplete component
• analyze_website tool (still useful when someone mentions their current site)
• The typed configurator (minus the mode toggle)