wizz-method 1.3.2 → 1.4.0

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

package/src/skills-lib/ai-product-design/references/prompt-architecture/constraint-specification/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: constraint-specification
+description: Defining output format, length, tone, and content boundaries within prompts.
+---
+# 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
+- Required information elements
+- Prohibited content
+- Source restrictions (only use provided context, don't use external knowledge)
+**Tone constraints:**
+- Formality level
+- Emotional register
+- Audience-appropriate language
+- Voice and style guidelines
+**Quality constraints:**
+- Accuracy requirements ("cite sources", "flag uncertainty")
+- Completeness requirements ("address all aspects of the question")
+- Originality requirements ("don't repeat the question back")
+- Actionability requirements ("every recommendation must be implementable")
+## Writing Effective Constraints
+- **Be specific**: "Keep responses under 200 words" beats "be concise"
+- **Prioritise**: When constraints conflict, state which wins. "Accuracy over brevity."
+- **Provide examples**: Show what a constrained output looks like
+- **Test boundaries**: What happens at the edge of each constraint?
+- **Separate hard and soft constraints**: Hard constraints must always be met. Soft constraints are preferences.
+## Constraint Interactions
+Constraints interact and can conflict:
+- "Be thorough" vs. "Keep it under 100 words"
+- "Be creative" vs. "Follow this exact format"
+- "Be helpful" vs. "Don't give medical advice"
+Resolve conflicts explicitly in the prompt. Don't make the model guess which constraint takes priority.
+## Design Artefacts
+- Constraint specification documents per output type
+- Constraint priority hierarchies
+- Constraint test cases (inputs designed to stress each constraint)
+- Constraint violation examples (what bad looks like)
+- Constraint evolution logs (how constraints changed and why)

package/src/skills-lib/ai-product-design/references/prompt-architecture/context-engineering/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: context-engineering
+description: Designing what information goes into the context window and in what order.
+---
+# 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.
+- **Adjacent to the task**: Information placed right before the user's question gets more attention than information earlier in the context.
+## Context Selection
+Not everything should go into the context. Design selection criteria:
+- **Relevance**: Does this information help answer the current question?
+- **Recency**: Is this the most up-to-date information available?
+- **Specificity**: Is this specific enough to be useful, or is it too generic?
+- **Redundancy**: Is this information already covered elsewhere in the context?
+- **Authority**: Is this from a reliable source?
+## Context Strategies
+- **Retrieval-augmented generation (RAG)**: Pull relevant documents into the context dynamically
+- **Summarisation**: Compress older context into summaries to free up space
+- **Prioritised history**: Keep recent and important conversation turns, drop less important ones
+- **Structured context**: Organise information with clear headers and sections so the model can navigate it
+- **Context caching**: Pre-compute and cache frequently used context blocks
+## Context Quality Signals
+How to tell if your context engineering is working:
+- **Output relevance**: Do outputs address the actual question using the provided context?
+- **Hallucination rate**: Is the model making things up because the context is insufficient?
+- **Context utilisation**: Is the model actually using the provided context, or ignoring it?
+- **Consistency**: Are outputs consistent when the same context is provided?
+## Design Artefacts
+- Context budget allocation documents
+- Information architecture diagrams for the context window
+- Context selection criteria per feature
+- Retrieval strategy specifications
+- Context quality monitoring metrics

package/src/skills-lib/ai-product-design/references/prompt-architecture/few-shot-patterns/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: few-shot-patterns
+description: Crafting examples that steer AI behavior effectively.
+---
+# 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
+- Make the mapping from input to output obvious
+- Remove irrelevant variation between examples
+**Quality**: Examples set the ceiling for output quality
+- Every example should be one you'd be happy to ship
+- If the example has a flaw, the AI will replicate that flaw
+- Invest time in crafting examples — they're worth more than instructions
+**Ordering**: The position of examples matters
+- Put the most representative example first
+- Put edge cases after common cases
+- End with an example closest to the expected input type
+## How Many Examples
+- **Zero-shot**: No examples. Relies entirely on instructions. Good for simple, well-understood tasks.
+- **One-shot**: Single example. Enough when the pattern is straightforward.
+- **Few-shot (3-5)**: Multiple examples. Best for complex patterns or nuanced quality requirements.
+- **Many-shot (5+)**: Diminishing returns but useful for highly variable tasks or when consistency is critical.
+Balance example count against context window cost. More examples means less room for other context.
+## Anti-Patterns
+- **Identical examples**: All examples are basically the same, teaching nothing about variation
+- **Perfect-only examples**: No examples of how to handle imperfect inputs or edge cases
+- **Contradictory examples**: Examples that demonstrate inconsistent patterns
+- **Low-quality examples**: Sloppy examples produce sloppy outputs
+- **Outdated examples**: Examples that no longer reflect current requirements
+## Design Artefacts
+- Example libraries per task type
+- Example quality rubrics
+- Example selection guidelines
+- Example maintenance and update schedules
+- Example effectiveness testing results