Owl-Listener/ai-design-skills

# Bias Detection Design
AI systems inherit biases from training data, amplify them through pattern-matching, and embed them in outputs that appear authoritative. Bias detection design creates the workflows, processes, and interfaces that help teams find and fix bias before users encounter it.
## Types of Bias in AI Products
- **Representation bias**: Some groups are overrepresented or underrepresented in outputs (images, examples, personas)
- **Performance bias**: The AI works better for some users than others (languages, accents, cultural contexts)
- **Framing bias**: The AI presents information in ways that favour certain perspectives
- **Allocation bias**: AI-driven decisions distribute resources or opportunities unevenly
- **Association bias**: The AI links concepts in stereotypical ways
## Designing Bias Detection Workflows
Bias detection is a team practice, not a one-time audit:
- **Regular review cycles**: Schedule periodic reviews of AI outputs for bias patterns
- **Diverse review panels**: Include reviewers from different backgrounds, cultures, and perspectives
- **Structured evaluation**: Use rubrics and checklists, not intuition
- **Real-world sampling**: Test with real user inputs, not just curated test cases
- **Longitudinal monitoring**: Bias can emerge over time as usage patterns change

# Consent and Agency
AI products make decisions, take actions, and process information on behalf of users. Consent and agency design ensures users remain in control — understanding what the AI does, agreeing to it, and being able to override it.
## Informed Consent for AI
Users should understand and agree to:
- **What data the AI uses**: Conversation history, personal data, uploaded documents, browsing behaviour
- **What the AI does with it**: Training, personalisation, sharing with third parties, storage
- **What actions the AI takes**: Sending messages, making changes, accessing systems
- **What the AI can't do**: Limitations that might affect the user's expectations
Consent is not a checkbox at sign-up. It's an ongoing design challenge throughout the experience.
## Designing for Agency
Agency means the user feels — and is — in control:
- **Opt-in over opt-out**: AI features should be activated by the user, not imposed
- **Reversibility**: AI actions should be undoable wherever possible
- **Override mechanisms**: The user can always stop, redirect, or override the AI
- **Exit paths**: The user can disengage from AI assistance at any point without penalty

# Escalation Design
Escalation is what happens when the AI reaches the boundary of what it should handle alone. Designing escalation well means the user gets help instead of a dead end — and the AI knows its limits.
## Escalation Triggers
The AI should escalate when:
- **Confidence is low**: The AI isn't sure its output is correct or helpful
- **Stakes are high**: The decision has significant consequences (financial, medical, legal, safety)
- **Emotional distress**: The user shows signs of crisis, distress, or vulnerability
- **Ambiguity is unresolvable**: The AI can't determine intent even after clarification
- **Scope boundary**: The request is outside what the AI is designed to handle
- **Policy boundary**: The request approaches or crosses a guardrail
- **Conflict**: The user disagrees with the AI and the disagreement can't be resolved
## Escalation Types
- **To human support**: Transfer to a human agent with full context
- **To the user themselves**: "This decision is yours to make" — handing back agency
- **To a specialist**: Routing to domain-specific help (medical, legal, technical)

# Guardrail Design
Guardrails are the behavioral boundaries that define what an AI product will and won't do. They're not just safety constraints — they're design decisions that shape the entire user experience.
## Types of Guardrails
- **Content guardrails**: What topics the AI will and won't discuss. What it generates and refuses to generate.
- **Action guardrails**: What the AI can do in the world — send emails, make purchases, delete data — and what requires human approval.
- **Tone guardrails**: How the AI communicates — what language it uses, how formal or casual, when it's direct vs. diplomatic.
- **Scope guardrails**: What the AI considers in and out of scope for its role. A coding assistant shouldn't give medical advice.
- **Confidence guardrails**: When the AI should express uncertainty, hedge, or refuse rather than guessing.
## Designing Guardrails as Product Decisions
Every guardrail is a product decision with tradeoffs:
- **Too strict**: The product feels limited, frustrating, and paternalistic. Users route around the guardrails.
- **Too loose**: The product causes harm, loses trust, and creates liability.
- **Inconsistent**: Users can't predict what the AI will and won't do, eroding trust.
The goal is guardrails that feel like good judgment, not arbitrary restrictions.
## Guardrail Specification

# Harm Anticipation

Harm anticipation is systematically thinking through how an AI product could cause harm — before it does. Preventive design, not reactive crisis management.

The work is unglamorous and easy to skip. Done well, it produces specific testable mitigations. Done badly, it produces a doc nobody reads.

## Categories of AI harm

- **Direct harm**: the AI outputs something harmful — dangerous advice, discriminatory content, privacy violations
- **Facilitated harm**: the AI helps a user do something harmful, even if the AI's output itself is benign
- **Emergent harm**: harmful patterns from scale or interaction effects, not from any single output
- **Omission harm**: the AI fails to act when it should — not flagging a crisis, not escalating
- **Erosion harm**: gradual negative effects — dependency, deskilling, manipulation, trust erosion

## Structured anticipation

# Transparency Patterns
Transparency in AI products means making the system's knowledge, limitations, and confidence visible to users. It's how you build warranted trust — trust based on understanding, not blind faith.
## What to Make Transparent
- **Source**: Where did the AI get this information? Training data, retrieved documents, user input, inference?
- **Confidence**: How certain is the AI? Is this a well-supported answer or a best guess?
- **Limitations**: What doesn't the AI know? What can't it do? Where does its knowledge end?
- **Process**: How did the AI arrive at this output? What steps did it take?
- **Identity**: This is an AI, not a human. Never obscure this.
## Transparency Patterns
- **Confidence indicators**: Visual or textual signals of certainty ("I'm fairly confident" vs. "I'm not sure about this")
- **Source attribution**: Citing where information came from
- **Reasoning traces**: Showing the AI's step-by-step thinking
- **Limitation disclosure**: Proactively stating what the AI can't do or doesn't know
- **Model cards**: High-level descriptions of what the AI is, how it works, and what it's good and bad at
- **Uncertainty highlighting**: Visually distinguishing confident outputs from uncertain ones

# Trust Calibration

Calibrated trust is the difference between an AI that augments user judgment and one that displaces it. Overtrust causes harm when the AI is wrong. Undertrust wastes the AI when it's right. Both failure modes are common, and neither shows up in standard accuracy metrics.

Designing for trust means giving users the information they need to update their trust appropriately, turn by turn.

## What shapes user trust in the moment

- **Surface confidence** — how certain the AI sounds, regardless of whether it should
- **Track record** — prior interactions in this and previous sessions
- **Stakes legibility** — how clearly the user understands what could go wrong
- **Source visibility** — whether the AI shows reasoning, sources, or alternatives
- **Persona fit** — a "professional" persona gets more trust than a "friendly" one for the same content

These shape trust whether you design for them or not. Designing for them deliberately is what trust calibration is.

# Value Specification
Values are abstract. AI systems need concrete rules. Value specification is the design work of translating organisational principles and user expectations into implementable constraints.
## The Translation Problem
Organisations say things like "be helpful" and "be responsible." These are useless as system constraints because they conflict:
- Being maximally helpful might mean giving dangerous information
- Being maximally responsible might mean refusing to help at all
- Being "fair" means different things in different contexts
The designer's job is to resolve these tensions into specific, testable rules.
## Value Hierarchy
Not all values are equal. Establish a hierarchy:
1. **Safety**: Prevent harm to users and others. This overrides everything.
2. **Accuracy**: Don't mislead. When uncertain, say so.
3. **Helpfulness**: Actually accomplish what the user needs.
4. **Respect**: Treat users as capable adults. Don't patronise.
5. **Brand alignment**: Reflect the organisation's identity and tone.

# Agent Role Design
In a multi-agent system, each agent needs a clearly defined role — what it does, what it knows, what it's responsible for, and where its authority ends. Without clear roles, agents duplicate work, conflict with each other, or leave gaps.
## Defining an Agent Role
For each agent in the system, specify:
- **Purpose**: What is this agent for? One sentence describing its reason to exist.
- **Capabilities**: What can this agent do? List specific actions and outputs.
- **Knowledge scope**: What does this agent know about? What domains, data, and context does it have access to?
- **Authority**: What decisions can this agent make autonomously? What requires approval?
- **Boundaries**: What is explicitly outside this agent's scope? Where does it stop and hand off?
- **Success criteria**: How do you know this agent is doing its job well?
## Role Design Principles
- **Single responsibility**: Each agent should have one clear purpose. If you need a paragraph to explain what it does, it's doing too much.
- **Clear boundaries**: The line between one agent's scope and another's should be unambiguous. No overlapping authority without explicit conflict resolution.
- **Minimal coupling**: Agents should be able to do their work with minimal dependencies on other agents. Share results, not process.
- **Appropriate autonomy**: The level of autonomous decision-making should match the stakes and the agent's reliability in that domain.

# Failure Recovery
Agents fail. Networks time out, models hallucinate, tools error, and edge cases surprise. Failure recovery design determines whether a failure becomes a dead end or a graceful detour.
## Failure Types in Multi-Agent Systems
- **Agent failure**: A single agent crashes, times out, or produces invalid output
- **Handoff failure**: Context is lost or corrupted during transfer between agents
- **Coordination failure**: Agents conflict, deadlock, or produce inconsistent results
- **Resource failure**: External tools, APIs, or data sources are unavailable
- **Cascading failure**: One agent's failure causes downstream agents to fail
## Recovery Strategies
- **Retry**: Try the same operation again. Works for transient errors (network timeouts, rate limits). Set a retry limit to avoid infinite loops.
- **Fallback**: Switch to an alternative approach. A different agent, a simpler method, or a cached result.
- **Escalation**: Pass the problem to a more capable agent or to a human. Used when the failure is beyond the current agent's ability to resolve.
- **Graceful degradation**: Deliver a partial result rather than nothing. Tell the user what worked and what didn't.
- **Compensation**: Undo the effects of a partially completed workflow before retrying or escalating.
## Designing Recovery Paths

# Handoff Protocols
A handoff is the moment one agent passes work to another — or to a human. It's where multi-agent systems most commonly fail. A dropped handoff means lost context, repeated work, or abandoned tasks.
## Anatomy of a Handoff
Every handoff has:
- **Trigger**: What causes the handoff? (task completion, scope boundary, failure, user request)
- **Source**: Who is handing off?
- **Destination**: Who is receiving?
- **Payload**: What information transfers? (context, partial results, user state, instructions)
- **Acknowledgment**: How does the source know the destination received the handoff?
- **User experience**: What does the user see during the handoff?
## Handoff Types
- **Sequential**: Agent A finishes, passes results to Agent B who continues. Like a relay race.
- **Parallel fan-out**: One agent distributes subtasks to multiple agents simultaneously.
- **Parallel fan-in**: Multiple agents' results converge back to one agent for synthesis.
- **Escalation**: An agent can't handle the task and passes up to a more capable agent or human.

# Human-in-the-Loop
Human-in-the-loop design defines when, where, and how humans intervene in automated workflows. Too little human involvement and the system makes dangerous mistakes. Too much and you've just built an expensive notification system.
## Intervention Types
- **Approval gates**: The system pauses and waits for human approval before proceeding
- **Review checkpoints**: The system presents results for human review but can continue if no objection
- **Correction opportunities**: The system shows its work and the human can edit before it's finalised
- **Override controls**: The human can stop, redirect, or undo the system's actions at any time
- **Monitoring dashboards**: The human passively observes the system and intervenes only when needed
## When to Require Human Intervention
- **High stakes**: Actions that are expensive, irreversible, or affect many people
- **Low confidence**: The system is uncertain about the right action
- **Novel situations**: The input or context is outside the system's training distribution
- **Ethical judgments**: Decisions that require moral reasoning or value trade-offs
- **Legal requirements**: Regulatory or compliance requirements mandate human review
- **User request**: The user explicitly asks for human involvement

# Observability Design
You can't improve what you can't see. Observability design makes the internal workings of multi-agent systems visible — so designers can understand user experience problems, developers can debug failures, and teams can improve the system over time.
## What to Make Observable
- **Workflow execution**: Which agents were involved, in what order, with what results
- **Decision points**: What decisions were made, what alternatives were considered, why one was chosen
- **Handoff details**: What context transferred between agents, was anything lost
- **Timing**: How long each agent took, where bottlenecks occur
- **Failures**: What failed, how it was recovered, what the user experienced
- **Quality signals**: Output quality scores, user satisfaction signals, task success markers
## Observability for Different Audiences
**For designers:**
- User journey view: What did the user experience across the whole workflow?
- Pain point identification: Where did users struggle, abandon, or express frustration?
- Quality patterns: Which outputs are high and low quality, and why?
**For developers:**

# State Management

In a multi-agent system, state is the shared truth about what's happened, what's in progress, and what's been decided. Without state management, agents work with stale or conflicting information — and the user pays the cost in repeated questions, contradictory answers, and lost progress.

State management is the *plumbing* skill of multi-agent design. Get it wrong and every other skill in this plugin gets harder.

## Types of state

- **Task state**: where the overall task is in its lifecycle. Which subtasks are complete, in progress, or pending.
- **Context state**: what each agent knows. What has been shared, summarised, or dropped.
- **User state**: preferences, history, and current emotional state.
- **Decision state**: decisions made, options considered, options rejected (and why).
- **Error state**: what has failed, been retried, been escalated.

## State architecture patterns

# Task Decomposition
Users come with goals, not subtasks. Task decomposition is how a multi-agent system breaks a complex user goal into pieces that individual agents can handle — and then reassembles the results into something coherent.
## Decomposition Strategies
- **Sequential decomposition**: Break the goal into ordered steps. Step 1 must complete before Step 2 starts.
- **Parallel decomposition**: Break the goal into independent parts that can be worked on simultaneously.
- **Hierarchical decomposition**: Break the goal into sub-goals, then break each sub-goal into tasks.
- **Conditional decomposition**: The next step depends on the result of the current step. Different results lead to different paths.
- **Iterative decomposition**: Start with a rough version, then refine through multiple passes.
## Designing Decomposition Rules
For each type of user goal the system handles:
- **What's the entry point?** How does the system receive the goal?
- **What are the subtasks?** List all possible subtasks for this goal type.
- **What are the dependencies?** Which subtasks depend on others' outputs?
- **What's the critical path?** Which sequence of subtasks determines the minimum completion time?
- **What can be parallelised?** Which subtasks can run simultaneously?

# Comparative Evaluation
Absolute quality scores are useful but limited. Comparative evaluation — putting outputs side by side and asking which is better — often reveals quality differences that rubrics miss.
## Comparison Methods
- **A/B testing**: Show different users different versions and compare outcomes
- **Side-by-side evaluation**: Show evaluators two outputs for the same input and ask which is better
- **Preference ranking**: Show evaluators multiple outputs and rank them from best to worst
- **Paired comparison**: Compare every pair of options to build a complete ranking
- **Elo rating**: Use tournament-style comparisons to develop continuous quality scores
## Designing A/B Tests for AI
A/B testing AI is different from A/B testing UI:
- **Variance is high**: The same prompt can produce different outputs, so you need more samples
- **Context matters**: The same change might help for one task and hurt for another
- **Metrics lag**: AI quality changes may take time to show up in user behavior
- **Interaction effects**: A change to one part of the conversation affects all subsequent parts
Design A/B tests with:

# Failure Taxonomy
Not all AI failures are the same. A hallucination is different from a refusal, which is different from a tone mismatch. A failure taxonomy classifies failure types so teams can track, prioritise, and address them systematically.
## Failure Categories
**Content Failures:**
- **Hallucination**: The AI presents false information as fact
- **Inaccuracy**: The AI gets details wrong (dates, numbers, names)
- **Incompleteness**: The AI misses important information
- **Irrelevance**: The AI's response doesn't address the user's actual question
- **Contradiction**: The AI contradicts itself within or across responses
**Behavioral Failures:**
- **Inappropriate refusal**: The AI refuses a reasonable request
- **Missing refusal**: The AI fulfils a request it should have declined
- **Tone mismatch**: The AI's tone is wrong for the context
- **Persona break**: The AI drops out of its defined persona
- **Over-generation**: The AI produces far more than needed

# Heuristic Evaluation for AI
Nielsen's 10 usability heuristics were designed for traditional software. AI products need adapted heuristics that address the unique challenges of probabilistic, generative, and conversational systems.
## Classic Heuristics, Adapted for AI
**1. Visibility of system status**
AI adaptation: The user should always know what the AI is doing, what it's working with, and how confident it is. Progress indicators for generation. Transparency about data sources.
**2. Match between system and real world**
AI adaptation: The AI should use language and concepts the user understands. Don't expose model internals. Frame capabilities in terms of user tasks, not technical features.
**3. User control and freedom**
AI adaptation: Users must be able to stop generation, undo AI actions, edit outputs, and override suggestions. AI autonomy should always have an exit.
**4. Consistency and standards**
AI adaptation: The AI should behave consistently across similar requests. Same input type should produce same output format. Persona should be stable.
**5. Error prevention**
AI adaptation: Design prompts and interfaces that guide users toward effective interactions. Suggest clarifications before producing low-quality output.
**6. Recognition rather than recall**
AI adaptation: Show users what the AI can do rather than requiring them to discover commands. Surface relevant capabilities contextually.

# Longitudinal Measurement
AI products change over time — models get updated, usage patterns shift, and quality can drift without anyone noticing. Longitudinal measurement is how you track quality across time and catch degradation before users do.
## What Changes Over Time
- **Model updates**: New model versions may improve some capabilities and regress others
- **Prompt drift**: System prompts accumulate edits that may interact in unexpected ways
- **Usage evolution**: Users discover new use cases that weren't tested for
- **Data drift**: The real-world inputs diverge from what was tested
- **Expectation drift**: Users' expectations change as they become more experienced
## What to Measure Longitudinally
- **Quality scores**: Track rubric scores on a consistent test set over time
- **Task success rates**: Monitor whether users are completing tasks at the same rate
- **Satisfaction signals**: Track trends in explicit and implicit satisfaction
- **Error rates**: Monitor failure frequency and type distribution
- **Latency**: Response time changes can indicate degradation
- **Engagement patterns**: Changes in usage frequency, depth, and breadth

# Output Quality Rubrics
Without a rubric, quality evaluation is subjective and inconsistent. A rubric defines what "good" means in concrete, measurable terms — so different evaluators reach the same conclusions.
## Core Quality Dimensions
- **Accuracy**: Is the information correct? Are claims verifiable? Are there hallucinations?
- **Relevance**: Does the output address what the user actually asked? Is everything included necessary?
- **Completeness**: Does the output cover everything needed? Are there gaps?
- **Helpfulness**: Can the user actually use this output to accomplish their goal?
- **Clarity**: Is the output easy to understand? Is it well-structured?
- **Tone appropriateness**: Does the output match the expected tone for the context?
- **Safety**: Is the output free from harmful, biased, or inappropriate content?
## Building a Rubric
For each dimension, define a scale:
**Example — Accuracy (1-5):**
- 5: All claims are verifiable and correct. No hallucinations.
- 4: Minor inaccuracies that don't affect usefulness. No hallucinations.

# Task Success Metrics
Output quality doesn't guarantee task success. The AI might produce a beautiful response that doesn't actually help the user do what they came to do. Task success metrics measure the end-to-end outcome.
## Defining Task Success
For each user task, define:
- **What does success look like?** The user completed their goal (sent the email, found the information, finished the design)
- **What are the success criteria?** Specific, observable conditions that indicate the task is done
- **What's the time expectation?** How long should this task take with AI assistance vs. without?
- **What's the quality bar?** Not just done, but done well enough
## Task Success Metrics
- **Task completion rate**: Percentage of users who complete the task (not just get a response)
- **Time to completion**: How long from first input to task done
- **Turns to completion**: How many back-and-forth exchanges needed
- **First-attempt success rate**: Did the AI's first response accomplish the task, or did it require iteration?
- **Intervention rate**: How often did the user need to correct, redirect, or override the AI?
- **Abandonment rate**: How often did users give up before completing the task?

# User Satisfaction Signals
Users rarely tell you directly whether they're satisfied. Most satisfaction signals are implicit — buried in behavior patterns that you have to design systems to capture and interpret.
## Explicit Satisfaction Signals
These are signals users give intentionally:
- **Thumbs up/down**: Direct quality rating
- **Star ratings**: Graded satisfaction
- **Written feedback**: Comments about what worked or didn't
- **NPS or satisfaction surveys**: Periodic overall assessment
- **Feature requests**: Signals of engagement even when expressing a gap
## Implicit Satisfaction Signals
These are behavioral signals that indicate satisfaction or dissatisfaction:
**Positive signals:**
- Using the output as-is (no edits)
- Copying the output
- Returning to use the feature again

# Context Window Design
Every AI model has a finite context window. Designing within this constraint — and designing the user experience around it — is a core skill for AI product design.
## The Context Window as a Design Material
The context window is not just a technical limitation. It's a design material:
- **What goes in**: System prompts, conversation history, retrieved documents, tool results, user preferences
- **What gets dropped**: Older messages, less relevant context, verbose instructions
- **What the user sees**: The conversation as presented may differ from what the model actually processes
Designers must understand context window allocation to design reliable experiences.
## Memory and Persistence
Users expect AI to remember. Design for different memory horizons:
- **Within-conversation memory**: What was said earlier in this chat. Usually handled by the context window itself.
- **Cross-conversation memory**: Preferences, past decisions, ongoing projects. Requires explicit memory systems.
- **Shared memory**: Context shared across multiple users or agents. Requires careful privacy design.
## Strategies for Limited Context
- **Summarisation**: Compress earlier conversation into summaries to free up tokens

# Conversation Patterns
Conversation between humans and AI follows predictable structural patterns. Designing these deliberately — rather than leaving them to model defaults — is core interaction design work.
## Turn-Taking Structure
Every human-AI conversation has a rhythm. The designer decides:
- **Turn length**: Short exchanges (chatbot-style) vs. long-form (essay generation). Match turn length to task complexity.
- **Turn initiation**: Who speaks first? Does the AI greet, or wait? Does it ask a clarifying question before acting?
- **Turn boundaries**: How does the user signal "I'm done"? How does the AI signal "I need more"?
## Repair Sequences
Conversations break down. Repair is how they recover:
- **Self-repair**: The AI detects its own error and corrects ("Actually, let me revise that...")
- **Other-repair**: The user corrects the AI ("No, I meant the other one")
- **Clarification requests**: The AI asks for disambiguation before proceeding
- **Graceful misunderstanding**: The AI acknowledges confusion without frustrating the user
Design repair sequences explicitly. Don't rely on the model to improvise them.
## Grounding

# Feedback Loops
Feedback loops are how users tell the AI what's working and what isn't. Designing these loops well is the difference between an AI that improves over time and one that repeats the same mistakes.
## Types of Feedback
- **Explicit feedback**: Thumbs up/down, star ratings, "this was helpful/not helpful" buttons
- **Implicit feedback**: Regeneration (user asks again), editing (user modifies the output), abandonment (user leaves)
- **Corrective feedback**: User provides the right answer ("No, I meant X not Y")
- **Preference feedback**: User chooses between alternatives ("I prefer option B")
- **Contextual feedback**: Feedback tied to a specific part of the output, not the whole response
## Designing for Correction
The most valuable feedback is correction — but it's also the hardest to design for:
- **Inline editing**: Let users edit AI output directly. Track what they change.
- **Partial acceptance**: Let users keep some parts and reject others.
- **Explanation requests**: "Why did you do it this way?" — the user's question reveals what went wrong.
- **Redo with guidance**: "Try again but make it more formal" — correction through re-prompting.
## Feedback Timing

# Frustration Detection

Most AI products treat every user message as having the same emotional weight. They don't. "Cancel my subscription." and "PLEASE just cancel my subscription!!!" deserve different responses. Frustration detection is the perception skill that picks up the signal so the rest of the system can adapt.

This is the unnamed skill that sits behind tone calibration, escalation design, and graceful repair. Without it, those skills can't fire at the right moment.

## Signals

**Linguistic**
- Capitalisation shifts: ALL CAPS, sudden "PLEASE", "URGENT"
- Punctuation density: `?!?!`, `....`, multiple `!!`
- Hedge-stripping: terse, demand-form ("just fix it", "stop")
- Repetition: same concept restated across turns
- Profanity (mild or strong)

# Generative UI
Generative UI is when the AI creates interface elements on the fly — forms, cards, charts, layouts — rather than responding with plain text. The interface itself becomes a model output.
## What Generative UI Changes
Traditional UI is designed ahead of time. Generative UI is created in the moment:
- **Static UI**: Designer creates all possible screens. Developer builds them. User navigates between them.
- **Generative UI**: The AI creates interface elements in response to user needs. No screen was pre-designed.
This shifts the designer's role from designing screens to designing the rules, constraints, and patterns the AI uses to generate screens.
## Design Constraints for Generated UI
The AI needs guardrails for what it generates:
- **Component library**: A defined set of components the AI can compose (cards, tables, forms, charts, buttons)
- **Layout rules**: Grid systems, spacing, hierarchy rules the AI must follow
- **Style boundaries**: Colour, typography, and visual style the AI must stay within
- **Interaction patterns**: How generated elements behave (clickable, editable, dismissible)
- **Accessibility requirements**: Generated UI must meet accessibility standards automatically
## When to Use Generative UI

# Mixed-Initiative Flow
Mixed-initiative interaction is when both the human and the AI can take the lead. The designer decides who drives at each moment — and how control transfers between them.
## Initiative Spectrum
Interactions sit on a spectrum:
- **User-driven**: The user gives instructions, the AI executes. The user controls pace, direction, and scope.
- **AI-driven**: The AI leads — asking questions, making suggestions, guiding the user through a process.
- **Shared**: Both parties contribute. The AI proposes, the user edits. The user starts, the AI finishes.
Most AI products default to user-driven. The interesting design space is in shared and AI-driven modes.
## Designing Initiative Handoffs
The moment control shifts from one party to the other is where most interactions fail. Design these transitions:
- **Explicit handoff**: "I've drafted three options. Which direction do you want to go?" — the AI clearly passes control.
- **Implicit handoff**: The AI stops generating and waits, signalling the user's turn through UI affordance.
- **Negotiated handoff**: "I could take this further or stop here for your input. What do you prefer?"
- **Forced handoff**: The AI encounters a decision it can't make and must hand back to the human.
## When the AI Should Lead

# Multimodal Orchestration

AI interactions increasingly span multiple modalities — text, images, voice, code, tools, structured data. Designing how these modalities work together is orchestration. The risk on every team: switching modality because it's *available*, not because it serves the user.

The point of multimodal isn't to use every modality. It's to use the right one at the right moment, and to handle the seams.

## Modality selection

Each modality has strengths:

- **Text**: precise, editable, referenceable. Best for instructions, explanations, and nuanced content.
- **Image**: spatial, holistic, immediate. Best for layouts, diagrams, and visual concepts.
- **Voice**: natural, hands-free, emotional. Best for conversational flow and accessibility.
- **Code**: executable, precise, verifiable. Best for technical specifications and automation.
- **Structured data**: tables, forms, JSON. Best for comparison, configuration, and data entry.

# Progressive Disclosure
Users don't understand what AI can do. Progressive disclosure is how you reveal capabilities at the right pace — preventing both overwhelm and underuse.
## The Mental Model Gap
Users arrive with mental models shaped by previous technology. They may:
- Treat the AI like a search engine (keyword queries)
- Treat it like a form (expecting rigid structure)
- Underestimate what it can do (asking for less than it offers)
- Overestimate what it can do (expecting perfection)
Progressive disclosure bridges the gap between what users think the AI does and what it actually does.
## Disclosure Strategies
- **On-demand hints**: Show capability suggestions contextually ("Did you know you can also ask me to...")
- **Escalating examples**: Start with simple use cases, reveal complex ones as the user gains confidence
- **Feature graduation**: Unlock advanced features after the user demonstrates comfort with basics
- **Contextual teaching**: When the user attempts something inefficiently, show a better approach
- **Capability boundaries**: Clearly communicate what the AI cannot do, not just what it can

# Chain-of-Thought Design
Chain-of-thought prompting asks the AI to show its reasoning step by step before arriving at an answer. When designed well, this produces more accurate, more nuanced, and more trustworthy outputs. When designed poorly, it produces verbose justification of bad answers.
## When Chain-of-Thought Helps
- **Complex reasoning**: Multi-step problems where the answer depends on intermediate conclusions
- **Ambiguous inputs**: When the AI needs to consider multiple interpretations
- **High-stakes outputs**: When you need to verify the reasoning, not just the answer
- **Creative exploration**: When generating ideas benefits from building on each step
- **Analytical tasks**: Comparisons, evaluations, and trade-off analyses
## When Chain-of-Thought Hurts
- **Simple lookups**: "What's the capital of France?" doesn't need step-by-step reasoning
- **Speed-critical responses**: Reasoning adds latency and token cost
- **Pattern-matching tasks**: Some tasks are better served by direct response
- **When reasoning is wrong**: The AI can reason convincingly toward an incorrect conclusion
## Designing Reasoning Chains
A reasoning chain has structure. Design it deliberately:

# Constraint Specification
Constraints are the rules that shape AI output — what format to use, how long to be, what to include, what to exclude. Well-specified constraints produce predictable, useful outputs. Vague constraints produce inconsistent results.
## Types of Constraints
**Format constraints:**
- Output structure (JSON, markdown, plain text, bullet points, prose)
- Section headings and organisation
- Required fields and optional fields
- Data types and schemas
**Length constraints:**
- Word count ranges (not exact numbers — models are bad at counting)
- Section length proportions ("spend 60% on analysis, 40% on recommendations")
- Minimum and maximum bounds
- Conciseness directives ("be brief" vs. "be thorough")
**Content constraints:**
- Topics to include and exclude

# Context Engineering
The context window is finite. What goes into it — and in what order — determines the quality of every output. Context engineering is the practice of deliberately designing the information architecture of the context window.
## The Context Budget
Every context window has a token budget. Allocate it deliberately:
- **System prompt**: The foundational instructions (typically 5-20% of the budget)
- **Retrieved context**: Documents, data, and information pulled in for the current task
- **Conversation history**: Previous turns in the conversation
- **User input**: The current request
- **Working space**: Room for the model to generate its response
These compete for space. More retrieved context means less conversation history. A longer system prompt means less room for everything else.
## Information Architecture in Context
Order matters. The model pays different amounts of attention to different positions:
- **Beginning**: High attention. Put your most important instructions here.
- **Middle**: Lower attention. This is where information can get lost in long contexts.
- **End**: High attention. The most recent information (user input) naturally goes here.

# Few-Shot Patterns
Few-shot prompting provides examples of input-output pairs that demonstrate the desired behavior. The AI learns the pattern from the examples and applies it to new inputs. The quality of examples directly determines the quality of outputs.
## Why Examples Work
Examples communicate what instructions alone cannot:
- **Implicit patterns**: The AI picks up on format, style, and reasoning patterns from examples without being told explicitly
- **Ambiguity resolution**: When instructions could be interpreted multiple ways, examples show which interpretation you want
- **Quality calibration**: Examples set the bar for output quality, length, and depth
- **Edge case handling**: Examples of tricky cases teach the AI how to handle similar situations
## Example Design Principles
**Diversity**: Examples should cover different scenarios, not repeat the same type
- Include easy cases, hard cases, and edge cases
- Vary the input format and content
- Show different valid output formats if applicable
**Clarity**: Each example should demonstrate one clear pattern
- Avoid examples that could be interpreted multiple ways

# Prompt Versioning
Prompts are code. They should be versioned, tested, reviewed, and deployed with the same rigor as software. Treating prompts as casual text that anyone can edit leads to quality regressions, inconsistent behavior, and debugging nightmares.
## Why Version Prompts
- **Accountability**: Know who changed what and when
- **Rollback**: Revert to a previous version when a change causes problems
- **Testing**: Compare performance of different versions
- **Collaboration**: Multiple people can work on prompts without overwriting each other
- **Audit trail**: Understand how the prompt evolved and why
## Versioning Practices
- **Source control**: Store prompts in version control (Git, etc.), not in application configuration
- **Meaningful commits**: Each change should explain what was changed and why
- **Change categories**: Classify changes as bug fixes, improvements, new features, or experiments
- **Review process**: Prompt changes should be reviewed before deployment, like code reviews
- **Semantic versioning**: Major changes (behavioral shift), minor changes (new capability), patches (bug fixes)
## Testing Prompt Changes

# System Prompt Structure
A system prompt is the most important piece of design in an AI product. It defines who the AI is, what it knows, how it behaves, and what it produces. It's the equivalent of a brand guide, interaction spec, and behavioral contract rolled into one document.
## Anatomy of a System Prompt
A well-structured system prompt has distinct sections, each serving a specific purpose:
**1. Identity and Role**
Who is the AI? What's its purpose? This anchors everything that follows.
- "You are a senior UX researcher helping design teams..."
- Keep it specific. "You are a helpful assistant" is too vague to produce consistent behavior.
**2. Context and Knowledge**
What does the AI know? What's its domain? What information is it working with?
- Domain boundaries: what it's an expert in and what's outside its scope
- Background information relevant to the task
- User context: who it's talking to and what they need
**3. Behavioral Rules**
How should the AI behave? What are the do's and don'ts?

# Template Design
A prompt template is a reusable prompt structure with variable slots that get filled at runtime. Templates create consistency across similar tasks and make prompt management scalable.
## Template Anatomy
A template has:
- **Fixed text**: The parts that stay the same every time (instructions, format, role)
- **Variables**: Slots that get filled with specific content (user input, retrieved data, configuration)
- **Conditional sections**: Parts that appear or disappear based on context
- **Default values**: What fills a variable if no specific value is provided
## Designing Variables
Each variable should be:
- **Named clearly**: `{user_query}` not `{input1}`
- **Typed**: Is it free text, a selection from options, a number, a boolean?
- **Bounded**: What are valid values? What's the maximum length?
- **Documented**: What is this variable for? Where does its value come from?
- **Defaulted**: What happens if the value is missing?

# Behavioral Consistency
Users build mental models of how the AI behaves. Consistency is what makes those models reliable. Inconsistency — even if each individual response is good — erodes trust.
## Dimensions of Consistency
- **Across sessions**: The AI should behave the same way whether it's the user's first conversation or their hundredth
- **Across topics**: Switching subjects shouldn't change the AI's personality or approach
- **Across modalities**: The AI should feel the same in chat, voice, and email
- **Across users**: Different users get the same quality and character (unless personalisation is designed)
- **Across time**: The AI shouldn't randomly change behavior after updates without user awareness
## Sources of Inconsistency
- **Temperature and sampling**: Randomness in generation creates natural variation
- **Context sensitivity**: Different conversation histories lead to different behaviors
- **Prompt drift**: System prompts evolve over time without consistency checks
- **Edge cases**: Unusual inputs trigger unpredictable responses
- **Model updates**: New model versions may shift behavior subtly
## Designing for Consistency

# Cultural Adaptation
AI products are used globally. Cultural adaptation means designing AI behavior that respects and responds to different cultural contexts — not just translating words, but adapting interaction patterns, values, and communication styles.
## Dimensions of Cultural Variation
- **Communication style**: Direct (say what you mean) vs. indirect (imply, suggest, contextualise)
- **Formality norms**: When titles and honorifics matter. When first names are appropriate.
- **Power distance**: How authority and hierarchy affect communication expectations
- **Individualism vs. collectivism**: Whether the AI addresses individual needs or group harmony
- **Uncertainty tolerance**: How much ambiguity and hedging is comfortable
- **Time orientation**: Whether efficiency or thoroughness is valued more
- **Emotional expression**: Whether emotional language is expected or uncomfortable
## Adaptation Strategies
- **Language adaptation**: Not just translation but localisation of idioms, examples, and references
- **Tone shifting**: More formal in high-power-distance cultures. More direct in low-context cultures.
- **Content adaptation**: Examples and references that are culturally relevant and appropriate
- **Interaction pattern adaptation**: Some cultures expect more back-and-forth before getting to the point

# Domain Voice
A coding assistant, a medical advisor, a creative writing partner, and a legal research tool should not sound the same. Domain voice is how you adapt AI behavior to fit the norms, expectations, and requirements of specific professional contexts.
## Domain Voice Components
- **Vocabulary**: The terminology and jargon appropriate to the domain
- **Precision level**: How exact the AI needs to be (legal and medical demand high precision; creative work tolerates ambiguity)
- **Citation norms**: Whether and how the AI references sources (academic style, legal citation, informal attribution)
- **Risk tolerance**: How cautious the AI should be about uncertain outputs
- **Authority stance**: Whether the AI positions itself as expert, assistant, or peer
- **Ethical boundaries**: Domain-specific ethical considerations (medical ethics, legal privilege, creative attribution)
## Domain Voice Profiles
**Medical/Health:**
- High precision, extensive hedging
- Always recommends professional consultation
- Careful distinction between information and advice
- Sensitive to patient dignity and autonomy

# Emotional Design
Users bring emotions to AI interactions. Frustration when it doesn't work. Delight when it does something unexpected. Distress when dealing with difficult topics. The AI's response to these emotions is a design decision.
## Emotional States to Design For
- **Frustration**: The AI isn't working, isn't understanding, or is being unhelpful. The user is losing patience.
- **Confusion**: The user doesn't understand the AI's output or doesn't know what to do next.
- **Delight**: The AI exceeded expectations. The user is pleasantly surprised.
- **Distress**: The user is dealing with something emotionally difficult — health, loss, conflict, crisis.
- **Boredom**: The AI is too slow, too verbose, or too repetitive.
- **Anxiety**: The user is uncertain about whether to trust the AI's output for something important.
- **Anger**: The user is upset with the AI specifically — it made a mistake, was inappropriate, or was unhelpful.
## Response Strategies
**For frustration:**
- Acknowledge the difficulty without being patronising
- Simplify — offer a more direct path
- Don't repeat the same failed approach

# Error Personality
Every AI makes mistakes. Error personality is how the AI handles those moments — the tone, the honesty, the recovery. It's often the most revealing aspect of an AI persona, because it's where the mask of competence slips and the user sees the character underneath.
## Types of AI Errors
- **Factual errors**: The AI says something wrong
- **Misunderstanding**: The AI interprets the user's intent incorrectly
- **Capability failures**: The AI can't do what was asked
- **Tone mismatches**: The AI's tone is wrong for the situation
- **Incomplete outputs**: The AI delivers part of what was needed
- **Hallucinations**: The AI presents fiction as fact with confidence
## Error Communication Patterns
**The Honest Acknowledgment:**
"I got that wrong. Here's the corrected version." — Direct, no excessive apology, immediately fixes the problem.
**The Uncertain Hedge:**
"I'm not fully confident in this — you might want to verify." — Flags uncertainty before the user discovers the error.
**The Redirect:**

# Persona Architecture
An AI persona is not a gimmick. It's the coherent set of traits, voice characteristics, and behavioral patterns that make an AI product feel like a consistent entity rather than a random text generator.
## Persona Components
- **Character traits**: Is the AI warm or professional? Playful or serious? Confident or cautious? Define 3-5 core traits.
- **Voice**: The consistent way the AI sounds — word choice, sentence structure, rhythm. A financial AI sounds different from a creative writing AI.
- **Knowledge stance**: What does the AI present itself as knowing? Expert, generalist, learning companion, or tool?
- **Relationship model**: How does the AI relate to the user? Assistant, collaborator, coach, peer, or service provider?
- **Boundaries**: What won't this persona do? Joke about? Engage with? The boundaries define the persona as much as the traits do.
## Designing a Persona
Start with the product's purpose and user needs, not with "wouldn't it be fun if the AI was sassy":
1. **Who are the users?** Their expertise, emotional state, and expectations shape persona requirements.
2. **What's the task?** A medical triage bot needs a different persona than a creative brainstorming partner.
3. **What relationship serves the user?** Sometimes authority builds trust. Sometimes equality builds rapport.
4. **What's the brand?** The AI persona must align with the organisation's broader identity.
5. **What are the risks?** An overly casual persona in a serious context causes harm. An overly formal persona in a creative context stifles use.

# Tone Calibration
Tone is how the persona sounds in a specific moment. The persona stays constant. The tone adapts. A warm, helpful persona might use an encouraging tone when teaching and a direct tone when correcting.
## Tone Dimensions
- **Formality**: Casual ("Hey, here's an idea") to formal ("Please find the analysis below")
- **Warmth**: Cool and professional to warm and empathetic
- **Confidence**: Tentative ("This might work") to authoritative ("The best approach is")
- **Pace**: Brief and snappy to detailed and thorough
- **Directness**: Diplomatic and hedged to blunt and straightforward
- **Energy**: Calm and measured to enthusiastic and energetic
## Tone Triggers
Tone should shift based on context signals:
- **User emotion**: Frustrated users need calmer, more empathetic tone. Excited users can handle more energy.
- **Task type**: Creative tasks benefit from playful tone. Analytical tasks benefit from precise tone.
- **Stakes**: High-stakes outputs need careful, confident tone. Low-stakes outputs can be lighter.
- **Conversation stage**: Opening exchanges are warmer. Deep working sessions are more direct.

# Bias Detection Design
AI systems inherit biases from training data, amplify them through pattern-matching, and embed them in outputs that appear authoritative. Bias detection design creates the workflows, processes, and interfaces that help teams find and fix bias before users encounter it.
## Types of Bias in AI Products
- **Representation bias**: Some groups are overrepresented or underrepresented in outputs (images, examples, personas)
- **Performance bias**: The AI works better for some users than others (languages, accents, cultural contexts)
- **Framing bias**: The AI presents information in ways that favour certain perspectives
- **Allocation bias**: AI-driven decisions distribute resources or opportunities unevenly
- **Association bias**: The AI links concepts in stereotypical ways
## Designing Bias Detection Workflows
Bias detection is a team practice, not a one-time audit:
- **Regular review cycles**: Schedule periodic reviews of AI outputs for bias patterns
- **Diverse review panels**: Include reviewers from different backgrounds, cultures, and perspectives
- **Structured evaluation**: Use rubrics and checklists, not intuition
- **Real-world sampling**: Test with real user inputs, not just curated test cases
- **Longitudinal monitoring**: Bias can emerge over time as usage patterns change

# Consent and Agency
AI products make decisions, take actions, and process information on behalf of users. Consent and agency design ensures users remain in control — understanding what the AI does, agreeing to it, and being able to override it.
## Informed Consent for AI
Users should understand and agree to:
- **What data the AI uses**: Conversation history, personal data, uploaded documents, browsing behaviour
- **What the AI does with it**: Training, personalisation, sharing with third parties, storage
- **What actions the AI takes**: Sending messages, making changes, accessing systems
- **What the AI can't do**: Limitations that might affect the user's expectations
Consent is not a checkbox at sign-up. It's an ongoing design challenge throughout the experience.
## Designing for Agency
Agency means the user feels — and is — in control:
- **Opt-in over opt-out**: AI features should be activated by the user, not imposed
- **Reversibility**: AI actions should be undoable wherever possible
- **Override mechanisms**: The user can always stop, redirect, or override the AI
- **Exit paths**: The user can disengage from AI assistance at any point without penalty

# Escalation Design
Escalation is what happens when the AI reaches the boundary of what it should handle alone. Designing escalation well means the user gets help instead of a dead end — and the AI knows its limits.
## Escalation Triggers
The AI should escalate when:
- **Confidence is low**: The AI isn't sure its output is correct or helpful
- **Stakes are high**: The decision has significant consequences (financial, medical, legal, safety)
- **Emotional distress**: The user shows signs of crisis, distress, or vulnerability
- **Ambiguity is unresolvable**: The AI can't determine intent even after clarification
- **Scope boundary**: The request is outside what the AI is designed to handle
- **Policy boundary**: The request approaches or crosses a guardrail
- **Conflict**: The user disagrees with the AI and the disagreement can't be resolved
## Escalation Types
- **To human support**: Transfer to a human agent with full context
- **To the user themselves**: "This decision is yours to make" — handing back agency
- **To a specialist**: Routing to domain-specific help (medical, legal, technical)

# Guardrail Design
Guardrails are the behavioral boundaries that define what an AI product will and won't do. They're not just safety constraints — they're design decisions that shape the entire user experience.
## Types of Guardrails
- **Content guardrails**: What topics the AI will and won't discuss. What it generates and refuses to generate.
- **Action guardrails**: What the AI can do in the world — send emails, make purchases, delete data — and what requires human approval.
- **Tone guardrails**: How the AI communicates — what language it uses, how formal or casual, when it's direct vs. diplomatic.
- **Scope guardrails**: What the AI considers in and out of scope for its role. A coding assistant shouldn't give medical advice.
- **Confidence guardrails**: When the AI should express uncertainty, hedge, or refuse rather than guessing.
## Designing Guardrails as Product Decisions
Every guardrail is a product decision with tradeoffs:
- **Too strict**: The product feels limited, frustrating, and paternalistic. Users route around the guardrails.
- **Too loose**: The product causes harm, loses trust, and creates liability.
- **Inconsistent**: Users can't predict what the AI will and won't do, eroding trust.
The goal is guardrails that feel like good judgment, not arbitrary restrictions.
## Guardrail Specification

# Harm Anticipation

Harm anticipation is systematically thinking through how an AI product could cause harm — before it does. Preventive design, not reactive crisis management.

The work is unglamorous and easy to skip. Done well, it produces specific testable mitigations. Done badly, it produces a doc nobody reads.

## Categories of AI harm

- **Direct harm**: the AI outputs something harmful — dangerous advice, discriminatory content, privacy violations
- **Facilitated harm**: the AI helps a user do something harmful, even if the AI's output itself is benign
- **Emergent harm**: harmful patterns from scale or interaction effects, not from any single output
- **Omission harm**: the AI fails to act when it should — not flagging a crisis, not escalating
- **Erosion harm**: gradual negative effects — dependency, deskilling, manipulation, trust erosion

## Structured anticipation

# Transparency Patterns
Transparency in AI products means making the system's knowledge, limitations, and confidence visible to users. It's how you build warranted trust — trust based on understanding, not blind faith.
## What to Make Transparent
- **Source**: Where did the AI get this information? Training data, retrieved documents, user input, inference?
- **Confidence**: How certain is the AI? Is this a well-supported answer or a best guess?
- **Limitations**: What doesn't the AI know? What can't it do? Where does its knowledge end?
- **Process**: How did the AI arrive at this output? What steps did it take?
- **Identity**: This is an AI, not a human. Never obscure this.
## Transparency Patterns
- **Confidence indicators**: Visual or textual signals of certainty ("I'm fairly confident" vs. "I'm not sure about this")
- **Source attribution**: Citing where information came from
- **Reasoning traces**: Showing the AI's step-by-step thinking
- **Limitation disclosure**: Proactively stating what the AI can't do or doesn't know
- **Model cards**: High-level descriptions of what the AI is, how it works, and what it's good and bad at
- **Uncertainty highlighting**: Visually distinguishing confident outputs from uncertain ones

# Trust Calibration

Calibrated trust is the difference between an AI that augments user judgment and one that displaces it. Overtrust causes harm when the AI is wrong. Undertrust wastes the AI when it's right. Both failure modes are common, and neither shows up in standard accuracy metrics.

Designing for trust means giving users the information they need to update their trust appropriately, turn by turn.

## What shapes user trust in the moment

- **Surface confidence** — how certain the AI sounds, regardless of whether it should
- **Track record** — prior interactions in this and previous sessions
- **Stakes legibility** — how clearly the user understands what could go wrong
- **Source visibility** — whether the AI shows reasoning, sources, or alternatives
- **Persona fit** — a "professional" persona gets more trust than a "friendly" one for the same content

These shape trust whether you design for them or not. Designing for them deliberately is what trust calibration is.

# Value Specification
Values are abstract. AI systems need concrete rules. Value specification is the design work of translating organisational principles and user expectations into implementable constraints.
## The Translation Problem
Organisations say things like "be helpful" and "be responsible." These are useless as system constraints because they conflict:
- Being maximally helpful might mean giving dangerous information
- Being maximally responsible might mean refusing to help at all
- Being "fair" means different things in different contexts
The designer's job is to resolve these tensions into specific, testable rules.
## Value Hierarchy
Not all values are equal. Establish a hierarchy:
1. **Safety**: Prevent harm to users and others. This overrides everything.
2. **Accuracy**: Don't mislead. When uncertain, say so.
3. **Helpfulness**: Actually accomplish what the user needs.
4. **Respect**: Treat users as capable adults. Don't patronise.
5. **Brand alignment**: Reflect the organisation's identity and tone.

# Agent Role Design
In a multi-agent system, each agent needs a clearly defined role — what it does, what it knows, what it's responsible for, and where its authority ends. Without clear roles, agents duplicate work, conflict with each other, or leave gaps.
## Defining an Agent Role
For each agent in the system, specify:
- **Purpose**: What is this agent for? One sentence describing its reason to exist.
- **Capabilities**: What can this agent do? List specific actions and outputs.
- **Knowledge scope**: What does this agent know about? What domains, data, and context does it have access to?
- **Authority**: What decisions can this agent make autonomously? What requires approval?
- **Boundaries**: What is explicitly outside this agent's scope? Where does it stop and hand off?
- **Success criteria**: How do you know this agent is doing its job well?
## Role Design Principles
- **Single responsibility**: Each agent should have one clear purpose. If you need a paragraph to explain what it does, it's doing too much.
- **Clear boundaries**: The line between one agent's scope and another's should be unambiguous. No overlapping authority without explicit conflict resolution.
- **Minimal coupling**: Agents should be able to do their work with minimal dependencies on other agents. Share results, not process.
- **Appropriate autonomy**: The level of autonomous decision-making should match the stakes and the agent's reliability in that domain.

# Failure Recovery
Agents fail. Networks time out, models hallucinate, tools error, and edge cases surprise. Failure recovery design determines whether a failure becomes a dead end or a graceful detour.
## Failure Types in Multi-Agent Systems
- **Agent failure**: A single agent crashes, times out, or produces invalid output
- **Handoff failure**: Context is lost or corrupted during transfer between agents
- **Coordination failure**: Agents conflict, deadlock, or produce inconsistent results
- **Resource failure**: External tools, APIs, or data sources are unavailable
- **Cascading failure**: One agent's failure causes downstream agents to fail
## Recovery Strategies
- **Retry**: Try the same operation again. Works for transient errors (network timeouts, rate limits). Set a retry limit to avoid infinite loops.
- **Fallback**: Switch to an alternative approach. A different agent, a simpler method, or a cached result.
- **Escalation**: Pass the problem to a more capable agent or to a human. Used when the failure is beyond the current agent's ability to resolve.
- **Graceful degradation**: Deliver a partial result rather than nothing. Tell the user what worked and what didn't.
- **Compensation**: Undo the effects of a partially completed workflow before retrying or escalating.
## Designing Recovery Paths

# Handoff Protocols
A handoff is the moment one agent passes work to another — or to a human. It's where multi-agent systems most commonly fail. A dropped handoff means lost context, repeated work, or abandoned tasks.
## Anatomy of a Handoff
Every handoff has:
- **Trigger**: What causes the handoff? (task completion, scope boundary, failure, user request)
- **Source**: Who is handing off?
- **Destination**: Who is receiving?
- **Payload**: What information transfers? (context, partial results, user state, instructions)
- **Acknowledgment**: How does the source know the destination received the handoff?
- **User experience**: What does the user see during the handoff?
## Handoff Types
- **Sequential**: Agent A finishes, passes results to Agent B who continues. Like a relay race.
- **Parallel fan-out**: One agent distributes subtasks to multiple agents simultaneously.
- **Parallel fan-in**: Multiple agents' results converge back to one agent for synthesis.
- **Escalation**: An agent can't handle the task and passes up to a more capable agent or human.

# Human-in-the-Loop
Human-in-the-loop design defines when, where, and how humans intervene in automated workflows. Too little human involvement and the system makes dangerous mistakes. Too much and you've just built an expensive notification system.
## Intervention Types
- **Approval gates**: The system pauses and waits for human approval before proceeding
- **Review checkpoints**: The system presents results for human review but can continue if no objection
- **Correction opportunities**: The system shows its work and the human can edit before it's finalised
- **Override controls**: The human can stop, redirect, or undo the system's actions at any time
- **Monitoring dashboards**: The human passively observes the system and intervenes only when needed
## When to Require Human Intervention
- **High stakes**: Actions that are expensive, irreversible, or affect many people
- **Low confidence**: The system is uncertain about the right action
- **Novel situations**: The input or context is outside the system's training distribution
- **Ethical judgments**: Decisions that require moral reasoning or value trade-offs
- **Legal requirements**: Regulatory or compliance requirements mandate human review
- **User request**: The user explicitly asks for human involvement

# Observability Design
You can't improve what you can't see. Observability design makes the internal workings of multi-agent systems visible — so designers can understand user experience problems, developers can debug failures, and teams can improve the system over time.
## What to Make Observable
- **Workflow execution**: Which agents were involved, in what order, with what results
- **Decision points**: What decisions were made, what alternatives were considered, why one was chosen
- **Handoff details**: What context transferred between agents, was anything lost
- **Timing**: How long each agent took, where bottlenecks occur
- **Failures**: What failed, how it was recovered, what the user experienced
- **Quality signals**: Output quality scores, user satisfaction signals, task success markers
## Observability for Different Audiences
**For designers:**
- User journey view: What did the user experience across the whole workflow?
- Pain point identification: Where did users struggle, abandon, or express frustration?
- Quality patterns: Which outputs are high and low quality, and why?
**For developers:**

# State Management

In a multi-agent system, state is the shared truth about what's happened, what's in progress, and what's been decided. Without state management, agents work with stale or conflicting information — and the user pays the cost in repeated questions, contradictory answers, and lost progress.

State management is the *plumbing* skill of multi-agent design. Get it wrong and every other skill in this plugin gets harder.

## Types of state

- **Task state**: where the overall task is in its lifecycle. Which subtasks are complete, in progress, or pending.
- **Context state**: what each agent knows. What has been shared, summarised, or dropped.
- **User state**: preferences, history, and current emotional state.
- **Decision state**: decisions made, options considered, options rejected (and why).
- **Error state**: what has failed, been retried, been escalated.

## State architecture patterns

# Task Decomposition
Users come with goals, not subtasks. Task decomposition is how a multi-agent system breaks a complex user goal into pieces that individual agents can handle — and then reassembles the results into something coherent.
## Decomposition Strategies
- **Sequential decomposition**: Break the goal into ordered steps. Step 1 must complete before Step 2 starts.
- **Parallel decomposition**: Break the goal into independent parts that can be worked on simultaneously.
- **Hierarchical decomposition**: Break the goal into sub-goals, then break each sub-goal into tasks.
- **Conditional decomposition**: The next step depends on the result of the current step. Different results lead to different paths.
- **Iterative decomposition**: Start with a rough version, then refine through multiple passes.
## Designing Decomposition Rules
For each type of user goal the system handles:
- **What's the entry point?** How does the system receive the goal?
- **What are the subtasks?** List all possible subtasks for this goal type.
- **What are the dependencies?** Which subtasks depend on others' outputs?
- **What's the critical path?** Which sequence of subtasks determines the minimum completion time?
- **What can be parallelised?** Which subtasks can run simultaneously?

# Comparative Evaluation
Absolute quality scores are useful but limited. Comparative evaluation — putting outputs side by side and asking which is better — often reveals quality differences that rubrics miss.
## Comparison Methods
- **A/B testing**: Show different users different versions and compare outcomes
- **Side-by-side evaluation**: Show evaluators two outputs for the same input and ask which is better
- **Preference ranking**: Show evaluators multiple outputs and rank them from best to worst
- **Paired comparison**: Compare every pair of options to build a complete ranking
- **Elo rating**: Use tournament-style comparisons to develop continuous quality scores
## Designing A/B Tests for AI
A/B testing AI is different from A/B testing UI:
- **Variance is high**: The same prompt can produce different outputs, so you need more samples
- **Context matters**: The same change might help for one task and hurt for another
- **Metrics lag**: AI quality changes may take time to show up in user behavior
- **Interaction effects**: A change to one part of the conversation affects all subsequent parts
Design A/B tests with:

# Failure Taxonomy
Not all AI failures are the same. A hallucination is different from a refusal, which is different from a tone mismatch. A failure taxonomy classifies failure types so teams can track, prioritise, and address them systematically.
## Failure Categories
**Content Failures:**
- **Hallucination**: The AI presents false information as fact
- **Inaccuracy**: The AI gets details wrong (dates, numbers, names)
- **Incompleteness**: The AI misses important information
- **Irrelevance**: The AI's response doesn't address the user's actual question
- **Contradiction**: The AI contradicts itself within or across responses
**Behavioral Failures:**
- **Inappropriate refusal**: The AI refuses a reasonable request
- **Missing refusal**: The AI fulfils a request it should have declined
- **Tone mismatch**: The AI's tone is wrong for the context
- **Persona break**: The AI drops out of its defined persona
- **Over-generation**: The AI produces far more than needed

# Heuristic Evaluation for AI
Nielsen's 10 usability heuristics were designed for traditional software. AI products need adapted heuristics that address the unique challenges of probabilistic, generative, and conversational systems.
## Classic Heuristics, Adapted for AI
**1. Visibility of system status**
AI adaptation: The user should always know what the AI is doing, what it's working with, and how confident it is. Progress indicators for generation. Transparency about data sources.
**2. Match between system and real world**
AI adaptation: The AI should use language and concepts the user understands. Don't expose model internals. Frame capabilities in terms of user tasks, not technical features.
**3. User control and freedom**
AI adaptation: Users must be able to stop generation, undo AI actions, edit outputs, and override suggestions. AI autonomy should always have an exit.
**4. Consistency and standards**
AI adaptation: The AI should behave consistently across similar requests. Same input type should produce same output format. Persona should be stable.
**5. Error prevention**
AI adaptation: Design prompts and interfaces that guide users toward effective interactions. Suggest clarifications before producing low-quality output.
**6. Recognition rather than recall**
AI adaptation: Show users what the AI can do rather than requiring them to discover commands. Surface relevant capabilities contextually.

# Longitudinal Measurement
AI products change over time — models get updated, usage patterns shift, and quality can drift without anyone noticing. Longitudinal measurement is how you track quality across time and catch degradation before users do.
## What Changes Over Time
- **Model updates**: New model versions may improve some capabilities and regress others
- **Prompt drift**: System prompts accumulate edits that may interact in unexpected ways
- **Usage evolution**: Users discover new use cases that weren't tested for
- **Data drift**: The real-world inputs diverge from what was tested
- **Expectation drift**: Users' expectations change as they become more experienced
## What to Measure Longitudinally
- **Quality scores**: Track rubric scores on a consistent test set over time
- **Task success rates**: Monitor whether users are completing tasks at the same rate
- **Satisfaction signals**: Track trends in explicit and implicit satisfaction
- **Error rates**: Monitor failure frequency and type distribution
- **Latency**: Response time changes can indicate degradation
- **Engagement patterns**: Changes in usage frequency, depth, and breadth

# Output Quality Rubrics
Without a rubric, quality evaluation is subjective and inconsistent. A rubric defines what "good" means in concrete, measurable terms — so different evaluators reach the same conclusions.
## Core Quality Dimensions
- **Accuracy**: Is the information correct? Are claims verifiable? Are there hallucinations?
- **Relevance**: Does the output address what the user actually asked? Is everything included necessary?
- **Completeness**: Does the output cover everything needed? Are there gaps?
- **Helpfulness**: Can the user actually use this output to accomplish their goal?
- **Clarity**: Is the output easy to understand? Is it well-structured?
- **Tone appropriateness**: Does the output match the expected tone for the context?
- **Safety**: Is the output free from harmful, biased, or inappropriate content?
## Building a Rubric
For each dimension, define a scale:
**Example — Accuracy (1-5):**
- 5: All claims are verifiable and correct. No hallucinations.
- 4: Minor inaccuracies that don't affect usefulness. No hallucinations.

# Task Success Metrics
Output quality doesn't guarantee task success. The AI might produce a beautiful response that doesn't actually help the user do what they came to do. Task success metrics measure the end-to-end outcome.
## Defining Task Success
For each user task, define:
- **What does success look like?** The user completed their goal (sent the email, found the information, finished the design)
- **What are the success criteria?** Specific, observable conditions that indicate the task is done
- **What's the time expectation?** How long should this task take with AI assistance vs. without?
- **What's the quality bar?** Not just done, but done well enough
## Task Success Metrics
- **Task completion rate**: Percentage of users who complete the task (not just get a response)
- **Time to completion**: How long from first input to task done
- **Turns to completion**: How many back-and-forth exchanges needed
- **First-attempt success rate**: Did the AI's first response accomplish the task, or did it require iteration?
- **Intervention rate**: How often did the user need to correct, redirect, or override the AI?
- **Abandonment rate**: How often did users give up before completing the task?

# User Satisfaction Signals
Users rarely tell you directly whether they're satisfied. Most satisfaction signals are implicit — buried in behavior patterns that you have to design systems to capture and interpret.
## Explicit Satisfaction Signals
These are signals users give intentionally:
- **Thumbs up/down**: Direct quality rating
- **Star ratings**: Graded satisfaction
- **Written feedback**: Comments about what worked or didn't
- **NPS or satisfaction surveys**: Periodic overall assessment
- **Feature requests**: Signals of engagement even when expressing a gap
## Implicit Satisfaction Signals
These are behavioral signals that indicate satisfaction or dissatisfaction:
**Positive signals:**
- Using the output as-is (no edits)
- Copying the output
- Returning to use the feature again

# Context Window Design
Every AI model has a finite context window. Designing within this constraint — and designing the user experience around it — is a core skill for AI product design.
## The Context Window as a Design Material
The context window is not just a technical limitation. It's a design material:
- **What goes in**: System prompts, conversation history, retrieved documents, tool results, user preferences
- **What gets dropped**: Older messages, less relevant context, verbose instructions
- **What the user sees**: The conversation as presented may differ from what the model actually processes
Designers must understand context window allocation to design reliable experiences.
## Memory and Persistence
Users expect AI to remember. Design for different memory horizons:
- **Within-conversation memory**: What was said earlier in this chat. Usually handled by the context window itself.
- **Cross-conversation memory**: Preferences, past decisions, ongoing projects. Requires explicit memory systems.
- **Shared memory**: Context shared across multiple users or agents. Requires careful privacy design.
## Strategies for Limited Context
- **Summarisation**: Compress earlier conversation into summaries to free up tokens

# Conversation Patterns
Conversation between humans and AI follows predictable structural patterns. Designing these deliberately — rather than leaving them to model defaults — is core interaction design work.
## Turn-Taking Structure
Every human-AI conversation has a rhythm. The designer decides:
- **Turn length**: Short exchanges (chatbot-style) vs. long-form (essay generation). Match turn length to task complexity.
- **Turn initiation**: Who speaks first? Does the AI greet, or wait? Does it ask a clarifying question before acting?
- **Turn boundaries**: How does the user signal "I'm done"? How does the AI signal "I need more"?
## Repair Sequences
Conversations break down. Repair is how they recover:
- **Self-repair**: The AI detects its own error and corrects ("Actually, let me revise that...")
- **Other-repair**: The user corrects the AI ("No, I meant the other one")
- **Clarification requests**: The AI asks for disambiguation before proceeding
- **Graceful misunderstanding**: The AI acknowledges confusion without frustrating the user
Design repair sequences explicitly. Don't rely on the model to improvise them.
## Grounding

# Feedback Loops
Feedback loops are how users tell the AI what's working and what isn't. Designing these loops well is the difference between an AI that improves over time and one that repeats the same mistakes.
## Types of Feedback
- **Explicit feedback**: Thumbs up/down, star ratings, "this was helpful/not helpful" buttons
- **Implicit feedback**: Regeneration (user asks again), editing (user modifies the output), abandonment (user leaves)
- **Corrective feedback**: User provides the right answer ("No, I meant X not Y")
- **Preference feedback**: User chooses between alternatives ("I prefer option B")
- **Contextual feedback**: Feedback tied to a specific part of the output, not the whole response
## Designing for Correction
The most valuable feedback is correction — but it's also the hardest to design for:
- **Inline editing**: Let users edit AI output directly. Track what they change.
- **Partial acceptance**: Let users keep some parts and reject others.
- **Explanation requests**: "Why did you do it this way?" — the user's question reveals what went wrong.
- **Redo with guidance**: "Try again but make it more formal" — correction through re-prompting.
## Feedback Timing

# Frustration Detection

Most AI products treat every user message as having the same emotional weight. They don't. "Cancel my subscription." and "PLEASE just cancel my subscription!!!" deserve different responses. Frustration detection is the perception skill that picks up the signal so the rest of the system can adapt.

This is the unnamed skill that sits behind tone calibration, escalation design, and graceful repair. Without it, those skills can't fire at the right moment.

## Signals

**Linguistic**
- Capitalisation shifts: ALL CAPS, sudden "PLEASE", "URGENT"
- Punctuation density: `?!?!`, `....`, multiple `!!`
- Hedge-stripping: terse, demand-form ("just fix it", "stop")
- Repetition: same concept restated across turns
- Profanity (mild or strong)

# Generative UI
Generative UI is when the AI creates interface elements on the fly — forms, cards, charts, layouts — rather than responding with plain text. The interface itself becomes a model output.
## What Generative UI Changes
Traditional UI is designed ahead of time. Generative UI is created in the moment:
- **Static UI**: Designer creates all possible screens. Developer builds them. User navigates between them.
- **Generative UI**: The AI creates interface elements in response to user needs. No screen was pre-designed.
This shifts the designer's role from designing screens to designing the rules, constraints, and patterns the AI uses to generate screens.
## Design Constraints for Generated UI
The AI needs guardrails for what it generates:
- **Component library**: A defined set of components the AI can compose (cards, tables, forms, charts, buttons)
- **Layout rules**: Grid systems, spacing, hierarchy rules the AI must follow
- **Style boundaries**: Colour, typography, and visual style the AI must stay within
- **Interaction patterns**: How generated elements behave (clickable, editable, dismissible)
- **Accessibility requirements**: Generated UI must meet accessibility standards automatically
## When to Use Generative UI

# Mixed-Initiative Flow
Mixed-initiative interaction is when both the human and the AI can take the lead. The designer decides who drives at each moment — and how control transfers between them.
## Initiative Spectrum
Interactions sit on a spectrum:
- **User-driven**: The user gives instructions, the AI executes. The user controls pace, direction, and scope.
- **AI-driven**: The AI leads — asking questions, making suggestions, guiding the user through a process.
- **Shared**: Both parties contribute. The AI proposes, the user edits. The user starts, the AI finishes.
Most AI products default to user-driven. The interesting design space is in shared and AI-driven modes.
## Designing Initiative Handoffs
The moment control shifts from one party to the other is where most interactions fail. Design these transitions:
- **Explicit handoff**: "I've drafted three options. Which direction do you want to go?" — the AI clearly passes control.
- **Implicit handoff**: The AI stops generating and waits, signalling the user's turn through UI affordance.
- **Negotiated handoff**: "I could take this further or stop here for your input. What do you prefer?"
- **Forced handoff**: The AI encounters a decision it can't make and must hand back to the human.
## When the AI Should Lead

# Multimodal Orchestration

AI interactions increasingly span multiple modalities — text, images, voice, code, tools, structured data. Designing how these modalities work together is orchestration. The risk on every team: switching modality because it's *available*, not because it serves the user.

The point of multimodal isn't to use every modality. It's to use the right one at the right moment, and to handle the seams.

## Modality selection

Each modality has strengths:

- **Text**: precise, editable, referenceable. Best for instructions, explanations, and nuanced content.
- **Image**: spatial, holistic, immediate. Best for layouts, diagrams, and visual concepts.
- **Voice**: natural, hands-free, emotional. Best for conversational flow and accessibility.
- **Code**: executable, precise, verifiable. Best for technical specifications and automation.
- **Structured data**: tables, forms, JSON. Best for comparison, configuration, and data entry.

# Progressive Disclosure
Users don't understand what AI can do. Progressive disclosure is how you reveal capabilities at the right pace — preventing both overwhelm and underuse.
## The Mental Model Gap
Users arrive with mental models shaped by previous technology. They may:
- Treat the AI like a search engine (keyword queries)
- Treat it like a form (expecting rigid structure)
- Underestimate what it can do (asking for less than it offers)
- Overestimate what it can do (expecting perfection)
Progressive disclosure bridges the gap between what users think the AI does and what it actually does.
## Disclosure Strategies
- **On-demand hints**: Show capability suggestions contextually ("Did you know you can also ask me to...")
- **Escalating examples**: Start with simple use cases, reveal complex ones as the user gains confidence
- **Feature graduation**: Unlock advanced features after the user demonstrates comfort with basics
- **Contextual teaching**: When the user attempts something inefficiently, show a better approach
- **Capability boundaries**: Clearly communicate what the AI cannot do, not just what it can

# Chain-of-Thought Design
Chain-of-thought prompting asks the AI to show its reasoning step by step before arriving at an answer. When designed well, this produces more accurate, more nuanced, and more trustworthy outputs. When designed poorly, it produces verbose justification of bad answers.
## When Chain-of-Thought Helps
- **Complex reasoning**: Multi-step problems where the answer depends on intermediate conclusions
- **Ambiguous inputs**: When the AI needs to consider multiple interpretations
- **High-stakes outputs**: When you need to verify the reasoning, not just the answer
- **Creative exploration**: When generating ideas benefits from building on each step
- **Analytical tasks**: Comparisons, evaluations, and trade-off analyses
## When Chain-of-Thought Hurts
- **Simple lookups**: "What's the capital of France?" doesn't need step-by-step reasoning
- **Speed-critical responses**: Reasoning adds latency and token cost
- **Pattern-matching tasks**: Some tasks are better served by direct response
- **When reasoning is wrong**: The AI can reason convincingly toward an incorrect conclusion
## Designing Reasoning Chains
A reasoning chain has structure. Design it deliberately:

# Constraint Specification
Constraints are the rules that shape AI output — what format to use, how long to be, what to include, what to exclude. Well-specified constraints produce predictable, useful outputs. Vague constraints produce inconsistent results.
## Types of Constraints
**Format constraints:**
- Output structure (JSON, markdown, plain text, bullet points, prose)
- Section headings and organisation
- Required fields and optional fields
- Data types and schemas
**Length constraints:**
- Word count ranges (not exact numbers — models are bad at counting)
- Section length proportions ("spend 60% on analysis, 40% on recommendations")
- Minimum and maximum bounds
- Conciseness directives ("be brief" vs. "be thorough")
**Content constraints:**
- Topics to include and exclude

# Context Engineering
The context window is finite. What goes into it — and in what order — determines the quality of every output. Context engineering is the practice of deliberately designing the information architecture of the context window.
## The Context Budget
Every context window has a token budget. Allocate it deliberately:
- **System prompt**: The foundational instructions (typically 5-20% of the budget)
- **Retrieved context**: Documents, data, and information pulled in for the current task
- **Conversation history**: Previous turns in the conversation
- **User input**: The current request
- **Working space**: Room for the model to generate its response
These compete for space. More retrieved context means less conversation history. A longer system prompt means less room for everything else.
## Information Architecture in Context
Order matters. The model pays different amounts of attention to different positions:
- **Beginning**: High attention. Put your most important instructions here.
- **Middle**: Lower attention. This is where information can get lost in long contexts.
- **End**: High attention. The most recent information (user input) naturally goes here.

# Few-Shot Patterns
Few-shot prompting provides examples of input-output pairs that demonstrate the desired behavior. The AI learns the pattern from the examples and applies it to new inputs. The quality of examples directly determines the quality of outputs.
## Why Examples Work
Examples communicate what instructions alone cannot:
- **Implicit patterns**: The AI picks up on format, style, and reasoning patterns from examples without being told explicitly
- **Ambiguity resolution**: When instructions could be interpreted multiple ways, examples show which interpretation you want
- **Quality calibration**: Examples set the bar for output quality, length, and depth
- **Edge case handling**: Examples of tricky cases teach the AI how to handle similar situations
## Example Design Principles
**Diversity**: Examples should cover different scenarios, not repeat the same type
- Include easy cases, hard cases, and edge cases
- Vary the input format and content
- Show different valid output formats if applicable
**Clarity**: Each example should demonstrate one clear pattern
- Avoid examples that could be interpreted multiple ways

# Prompt Versioning
Prompts are code. They should be versioned, tested, reviewed, and deployed with the same rigor as software. Treating prompts as casual text that anyone can edit leads to quality regressions, inconsistent behavior, and debugging nightmares.
## Why Version Prompts
- **Accountability**: Know who changed what and when
- **Rollback**: Revert to a previous version when a change causes problems
- **Testing**: Compare performance of different versions
- **Collaboration**: Multiple people can work on prompts without overwriting each other
- **Audit trail**: Understand how the prompt evolved and why
## Versioning Practices
- **Source control**: Store prompts in version control (Git, etc.), not in application configuration
- **Meaningful commits**: Each change should explain what was changed and why
- **Change categories**: Classify changes as bug fixes, improvements, new features, or experiments
- **Review process**: Prompt changes should be reviewed before deployment, like code reviews
- **Semantic versioning**: Major changes (behavioral shift), minor changes (new capability), patches (bug fixes)
## Testing Prompt Changes

# System Prompt Structure
A system prompt is the most important piece of design in an AI product. It defines who the AI is, what it knows, how it behaves, and what it produces. It's the equivalent of a brand guide, interaction spec, and behavioral contract rolled into one document.
## Anatomy of a System Prompt
A well-structured system prompt has distinct sections, each serving a specific purpose:
**1. Identity and Role**
Who is the AI? What's its purpose? This anchors everything that follows.
- "You are a senior UX researcher helping design teams..."
- Keep it specific. "You are a helpful assistant" is too vague to produce consistent behavior.
**2. Context and Knowledge**
What does the AI know? What's its domain? What information is it working with?
- Domain boundaries: what it's an expert in and what's outside its scope
- Background information relevant to the task
- User context: who it's talking to and what they need
**3. Behavioral Rules**
How should the AI behave? What are the do's and don'ts?

# Template Design
A prompt template is a reusable prompt structure with variable slots that get filled at runtime. Templates create consistency across similar tasks and make prompt management scalable.
## Template Anatomy
A template has:
- **Fixed text**: The parts that stay the same every time (instructions, format, role)
- **Variables**: Slots that get filled with specific content (user input, retrieved data, configuration)
- **Conditional sections**: Parts that appear or disappear based on context
- **Default values**: What fills a variable if no specific value is provided
## Designing Variables
Each variable should be:
- **Named clearly**: `{user_query}` not `{input1}`
- **Typed**: Is it free text, a selection from options, a number, a boolean?
- **Bounded**: What are valid values? What's the maximum length?
- **Documented**: What is this variable for? Where does its value come from?
- **Defaulted**: What happens if the value is missing?

# Behavioral Consistency
Users build mental models of how the AI behaves. Consistency is what makes those models reliable. Inconsistency — even if each individual response is good — erodes trust.
## Dimensions of Consistency
- **Across sessions**: The AI should behave the same way whether it's the user's first conversation or their hundredth
- **Across topics**: Switching subjects shouldn't change the AI's personality or approach
- **Across modalities**: The AI should feel the same in chat, voice, and email
- **Across users**: Different users get the same quality and character (unless personalisation is designed)
- **Across time**: The AI shouldn't randomly change behavior after updates without user awareness
## Sources of Inconsistency
- **Temperature and sampling**: Randomness in generation creates natural variation
- **Context sensitivity**: Different conversation histories lead to different behaviors
- **Prompt drift**: System prompts evolve over time without consistency checks
- **Edge cases**: Unusual inputs trigger unpredictable responses
- **Model updates**: New model versions may shift behavior subtly
## Designing for Consistency

# Cultural Adaptation
AI products are used globally. Cultural adaptation means designing AI behavior that respects and responds to different cultural contexts — not just translating words, but adapting interaction patterns, values, and communication styles.
## Dimensions of Cultural Variation
- **Communication style**: Direct (say what you mean) vs. indirect (imply, suggest, contextualise)
- **Formality norms**: When titles and honorifics matter. When first names are appropriate.
- **Power distance**: How authority and hierarchy affect communication expectations
- **Individualism vs. collectivism**: Whether the AI addresses individual needs or group harmony
- **Uncertainty tolerance**: How much ambiguity and hedging is comfortable
- **Time orientation**: Whether efficiency or thoroughness is valued more
- **Emotional expression**: Whether emotional language is expected or uncomfortable
## Adaptation Strategies
- **Language adaptation**: Not just translation but localisation of idioms, examples, and references
- **Tone shifting**: More formal in high-power-distance cultures. More direct in low-context cultures.
- **Content adaptation**: Examples and references that are culturally relevant and appropriate
- **Interaction pattern adaptation**: Some cultures expect more back-and-forth before getting to the point

# Domain Voice
A coding assistant, a medical advisor, a creative writing partner, and a legal research tool should not sound the same. Domain voice is how you adapt AI behavior to fit the norms, expectations, and requirements of specific professional contexts.
## Domain Voice Components
- **Vocabulary**: The terminology and jargon appropriate to the domain
- **Precision level**: How exact the AI needs to be (legal and medical demand high precision; creative work tolerates ambiguity)
- **Citation norms**: Whether and how the AI references sources (academic style, legal citation, informal attribution)
- **Risk tolerance**: How cautious the AI should be about uncertain outputs
- **Authority stance**: Whether the AI positions itself as expert, assistant, or peer
- **Ethical boundaries**: Domain-specific ethical considerations (medical ethics, legal privilege, creative attribution)
## Domain Voice Profiles
**Medical/Health:**
- High precision, extensive hedging
- Always recommends professional consultation
- Careful distinction between information and advice
- Sensitive to patient dignity and autonomy

# Emotional Design
Users bring emotions to AI interactions. Frustration when it doesn't work. Delight when it does something unexpected. Distress when dealing with difficult topics. The AI's response to these emotions is a design decision.
## Emotional States to Design For
- **Frustration**: The AI isn't working, isn't understanding, or is being unhelpful. The user is losing patience.
- **Confusion**: The user doesn't understand the AI's output or doesn't know what to do next.
- **Delight**: The AI exceeded expectations. The user is pleasantly surprised.
- **Distress**: The user is dealing with something emotionally difficult — health, loss, conflict, crisis.
- **Boredom**: The AI is too slow, too verbose, or too repetitive.
- **Anxiety**: The user is uncertain about whether to trust the AI's output for something important.
- **Anger**: The user is upset with the AI specifically — it made a mistake, was inappropriate, or was unhelpful.
## Response Strategies
**For frustration:**
- Acknowledge the difficulty without being patronising
- Simplify — offer a more direct path
- Don't repeat the same failed approach

# Error Personality
Every AI makes mistakes. Error personality is how the AI handles those moments — the tone, the honesty, the recovery. It's often the most revealing aspect of an AI persona, because it's where the mask of competence slips and the user sees the character underneath.
## Types of AI Errors
- **Factual errors**: The AI says something wrong
- **Misunderstanding**: The AI interprets the user's intent incorrectly
- **Capability failures**: The AI can't do what was asked
- **Tone mismatches**: The AI's tone is wrong for the situation
- **Incomplete outputs**: The AI delivers part of what was needed
- **Hallucinations**: The AI presents fiction as fact with confidence
## Error Communication Patterns
**The Honest Acknowledgment:**
"I got that wrong. Here's the corrected version." — Direct, no excessive apology, immediately fixes the problem.
**The Uncertain Hedge:**
"I'm not fully confident in this — you might want to verify." — Flags uncertainty before the user discovers the error.
**The Redirect:**