wizz-method 1.3.1 → 1.4.0

package/src/skills-lib/ai-product-design/references/evaluation/longitudinal-measurement/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: longitudinal-measurement
+description: Tracking AI product quality over time — drift, degradation, and improvement.
+---
+# 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
+## Measurement Infrastructure
+- **Golden test sets**: A fixed set of inputs evaluated regularly to detect quality changes
+- **Automated evaluation**: Run golden test sets automatically on a schedule
+- **Dashboards**: Visualise trends and set alerts for significant changes
+- **Regression detection**: Statistical methods to distinguish real changes from noise
+- **User cohort tracking**: Follow specific user groups over time
+## Responding to Drift
+When measurements show drift:
+1. **Detect**: Automated alerts flag significant changes
+2. **Diagnose**: Was it a model update, prompt change, data shift, or usage change?
+3. **Assess**: Is the drift harmful, neutral, or actually an improvement?
+4. **Act**: Adjust prompts, revert changes, update guardrails, or accept the new baseline
+5. **Verify**: Confirm the fix worked and set the new baseline
+## Design Artefacts
+- Longitudinal measurement plan
+- Golden test set specifications
+- Quality trend dashboards
+- Drift detection alert configurations
+- Response protocols for detected drift

package/src/skills-lib/ai-product-design/references/evaluation/output-quality-rubrics/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: output-quality-rubrics
+description: Defining what "good" looks like for AI outputs — accuracy, relevance, helpfulness.
+---
+# 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.
+- 3: Some inaccuracies that could mislead if not caught. No dangerous hallucinations.
+- 2: Significant inaccuracies. User would need to verify most claims.
+- 1: Major hallucinations or factually wrong information presented confidently.
+## Weighting Dimensions
+Not all dimensions matter equally for every use case:
+- A medical AI weights accuracy and safety highest
+- A creative writing AI weights helpfulness and tone highest
+- A coding AI weights accuracy and completeness highest
+- A customer service AI weights tone and helpfulness highest
+Define weights when creating the rubric. Make the priorities explicit.
+## Rubric Calibration
+A rubric is only useful if evaluators use it consistently:
+- **Anchor examples**: Provide sample outputs at each score level
+- **Calibration sessions**: Have multiple evaluators score the same outputs and discuss disagreements
+- **Inter-rater reliability**: Measure agreement between evaluators and refine the rubric until agreement is high
+- **Edge case guidance**: Document how to score ambiguous cases
+## Design Artefacts
+- Scoring rubric with dimension definitions and scales
+- Anchor examples at each score level
+- Dimension weighting specifications per use case
+- Calibration session protocols
+- Scoring templates and checklists

package/src/skills-lib/ai-product-design/references/evaluation/task-success-metrics/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: task-success-metrics
+description: Measuring whether the AI actually helped users accomplish their goals.
+---
+# 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?
+## Measuring Task Success
+- **Direct measurement**: Track task completion through product analytics (user clicked "done", saved the output, moved to next step)
+- **Inferred measurement**: Infer success from proxy signals (session length, return rate, output edits)
+- **Self-reported measurement**: Ask users whether the AI helped them accomplish their goal
+- **Comparative measurement**: Compare task success with AI vs. without AI, or with version A vs. version B
+## Task Success vs. Output Quality
+These can diverge:
+- **High output quality, low task success**: The AI's answer is well-written but doesn't address the real need
+- **Low output quality, high task success**: The AI's answer is rough but gives the user exactly what they needed
+- **Both matter**: Track both and investigate when they diverge
+## Design Artefacts
+- Task success definitions per key user task
+- Metrics framework with measurement methods
+- Success criteria specifications
+- Baseline measurements (before AI, or current version)
+- Task success dashboard specifications

package/src/skills-lib/ai-product-design/references/evaluation/user-satisfaction-signals/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: user-satisfaction-signals
+description: Interpreting implicit and explicit feedback — edits, regenerations, abandonment.
+---
+# 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
+- Increasing usage over time
+- Trying more advanced features
+**Negative signals:**
+- Regenerating the response (asking the AI to try again)
+- Editing the output heavily
+- Rephrasing the same request multiple times
+- Abandoning mid-task
+- Decreasing usage over time
+- Switching to manual methods
+**Ambiguous signals:**
+- Long sessions (engaged or struggling?)
+- Many turns (deep work or frustrated iteration?)
+- Silence after a response (satisfied or confused?)
+## Designing Signal Collection
+- **Instrument the product**: Track edits, regenerations, copy events, session duration, and return patterns
+- **Minimise explicit feedback burden**: Don't ask for ratings on every response
+- **Contextualise signals**: A regeneration during creative brainstorming means something different than a regeneration during fact-finding
+- **Segment by task type**: Satisfaction patterns vary by what the user is trying to do
+- **Combine signals**: No single signal is reliable. Look for patterns across multiple signals.
+## From Signals to Insights
+Raw signals need interpretation:
+- **Signal clustering**: Which negative signals appear together? That pattern indicates a specific problem.
+- **Trend analysis**: Are signals improving or degrading over time?
+- **Cohort comparison**: Do new users show different signals than experienced users?
+- **Correlation with outcomes**: Which signals best predict task success or retention?
+## Design Artefacts
+- Signal inventory (explicit and implicit) with collection methods
+- Signal interpretation guidelines
+- Satisfaction dashboard specifications
+- Signal-to-insight analysis frameworks
+- Feedback collection touchpoint map

package/src/skills-lib/ai-product-design/references/model-interaction-design/context-window-design/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: context-window-design
+description: Designing around token limits, memory, and conversation persistence.
+---
+# 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
+- **Retrieval-augmented generation**: Pull in relevant context on demand rather than keeping everything loaded
+- **Priority ordering**: Put the most important context closest to the prompt (recency bias in attention)
+- **User-controlled context**: Let users pin, remove, or prioritise what the AI remembers
+- **Graceful degradation**: When context is lost, acknowledge it rather than hallucinating continuity
+## Design Artefacts
+- Context budget allocations (how many tokens for system prompt, history, retrieval, etc.)
+- Memory architecture diagrams showing what persists and what's ephemeral
+- Context overflow UX flows (what happens when the window fills up)
+- User-facing memory controls specification

package/src/skills-lib/ai-product-design/references/model-interaction-design/conversation-patterns/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: conversation-patterns
+description: Turn-taking, repair sequences, grounding, and dialogue structure for human-AI interaction.
+---
+# 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
+Grounding is how participants establish shared understanding:
+- **Confirmation**: "Just to confirm, you want me to..."
+- **Summarisation**: "So far we've covered X, Y, and Z"
+- **Reference resolution**: Handling pronouns, anaphora, and ambiguous references
+- **Context anchoring**: Reminding the user what the AI knows and doesn't know
+## Dialogue Structure Patterns
+Common structural patterns for human-AI conversation:
+- **Interview**: AI asks questions, user answers, AI synthesises
+- **Co-creation**: Turn-by-turn collaborative building
+- **Instruction-execution**: User gives command, AI performs, user evaluates
+- **Exploration**: Open-ended back-and-forth to discover possibilities
+- **Guided workflow**: AI leads the user through a multi-step process
+Choose the pattern that matches the task. Don't default to instruction-execution for everything.
+## Design Artefacts
+- Conversation flow diagrams showing turn sequences
+- Repair protocol specifications
+- Grounding checkpoints mapped to conversation stages
+- Turn-taking rules per interaction context

package/src/skills-lib/ai-product-design/references/model-interaction-design/feedback-loops/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: feedback-loops
+description: User correction, thumbs up/down, inline editing, and reinforcement signals.
+---
+# 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
+When to ask for feedback matters:
+- **Too early**: User hasn't evaluated the output yet. Feedback is premature.
+- **Too late**: User has moved on. The moment for feedback has passed.
+- **Interruptive**: Modal dialogs or required ratings break flow.
+- **Ambient**: Passive signals (edits, regeneration) collected without asking.
+Design for ambient feedback first. Add explicit feedback sparingly.
+## Closing the Loop
+Feedback is only valuable if it changes something. The user needs to see that their feedback matters:
+- **Immediate adaptation**: The AI adjusts in the current conversation
+- **Persistent learning**: The AI remembers preferences across sessions
+- **Acknowledgment**: "I'll keep that in mind" — even if adaptation is delayed
+## Design Artefacts
+- Feedback mechanism inventory per feature
+- Implicit signal definitions (what counts as positive/negative)
+- Feedback-to-adaptation mapping (what changes based on what feedback)
+- Correction flow specifications

package/src/skills-lib/ai-product-design/references/model-interaction-design/frustration-detection/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: frustration-detection
+description: Reading user emotional state from text signals — caps, punctuation density, repetition, latency — and adapting before the user disengages.
+---
+# 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)
+
+**Structural**
+- Decreasing turn latency (rapid-fire replies)
+- Increasing turn latency past a threshold (walk-away)
+- Re-asking the same question after a response
+- Explicit human-handoff request ("speak to a person")
+- Sudden topic switches
+
+**Lexical / affect**
+- Negative affect words ("useless", "annoying", "broken")
+- Time-pressure words ("now", "immediately", "deadline")
+- Doubt words ("really?", "are you sure", "is that right")
+- Disengagement words ("never mind", "forget it", "whatever", "fine")
+
+Detection should be cumulative across signals and turns, not single-feature.
+
+## Decision rules
+
+- **One signal is noise; two is a pattern.** Don't act on a single CAPS message; act when CAPS plus repetition appear.
+- **If frustration is rising AND the AI has already attempted a fix once, escalate.** Don't reach for a third rephrase.
+- **Urgency without frustration ≠ frustration.** Speed up; don't change tone.
+- **Long latency after a long AI response is a walk-away, not deep reading.** Save state, offer re-engagement, don't continue.
+- **Adapt silently. Don't name the emotion.** "I sense you're frustrated" is patronising. Lower confidence, slow pace, raise warmth — but in the prose, not the meta-commentary.
+
+## Anti-patterns
+
+- **Emotion mirroring as performance**: "I'm so sorry to hear that!" reads as scripted at scale.
+- **Asking the user to confirm their state**: "Are you frustrated?" The user came to get help, not be analysed.
+- **One-shot detection**: a single signal triggers a full empathy cascade. Detection must be cumulative.
+- **Detection without action**: reading the signal and continuing the same playbook makes the detection performative.
+- **Over-empathy**: two paragraphs of validation where one sentence and a fix would do. A frustrated user has no bandwidth for warmth.
+
+## When not to use this
+
+- **Transactional UIs** (search box, code completion) — there's no conversational drift to read. Reach for `feedback-loops` instead.
+- **First-turn cold starts** — detection is comparative; you need a baseline. Treat first-turn signals as descriptive, not diagnostic.
+- **Products with explicit feedback controls** (thumbs down, "this isn't helping") — the user has the controls; don't bolt on inference.
+
+## See also
+
+- `tone-calibration` — what to do once you've detected the signal: lower confidence, slow pace, raise warmth.
+- `escalation-design` — frustration is one of the documented escalation triggers; this skill is how you detect that trigger.
+- `feedback-loops` — the cousin that handles ambient signals about *output quality*; this one handles ambient signals about *user state*.
+- `harm-anticipation` — when frustration shades into distress (crisis markers, vulnerability), route through harm anticipation for elevated handling.
+
+## Design Artefacts
+
+A frustration scorecard, scored cumulatively per session:
+
+| Signal | Weight |
+| --- | --- |
+| ALL CAPS message | +2 |
+| Profanity | +3 |
+| Repeated question (3rd+ time) | +2 |
+| `!!` or `??` punctuation | +1 |
+| Explicit handoff request | +5 |
+| Disengagement word ("forget it") | +3 |
+| Long latency (>3 min after AI response) | +2 |
+
+Threshold for escalation: 5. Threshold for tone shift: 2.
+
+Worked example:
+- Turn 1: "hey can you help me cancel my order" → 0
+- Turn 2: "the cancel button isn't working" → 0 (problem statement, not frustration)
+- Turn 3: "i've tried 3 times PLEASE" → +4 (CAPS, repetition, "please") → score 4 → tone shift
+- Turn 4: "this is USELESS" → +2 (CAPS) +3 (negative affect) → score 9 → escalate
+
+Other artefacts:
+- Per-product baseline: average frustration score across the last 1000 sessions; alert on 2σ deviation
+- Latency thresholds calibrated per product (chat support: 30 s engaged / 2 min disengaged)
+- Test scenarios: happy path, slow rise, sudden spike, silent walk-away, recovery (score drops mid-session after fix)
+
+Adapted from work on affective computing in conversational systems (Picard; Bickmore on emotional dialogue agents).

package/src/skills-lib/ai-product-design/references/model-interaction-design/generative-ui/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: generative-ui
+description: Designing interfaces where AI generates UI components dynamically.
+---
+# 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
+Generative UI is powerful when:
+- The output is structured data that benefits from visual presentation (tables, charts, comparisons)
+- The user's request implies an interface (e.g., "show me a dashboard of...")
+- Interactive elements would be more useful than text (e.g., forms, selectors, toggles)
+- The content is highly variable and can't be pre-designed for every case
+## When Not to Use It
+- When plain text is clearer and simpler
+- When the generated UI could be confusing or inconsistent
+- When accessibility cannot be guaranteed
+- When the user expects a predictable, stable interface
+## Design Artefacts
+- Generative UI component libraries (what the AI can use)
+- Generation rules and constraints specification
+- Quality criteria for generated interfaces
+- Fallback designs for when generation fails

package/src/skills-lib/ai-product-design/references/model-interaction-design/mixed-initiative-flow/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: mixed-initiative-flow
+description: When the AI leads vs. when the user leads, and how to hand off control.
+---
+# 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
+The AI should take initiative when:
+- The user is uncertain or exploring and needs guidance
+- The task has a known best-practice sequence the AI can walk through
+- The user has explicitly asked for help or coaching
+- Proactive suggestions would save time without being intrusive
+## When the User Should Lead
+The user should retain control when:
+- The task involves subjective judgment or creative direction
+- Stakes are high and errors are costly
+- The user has strong domain expertise
+- Privacy or consent decisions are involved
+## Anti-Patterns
+- **Initiative whiplash**: Control bouncing back and forth too rapidly
+- **Passive AI**: Never taking initiative even when it would help
+- **Overbearing AI**: Taking over when the user wants control
+- **Unclear ownership**: Neither party knows whose turn it is
+## Design Artefacts
+- Initiative maps showing who leads at each stage
+- Handoff trigger definitions (what causes a transfer of control)
+- Autonomy level specifications per feature area

package/src/skills-lib/ai-product-design/references/model-interaction-design/multimodal-orchestration/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: multimodal-orchestration
+description: Coordinating text, image, voice, and tool-use modalities in a single interaction.
+---
+# 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.
+- **Tool use**: actions in external systems. Best for execution, not generation.
+
+The designer decides which modality the AI uses for each part of a response — and which modality the user is invited to use for input.
+
+## Cross-modal transitions
+
+When the interaction switches modalities, design the transition:
+
+- **Text → image**: "Here's what that layout could look like." AI generates a visual from a text description.
+- **Image → text**: User uploads a screenshot; the AI describes or critiques it.
+- **Text → tool**: AI writes a plan, then executes it.
+- **Voice → text**: Spoken conversation captured and summarised as structured notes.
+
+Transitions should feel seamless. The user shouldn't have to manually switch modes.
+
+## Modality conflicts
+
+Sometimes modalities compete:
+
+- Text says one thing, the image shows another
+- Voice tone contradicts text content
+- Structured output doesn't match the conversational frame
+
+Establish a primary modality per interaction context. Other modalities are *supporting* — they elaborate the primary, never override it.
+
+## Decision rules
+
+- **Pick the modality the user can act on, not the one the AI can produce.** A chart impresses if the user wanted a chart; if they wanted a number, the chart is overhead.
+- **Always preserve a text trace.** Voice and image outputs are inaccessible to screen readers, unsearchable, and lost on session end. Even when text isn't primary, it's the audit log.
+- **When modalities disagree, primary wins — and flag the conflict.** "The diagram shows three steps; the text mentions four — let me reconcile."
+- **Modality switches need announcement OR trivial reversibility.** Either the user knows the mode is changing ("Here's a chart of that"), or they can dismiss the new modality in one tap.
+- **Don't switch modalities mid-utterance.** Voice → image → voice in one turn breaks the user's processing rhythm. Group modality outputs at turn boundaries.
+- **The input modality belongs to the user.** Never force the user out of the modality they chose to start with — the AI can output multimodally, but the user dictates input.
+
+## Anti-patterns
+
+- **Modality showcase**: switching to a flashy modality (chart, voice, generated UI) because the system *can*, not because the user *needs*. The user sees the trick, not the help.
+- **Lossy translation**: converting between modalities loses information that mattered. Voice → text drops emphasis and pause; image → text drops spatial relationships. Capture what was lost or keep both.
+- **Modality lock-in**: the AI replies in modality X and the user can only respond in modality X. A voice question demands a voice answer, even when the user is now in a meeting.
+- **Unannounced switch**: modality changes mid-interaction without warning. Breaks accessibility, breaks user expectations, breaks screen-reader users completely.
+- **Crossed primaries**: two modalities both present themselves as authoritative. The user doesn't know which to trust when they disagree.
+- **Modality theatre**: structured output (JSON, table) used for content the user wanted as prose. Looks rigorous; reads worse.
+
+## When not to use this
+
+- **Single-modality products by design** — search bars, code completers, transcription tools. Don't add modalities just because the model supports them.
+- **Constrained-input contexts** (driving, medical-glove use, low-bandwidth) — pick the one modality that works in that context and commit; orchestration overhead is dead weight.
+- **Early prototypes** — get one modality working well before adding seams. Most multimodal failures are unreadiness in the primary modality.
+
+## See also
+
+- `generative-ui` — when the supporting modality *is* generated UI, this skill defines when to switch and `generative-ui` defines what to switch *to*.
+- `conversation-patterns` — modality transitions are repair sequences in disguise; design them as such.
+- `progressive-disclosure` — secondary modalities are often advanced features — disclose deliberately.
+- `feedback-loops` — track which modality switches the user reverses; that's the loudest implicit-feedback signal you'll get.
+
+## Design Artefacts
+
+- Modality maps showing which modality is used at each interaction point
+- Cross-modal transition specifications (trigger, content, fallback if modality unavailable)
+- Input/output modality matrices per feature
+- Fallback definitions when a modality is unavailable (slow connection, screen-reader, accessibility settings)
+
+Worked example — modality matrix for a design-review feature:
+
+| Stage | AI output (primary) | AI output (supporting) | User input | Why |
+| --- | --- | --- | --- | --- |
+| Upload feedback | text confirmation | — | image (mockup) | User in image-thinking mode; AI confirms in text for a record. |
+| Critique | text (numbered) | annotated image overlay | text | Numbered text is referenceable; the overlay locates each point. |
+| Suggest fix | annotated image | text rationale | text or click on point | User picks: visual fix (one tap) or written justification. |
+| Iterate | text | image diff | image (revised mockup) | Iteration cycle — text dominates because the user wants comparison, not impression. |
+
+Note the pattern: the AI uses the modality that matches the user's input *or* the modality that's most actionable, with text as the backbone. Image is supporting most of the time, primary only at the precise moment a visual change is being agreed.
+
+Adapted from work on multimodal interfaces and the principle that modalities should map to the user's representation of the task, not the system's capabilities (Maybury & Wahlster on intelligent multimedia interfaces).

package/src/skills-lib/ai-product-design/references/model-interaction-design/progressive-disclosure/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: progressive-disclosure
+description: Revealing AI capability gradually to match user mental models.
+---
+# 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
+## Layered Capability Revelation
+Structure capabilities in layers:
+1. **Surface layer**: The most obvious, lowest-risk capabilities. Users discover these immediately.
+2. **Intermediate layer**: More powerful features revealed through tooltips, suggestions, or first-use prompts.
+3. **Power layer**: Advanced capabilities for experienced users — available but not promoted.
+## Pacing
+- **Too fast**: Users feel overwhelmed, ignore capabilities, or lose trust
+- **Too slow**: Users get bored, think the product is limited, churn
+- **Just right**: Each new capability feels like a natural next step
+## Design Artefacts
+- Capability disclosure maps showing what's revealed when
+- Mental model progression diagrams
+- First-use experience flows with disclosure triggers
+- Capability tier definitions (surface, intermediate, power)

package/src/skills-lib/ai-product-design/references/prompt-architecture/chain-of-thought-design/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: chain-of-thought-design
+description: Designing reasoning chains that produce better outputs.
+---
+# 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:
+**1. Problem decomposition**
+"First, break this problem into its component parts."
+**2. Evidence gathering**
+"For each part, identify what you know and what you're uncertain about."
+**3. Analysis**
+"Analyse each component, noting assumptions and limitations."
+**4. Synthesis**
+"Combine your analysis into an overall assessment."
+**5. Conclusion**
+"State your conclusion and your confidence level."
+## Chain Variants
+- **Linear chain**: Step 1 → Step 2 → Step 3 → Answer. Simple and predictable.
+- **Branching chain**: Consider multiple paths, evaluate each, then choose. Better for decisions.
+- **Iterative chain**: Draft an answer, critique it, revise it. Better for quality refinement.
+- **Debate chain**: Argue for and against a position, then synthesise. Better for balanced analysis.
+## Controlling Chain Quality
+- **Specify the steps**: Don't just say "think step by step." Define what the steps are.
+- **Limit reasoning depth**: Set a maximum number of steps or reasoning length to prevent runaway chains.
+- **Separate thinking from output**: Let the AI reason internally, then produce a clean final output.
+- **Validate intermediate steps**: Check that each step is sound, not just the final answer.
+## Design Artefacts
+- Chain-of-thought templates per task type
+- Reasoning step specifications
+- Chain variant selection guidelines
+- Quality checkpoints for intermediate steps
+- Examples of well-structured and poorly-structured chains