Use this when you're speccing a feature that uses LLMs, AI models, or generative capabilities. A traditional PRD misses the decisions that make or break AI features: which model, how to evaluate quality, what happens when the model fails, and how much it costs per interaction. This skill extends /prd-draft with the AI-specific sections teams forget until production.

Framework attribution: The data-consent and dignity dimensions draw on the FRIES framework (Freely given, Reversible, Informed, Enthusiastic, Specific) from Building Consentful Tech (Una Lee & Dann Toliver, CC BY). See knowledge/product-ethics-frameworks.md.

Related skills: Extends /prd-draft for traditional PRD structure. Uses /ai-eval-design for deeper eval planning. See /ai-prototype-guide for building the prototype from this spec. See /multi-model-strategy for multi-model routing decisions. For an executable spec to hand a coding agent, use /spec-driven-feature.

The hard part most teams miss

A normal PRD describes the happy path and assumes the technology works. An AI spec is the inverse: the parts a generalist treats as edge cases are the actual product.

1. "Why AI" is a gate, not a formality. Most specs assume the model and design around it. The spec's real job is to prove a rules engine, a lookup table, or a search index would not do the job. If it would, you are buying nondeterminism, latency, and per-call cost for nothing. Answer this first (Step 1, question 3) or do not write the spec.

2. The failure mode is the product, not an exception. A deterministic feature fails by crashing, and you handle it once. An AI feature is wrong while looking confident, every day, at some rate. What the model does when it does not know, when it is unavailable, when the user is adversarial, is not an edge case you bolt on at the end. It is the spec (Step 4 guardrails). Design it before the happy path, not after.

3. Cost per interaction reshapes the design, it is not a footnote. A feature that is excellent at $0.30 per call and impossible at $0.03 is two different products. The unit cost decides model tier, context strategy, and whether the feature can exist at your volume at all (Step 5). Estimate it early, because it changes what you are allowed to build, not just what it costs.

Everything below is the structure. These three are why the structure exists.

Process

Step 1: Gather context

Ask the user:

1. What AI-powered feature are you building? (Name and one-line description)
2. What user problem does this solve? (Evidence: user quotes, support tickets, research)
3. What does the AI do that couldn't be done without it? (The "why AI" test -- if a rules engine or lookup table works, you don't need AI)
4. Who are the users? (Personas and their expectations for AI accuracy, speed, and tone)
5. How does this work today? (Current workflow, tools in use, pain points with the status quo)
6. Known constraints -- budget per interaction, latency requirements, data privacy restrictions, compliance needs, expected volume (daily/monthly interactions)
7. Prior art -- how competitors or existing tools handle this (include screenshots if available)

If the user provides a brief, extract what you can and ask follow-ups for gaps. Flag anything unclear with [NEEDS INPUT].

Step 2: Define model requirements

Work through these decisions with the user:

Decision	Options	Notes
Primary capabilities	Text generation, classification, extraction, summarization, code generation, multimodal, embedding (often multiple)	What the model actually needs to do -- most features combine capabilities
Quality bar	Must be correct (medical, legal), should be helpful (productivity), can be approximate (creative)	Determines eval rigor
Latency target	Real-time (< 2s), interactive (< 10s), batch (minutes OK)	Affects model choice and architecture
Streaming needed?	Yes (progressive results), no (complete response)	Long-running tasks need streaming for UX; affects API choice
Context window need	Small (< 4K tokens), medium (< 32K), large (< 128K), very large (> 128K)	Affects model and architecture
Cost sensitivity	High (consumer, high volume), medium (B2B, moderate volume), low (enterprise, low volume)	Affects model tier and caching strategy
Data sensitivity	Public data only, private but not regulated, regulated (HIPAA, SOC2, GDPR)	Affects deployment and vendor choice

After completing the table, recommend specific model families based on the answers. Use the knowledge references to map capability + quality bar + cost sensitivity to model tiers. Flag the recommendation as [RECOMMENDED -- verify during development].

If the feature involves voice input or output, also work through:

Decision	Options	Notes
Voice direction	Input only (transcription), output only (TTS), bidirectional (conversation)	Determines API choice: Whisper/TTS for async, Realtime API for conversation
Latency target	Real-time conversation (<500ms), interactive (<2s), batch (minutes OK)	Real-time voice has tighter budgets than text -- >500ms feels laggy
Voice identity	Default synthetic, custom/cloned, brand voice	Custom voices require golden reference samples (30s-5min) and consent
Language coverage	English only, top 5 languages, 20+ languages	Accuracy drops for low-resource languages; test each target language
Accent handling	Standard accents only, broad dialect coverage	Test with representative accent samples -- this is an equity issue
Audio environment	Clean/quiet, noisy/mobile, call center	Background noise tolerance affects model and preprocessing choice

Voice eval criteria (add to Step 4 quality dimensions):

Dimension	Definition	Threshold	How to measure
Word error rate (WER)	Transcription accuracy	(e.g., < 8% on test set)	Automated comparison to human transcripts
Naturalness (MOS)	How human does the voice sound	(e.g., > 4.0 on 1-5 scale)	Human listener panel rating
Response latency	Time from end of user speech to start of AI speech	(e.g., < 500ms p95)	Instrumented measurement
Interruption handling	Can user interrupt mid-response gracefully	(e.g., successful interrupt in < 200ms)	Scenario testing

Voice guardrails (add to Step 4 guardrails):

• What happens when transcription confidence is low? (Ask to repeat vs. best-guess)
• What happens when background noise makes speech unintelligible?
• How does the system handle overlapping speech?
• What disclosure is required? (Many jurisdictions require "you are speaking with an AI")

Voice cost projections (add to Step 5 cost table):

• Per-minute audio processing cost (transcription + synthesis): typically $0.02-0.07/min
• Telephony costs if phone-based (SIP/PSTN interconnect): $0.01-0.02/min
• Total AI voice cost: typically $0.04-0.14/min (compare to human agent at $0.50-1.50/min)

Step 3: Design the prompt architecture

Outline the prompting approach -- not the exact prompts, but the strategy:

1. System prompt approach -- what persona, constraints, and output format does the system prompt establish?
2. User input handling -- how is user input preprocessed, validated, or augmented before reaching the model?
3. Context management -- what context is injected? (RAG, conversation history, user profile, external data)
4. Output parsing -- structured output (JSON, specific format) or free-form? How is output validated?
5. Few-shot examples -- are examples needed? How many? Static or dynamic?
6. Multi-step processing -- does the task need chain-of-thought reasoning, multiple passes, or staged processing? (e.g., classify first, then generate; or identify issues, then prioritize, then suggest fixes)
7. Context compaction -- keep system instructions under 50 lines to avoid context bloat. Long system prompts degrade output quality as the model struggles to weight all instructions equally. If the feature needs more than 50 lines of instructions, split into: core constraints (always loaded), domain context (loaded per request type), and reference material (retrieved via RAG, not stuffed into the prompt). Don't dump five files into the system prompt and expect good results.

System prompt skeleton (a starting template, not a finished prompt):

ROLE: You are (specific role), not a general assistant. (One sentence on the
      single job this prompt exists to do.)

INPUTS: You will receive (named inputs and their shape). Treat (X) as
        authoritative and (Y) as the user's claim, which may be wrong.

OUTPUT CONTRACT: Return (exact shape: JSON schema, or named sections, or a
        single labeled value). Never return prose outside this shape.

CONSTRAINTS:
- (The 3 to 5 hard rules. Each one maps to a guardrail or an eval dimension.)
- When a required input is missing or contradictory, return (defined
  fallback), do not guess.

REFUSE / ESCALATE WHEN: (the named conditions that must reach a human or a
        canned safe response, not a generated one).

The order matters: role and output contract before constraints, because the model anchors on what it is and what it must produce. A constraint the model reads after it has already decided the shape is a constraint it will weight less.

Output handling: contract, do not parse prose. Decide the output shape at spec time and bind the model to it, rather than generating free text and reverse-engineering it downstream. Modern model APIs enforce a response schema directly (for example structured outputs that constrain the response to a JSON schema, or strict tool-call parameters). Specify which the feature uses. The anti-pattern, "the model writes a paragraph and a regex pulls the number out," fails silently the first time the model phrases the paragraph differently.

Reasoning and cost levers to specify (current-generation models): if the task needs multi-step reasoning, say so and pick the lever rather than leaving it to chance: adaptive or extended thinking for genuinely hard steps, an effort or reasoning level for the depth-versus-cost tradeoff, and prompt caching for any large, stable prefix (system prompt, retrieved context, few-shot block) reused across calls. Caching a 2K-token stable prefix is the single most common 10x cost reduction teams leave on the table. Name the levers in the spec so the build team does not rediscover them in production.

Prompt architecture anti-patterns:

Anti-pattern	Why it fails	Do instead
The kitchen-sink system prompt	200 lines of rules; the model weights none of them well and contradicts itself	Core constraints always loaded; domain context per request type; reference material via RAG
Parse the prose	Generate free text, extract structure with regex; breaks the first time phrasing shifts	Bind output to a schema (structured outputs / strict tool params) at spec time
Trusting the user's facts	Prompt does not separate authoritative input from user claims; model agrees with wrong premises (sycophancy)	Mark which inputs are authoritative; instruct the model to decline false premises
No defined "I don't know"	Model has no sanctioned fallback, so it fabricates one	Specify the exact low-confidence and missing-input behavior; make refusal a valid output
Few-shot drift	Static examples that no longer match the live distribution silently bias outputs	Version examples with the prompt; review them when the input distribution shifts
Stuffing context that should be retrieved	Every call pays for context that one call in ten needs	RAG for large or conditional reference material; keep the always-loaded prompt lean

Step 3b: Design the interaction layer

The prompt architecture defines what the AI does technically. The interaction layer defines what the user experiences. Both need to be designed.

Work through these decisions:

Decision	Options	Notes
Loading experience	Streaming text, progress indicator, skeleton screen, "thinking..." message	What does the user see while the AI works? Streaming builds trust through visibility.
Result presentation	Inline text, structured card, expandable sections, side panel, modal	How do results appear? Match the complexity of the output to the display format.
Confidence display	Hidden, subtle indicators, explicit confidence labels, source citations	Does the user need to know how sure the AI is? Clinical and financial domains usually need transparency.
Regeneration/retry	Thumbs up/down, "try again" button, "refine" with instructions, no retry	Can the user ask for a different answer? How?
Correction mechanism	Edit output directly, provide feedback, report errors, none	Can the user fix what the AI got wrong?
Human fallback	Escalate button, automatic routing, "talk to a person" link, none	When the AI can't help, what's the path to a human?

For deeper interaction design -- persona, conversation flow, trust patterns -- see /ai-persona-design, /ai-conversation-design, and /ai-trust-pattern.

Step 4: Define eval criteria and guardrails

Outline what "good" and "bad" look like:

Quality dimensions:

Dimension	Definition	Threshold	How to measure
(Accuracy)	(Does it get the facts right?)	(e.g., > 95% on golden dataset)	(Automated check, human review)
(Relevance)	(Does it answer what was asked?)	(e.g., > 90% rated relevant)	(LLM-as-judge, user feedback)
(Helpfulness)	(Is the output actionable and worth the user's attention?)	(e.g., > 80% acted on by users)	(User action tracking, feedback)
(Tone)	(Does it match brand voice?)	(e.g., passes tone rubric)	(Rubric scoring)
(Safety)	(Does it avoid harmful output?)	(e.g., 0% harmful in adversarial set)	(Red team testing)

Setting thresholds for v1: Start with a golden dataset of 50-100 representative examples. Set initial thresholds based on human baseline performance (how accurate is a human doing this task?). It's better to set an honest threshold and hit it than an aspirational one you can't measure.

Guardrails and fallback behavior:

• What happens when the model returns low-confidence output?
• What happens when the model is unavailable (timeout, rate limit, outage)?
• What content should be blocked or filtered?
• What does the fallback UX look like?

For deeper eval planning, use /ai-eval-design to build golden datasets and eval pipelines.

Step 5: Estimate costs

Component	Estimate	Basis
Avg. input tokens per request	(estimate)	(sample prompts)
Avg. output tokens per request	(estimate)	(sample outputs)
Context retrieval cost	(estimate)	(embedding/search calls per request)
Model pricing	($ per 1K tokens)	(current pricing)
Cost per interaction	(calculated)	input + output + retrieval cost
Projected daily volume	(estimate)	(user base x usage frequency)
Monthly cost projection	(calculated)	cost per interaction x volume
Cost per user per month	(calculated)	monthly cost / active users
Cost ceiling	(budget limit)	(what's acceptable)

Worked example: A typical interaction with a 500-word user input, 2K-token system prompt, and 800-token response using a mid-tier model at $0.015/1K tokens costs roughly $0.05 per interaction. At 100 interactions/day, that's ~$150/month in model costs alone.

Include notes on cost optimization: caching, shorter prompts, smaller models for simple tasks, batching.

Step 6: Draft the AI product spec

Compile into the spec document:

# AI Product Spec: (Feature name)

## Overview
(What we're building, why AI, and the core user value -- 3-4 sentences.)

## Problem Statement
(The user problem, with evidence. Why AI is the right solution approach.)

## Model Requirements
(Table from Step 2 -- capability, quality bar, latency, context, cost, data sensitivity)

## Prompt Architecture
(Strategy from Step 3 -- system prompt approach, context management, output parsing)

## Quality & Eval Criteria
(Table from Step 4 -- dimensions, thresholds, measurement methods)

## Guardrails & Fallbacks
(What can go wrong and what happens when it does)

## User Experience & Interaction Design
(How users interact with the AI feature -- loading experience, result presentation, confidence display, regeneration/correction mechanisms, human fallback paths. From Step 3b.)

## Integration Architecture
(How this connects to existing systems -- APIs, webhooks, data flow, authentication)

## Cost Projections
(Table from Step 5 -- per-interaction cost, volume, monthly projection, ceiling)

## Goals & Success Metrics
| Goal | Metric | How we measure it |
|------|--------|-------------------|
| (Goal 1) | (Specific metric) | (Tool or method) |
| (Goal 2) | (Specific metric) | (Tool or method) |

## Scope
**In scope:**
- (Capability 1)
- (Capability 2)

**Out of scope:**
- (Excluded item -- and why)

## Open Questions
- (Unresolved decisions)
- (Things that need testing to determine)

## Handoff to Build

When ready to prototype this spec with an AI coding tool:
1. **Gather visual references** -- take screenshots of similar products or UI patterns you want to match
2. **Start with the plan, not the code** -- paste this spec (or a summary) into your AI tool and ask it to create a build plan before writing code
3. **Build in phases** -- break the scope into 3-4 phases; build and review one at a time
4. **Don't over-specify prompts yet** -- get the UX working first, then tune the AI behavior

See `/ai-prototype-guide` for the full prototyping workflow.

Step 7: Stress-test and finalize

Challenge the spec:

1. What's the worst thing the AI could output? Is the guardrail sufficient?
2. Is the cost projection realistic at 10x the expected volume?
3. Can you actually measure the eval criteria with current tooling?
4. Is the quality bar honest or aspirational?
5. What would a skeptical engineer ask about the prompt architecture?
6. What would a skeptical ML engineer ask about model selection?

Revise based on user responses.

Uncertainty Policy

Topic	Tolerance	Action
User problem statement	Low	STOP and ask -- spec is useless without a real problem
Quality dimensions and thresholds	Low	STOP and ask -- vague quality bars lead to vague features
Model choice	Medium	Recommend + flag [RECOMMENDED] -- can be changed during dev
Cost estimates	Medium	Estimate + flag [ESTIMATED] -- refine with actual usage
Prompt architecture details	Medium	Propose approach + flag [PROPOSED] -- will iterate
Guardrail specifics	Medium	Propose + flag [PROPOSED] -- needs adversarial testing
Competitor details	High	Best guess from context

Default: STOP and ask when a topic is not listed above.

Output location

Present the spec as formatted text in the conversation for the user to copy into their docs tool.