/design-voice-ui

description: "Design a voice interface — wake word flows, confirmation patterns, error recovery, screen companion layout (if hybrid), audio feedback guidelines."
argument-hint: "[product type] [platform: alexa|google|custom] [screen: voice-only|hybrid]"
allowed-tools: ["Read", "Write", "mcp__*"]

/design-voice-ui

You are designing a complete voice user interface (VUI). Your output is a single structured spec covering interaction flows, confirmation patterns, screen companion layout (if hybrid), audio feedback, and accessibility.

Input

Arguments: **$ARGUMENTS**

Parse the following from `$ARGUMENTS`:

• **Product type**: what the product does (e.g., smart home control, customer support, media playback, banking assistant)
• **Voice platform**: Alexa / Google Assistant / custom (default: custom)
• **Screen availability**: voice-only / hybrid (default: voice-only)

---

Step 1: Load Knowledge Base

Read `${CLAUDE_PLUGIN_ROOT}/skills/design/references/conversational-designer.md` to apply the full Conversational Designer VUI knowledge base to every section below. Focus especially on: VUI Principles (wake word design, confirmation strategies, barge-in, no-input handling, SSML), Multi-Modal Design (when to show vs. speak, progressive disclosure, sync latency), and Earcons and Audio Feedback.

**MCP Fallback**: If the file cannot be read, proceed using inline knowledge. The inline knowledge for this command covers: wake word requirements (3+ syllables, phonetically distinctive, brand-consistent), confirmation strategies (explicit for high-stakes/irreversible, implicit for low-stakes/reversible), barge-in (enable by default, stop audio within 100ms, resume from current state), no-input handling (4s → "Are you still there?", 4s more → explicit options, third silence → graceful exit), SSML (break/emphasis/prosody/say-as), earcons (ascending 2-tone for success 200ms, descending 2-tone for error 300ms, pulse for waiting, single chime for wake detection 150ms), and multi-modal sync (screen update within 200ms of voice response starting).

---

Step 2: Generate the Spec

Produce all five sections below as a single continuous output. Do not pause or ask for confirmation between sections.

---

Section 1: Interaction Flow Diagrams

Four key conversation paths for the voice interface.

Success Flow (intent recognized, action completes)

User: [Wake word] — "Hey [assistant name]"
  └─→ SYSTEM: Wake word detected
       └─→ [Earcon: single chime 150ms] + [Listening indicator active]
            └─→ User: [core voice command]
                 └─→ SYSTEM: Intent recognized (confidence ≥ 0.85)
                      └─→ [Processing indicator]
                           └─→ BOT: [Implicit confirmation + action]
                                └─→ [Earcon: ascending 2-tone 200ms] + [Screen update if hybrid]
                                     └─→ [END or await follow-up]

Disambiguation Flow (multiple valid responses match)

User: [ambiguous command — top 2 intents within 15% confidence]
  └─→ SYSTEM: Disambiguation triggered
       └─→ BOT: "I want to make sure I help with the right thing.
                 Do you mean [Intent A] or [Intent B]?"
            └─→ [2 options only — max 2 choices per disambiguation prompt]
                 ├─→ User: clarifies → [proceed with selected intent]
                 └─→ User: still ambiguous → FALLBACK_1 (not a second disambiguation)

Not-Understood Flow (intent not recognized — 3-strike model)

User: [utterance — intent not recognized]
  └─→ FALLBACK_1: "I didn't quite catch that. You can say things like
                   '[capability 1],' '[capability 2],' or '[capability 3].'"
       └─→ User: [still unrecognized]
            └─→ FALLBACK_2: "Let me try a different way — I can help with
                             [category A], [category B], and [category C].
                             Which of those sounds closest to what you need?"
                 └─→ User: [still unrecognized or 3rd failure]
                      └─→ ESCALATION: "I'm having trouble understanding —
                                       let me connect you with someone who can help."
                           └─→ [Graceful exit or human handoff]

**Fallback rule**: Never repeat the same fallback phrase twice in a session. Rotate phrasing. FALLBACK_1 should offer structured choices — an open-ended reprompt after a failed open-ended exchange is a dead end.

Error Flow (service failure → graceful exit with alternative)

SYSTEM: [Action attempted — service call fails]
  └─→ [Earcon: descending 2-tone 300ms]
       └─→ BOT: "Something went wrong on my end — it's not you.
                 Want me to try again?"
            ├─→ User: "Yes" → [Retry once]
            │     ├─→ [Retry succeeds] → Resume flow
            │     └─→ [Retry fails] → "I'm still having trouble.
            │                          [Alternative: 'Try the app' / 'Call support' / 'I'll remind you later']"
            └─→ User: "No" / silence after 8s → Graceful exit offer

**No-input handling (silence during expected response):**

| Silence duration | Response | |---|---| | 4 seconds | "Are you still there? Take your time." | | 4 more seconds | "You can say 'yes' to continue, 'start over' to begin again, or 'goodbye' to end." | | Third silence | "I'll end our session now — [platform wake word] anytime." End gracefully. |

Note: silence during slot-filling (user thinking about a date or number) should receive a longer grace period than top-level silence. For **explicit yes/no confirmation prompts on high-stakes actions** (payment, booking, deletion), the extended 8-second threshold from Section 2 applies — deliberate silence before confirming an irreversible action is expected and should not be penalized with a 4-second cutoff.

---

Section 2: Confirmation Patterns

Match confirmation weight to action weight. Over-confirmation destroys conversation flow;