Task: Create INTENTSPEC.md for a Voice Intent

Task: Create INTENT_SPEC.md for a Voice Intent

Objective

Produce an INTENT_SPEC.md that serves as the single source of truth for designing the deep dialog of one voice intent: a complete sample-utterance library grouped by phrasing pattern, every slot's validation / disambiguation / re-prompt / carry-over / confirmation rules, the turn-by-turn multi-turn dialog flow, the confirmation flow detail, every declared response role's composition (TTS body structure, SSML hints, variation strategy, length budget, persona constraints), the multimodal expansion detail, an expanded failure matrix per failure type, the intent's full context-effect ledger, and intent-specific privacy and safety constraints. The defining discipline — and the definition of "done" — is that the gap between VOICE_IA's blueprint and a fully-composable dialog is purely mechanical: an implementing agent reading VOICE_IA's blueprint for the intent + DESIGN.md's voice-design tokens + this INTENT_SPEC produces the intent's full dialog, slot-filling logic, confirmation pattern, response structure, and multimodal expansion exactly as designed, without inventing utterance grammar, disambiguation prompts, or escape paths.

The commonest violation is silently picking an answer for a design-level question instead of surfacing it. When VOICE_IA, DESIGN.md, or sibling INTENT_SPECs are silent, ambiguous, or contradictory on a question this intent must answer — a re-prompt sequence, an SSML hint, an escape path, a multimodal action affordance — the question belongs in § 11 Open Questions with options, tradeoffs, and a recommendation. Do not invent. INTENT_SPEC must never introduce a design decision that is not already traceable to VOICE_IA, DESIGN.md, or a sibling INTENT_SPEC.

INTENT_SPEC is opt-in. Most intents stay with their lightweight inline blueprint in VOICE_IA. Use INTENT_SPEC only when the intent meets at least one of the selection criteria below.

Selection criteria — when to write an INTENT_SPEC

• The intent's full composition exceeds ~30 lines if expressed inline in VOICE_IA.
• The intent is multi-turn — needs more than one user-system exchange to complete.
• Slot-filling involves disambiguation, re-prompts, or carry-over from prior turns.
• Confirmation flow is non-trivial — multi-stage, escape paths, ambiguous affirmations.
• Multimodal expansion is non-trivial — visual card with multiple action affordances.
• Failure paths include hand-off to a human.
• Platform variations are substantial — different dialog flows on Alexa vs Google.
• Multiple work units touch the same intent.
• The intent is high-traffic or high-stakes — financial, medical, destructive.

Intents not meeting these stay with inline blueprints in VOICE_IA. Do not write an INTENT_SPEC for a one-shot informational intent or a utility intent.

The output file is conventionally placed at voice-intents/<intent-id>/INTENT_SPEC.md in the consuming project, where <intent-id> is the stable identifier from VOICE_IA's Intent Inventory.

Inputs

1. Intent identifier (required) — the stable intent ID from VOICE_IA's Intent Inventory (e.g., ForkResource, StartCheckout). Used verbatim in the frontmatter intent_id field and in the title of the output.
2. VOICE_IA.md (required) — invocation model, slot model, dialog model and context, platform strategy, confirmation strategy, fallback and handoff strategy, privacy and safety constraints, and the intent's lightweight blueprint to extend. The authoritative source for intent IDs, slot names, response role names, context keys, shared-surface names, failure-matrix row vocabulary, handoff target names, and platform names. INTENT_SPEC extends — never redefines — VOICE_IA's claims about this intent.
3. DESIGN.md (required if present) — voice-style tokens: tone-of-voice register (tone-warm, tone-formal, tone-playful), persona descriptors (persona-helpful, persona-expert), prosody guidance, SSML conventions (named hints — pause-short, emphasis-moderate, prosody-deliberate), multimodal card style tokens, microcopy patterns. INTENT_SPEC cites these tokens by name and never invents new ones. If DESIGN.md is absent, surface the absence as an open question — do not invent voice-style decisions.
4. Sibling INTENT_SPEC.md files (optional, auto-discovered) — the INTENT_SPECs of every intent referenced from this intent's dialog flows (intents this hands off to, or receives a hand-off from). Discovery mechanism: walk the dialog flow's hand-off targets and load the corresponding voice-intents/<intent-id>/INTENT_SPEC.md for each; if no INTENT_SPEC exists for a referenced intent, it is sufficient to cite VOICE_IA's blueprint.
5. Prior voice-intents/<intent-id>/INTENT_SPEC.md (optional, auto-discovered — only if refining) — read fully; preserve every resolved open question, every utterance pattern already calibrated, every re-prompt sequence already approved. Re-run citations against the current VOICE_IA and DESIGN.md — do not assume stale intent IDs, slot names, response role names, or SSML hint names are still valid.

Read-set size: VOICE_IA + DESIGN.md are always read end-to-end; 0–4 sibling INTENT_SPECs depending on hand-off targets in the dialog flow. Read every sibling INTENT_SPEC in full — truncated reads cause silent contradiction across hand-offs.