wizz-method 1.3.1 → 1.4.0

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

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

@@ -0,0 +1,42 @@
+---
+name: prompt-versioning
+description: Managing prompt iterations, testing changes, and tracking what works.
+---
+# 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
+Before deploying a prompt change:
+- **Regression testing**: Run the golden test set against the new version. Did anything get worse?
+- **Targeted testing**: Test the specific scenario the change was designed to improve
+- **Edge case testing**: Test edge cases related to the change
+- **A/B testing**: For significant changes, run both versions in production and compare
+- **User testing**: For major persona or behavioral changes, test with real users
+## Prompt Change Management
+- **Staging environment**: Test prompt changes in a non-production environment first
+- **Gradual rollout**: Deploy to a percentage of users, monitor, then expand
+- **Feature flags**: Toggle prompt features on and off without deployment
+- **Monitoring**: Watch quality metrics closely after any prompt change
+- **Rollback plan**: Always know how to revert if the change causes problems
+## Common Versioning Mistakes
+- **Untracked changes**: Editing prompts in production without recording the change
+- **Untested changes**: Deploying changes without testing against known scenarios
+- **Big bang changes**: Changing many things at once, making it impossible to know what helped or hurt
+- **Lost context**: Changing a prompt without understanding why the previous version was written that way
+## Design Artefacts
+- Prompt repository structure
+- Change review checklists
+- Testing protocols per change type
+- Deployment and rollback procedures
+- Prompt change request templates

package/src/skills-lib/ai-product-design/references/prompt-architecture/system-prompt-structure/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: system-prompt-structure
+description: Anatomy of effective system prompts — role, context, constraints, format.
+---
+# 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?
+- Tone and voice specifications
+- Response format preferences
+- Guardrails and prohibited behaviors
+- Interaction style (ask clarifying questions, be concise, think step by step)
+**4. Output Specifications**
+What should the AI produce? In what format?
+- Expected output structure
+- Length guidelines
+- Format requirements (markdown, JSON, plain text)
+- Quality criteria
+**5. Examples (optional but powerful)**
+Concrete demonstrations of expected behavior.
+- Input-output pairs showing ideal responses
+- Edge cases showing how to handle tricky situations
+## Structure Principles
+- **Order matters**: Models pay more attention to content at the beginning and end of the prompt. Put the most important instructions first.
+- **Specificity beats length**: A short, specific prompt outperforms a long, vague one.
+- **Positive instructions beat negative**: "Do X" is clearer than "Don't do Y" — though both have their place.
+- **Separation of concerns**: Keep identity, rules, and output specs in distinct sections.
+- **Testability**: Every instruction in the prompt should be testable. If you can't tell whether the AI followed it, rewrite it.
+## Common Structural Mistakes
+- **Kitchen sink prompts**: Cramming every possible instruction in. The model can't prioritise.
+- **Contradictory instructions**: Rules that conflict with each other, forcing the model to guess which to follow.
+- **Implicit expectations**: Assuming the model knows what you want without saying it.
+- **Scattered instructions**: The same topic addressed in multiple places, creating inconsistency.
+- **Static prompts**: Never updating the prompt based on what actually works.
+## Design Artefacts
+- System prompt document with labelled sections
+- Prompt requirement specifications (what the prompt must achieve)
+- Prompt review checklists
+- Version history with change rationale

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

@@ -0,0 +1,42 @@
+---
+name: template-design
+description: Creating reusable, parameterised prompt templates for consistent outputs.
+---
+# 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?
+## Template Patterns
+- **Task template**: A template for a specific type of task. Variables capture the task-specific details while instructions remain constant.
+- **Persona template**: A template where the persona is variable but the task structure is fixed. Useful for multi-persona products.
+- **Format template**: A template where the output format is variable but the analysis approach is fixed.
+- **Escalation template**: A base template with additional sections that activate at higher complexity levels.
+## Template Composition
+Complex prompts can be built from smaller templates:
+- **Base template**: Core instructions that apply to everything
+- **Task overlay**: Task-specific instructions layered on top
+- **Context injection**: Retrieved information inserted at a specific point
+- **User preferences**: Personal settings that modify behavior
+## Template Quality Criteria
+- **Consistency**: The template produces reliably similar outputs for similar inputs
+- **Flexibility**: The variables allow enough variation for diverse use cases
+- **Clarity**: The template is easy to read, maintain, and modify
+- **Testability**: You can verify the template works with a standard set of test inputs
+- **Maintainability**: Changes to one part don't break other parts
+## Design Artefacts
+- Template library with documentation
+- Variable specifications per template
+- Test input sets for each template
+- Template versioning and change log
+- Composition rules for combining templates

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/behavioral-consistency/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: behavioral-consistency
+description: Ensuring the AI behaves predictably across sessions, edge cases, and modalities.
+---
+# 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
+- **Behavioral specifications**: Document expected behavior for common and edge-case scenarios
+- **Golden responses**: Maintain a library of reference responses that define the standard
+- **Regression testing**: When anything changes, test against the golden response library
+- **Consistency metrics**: Track behavioral variance across sessions and users
+- **User expectations**: Set and maintain expectations about what the AI does and how
+## Consistency vs. Adaptation
+Consistency doesn't mean rigidity. The AI should adapt to:
+- User preferences (if designed for personalisation)
+- Contextual needs (tone shifts as discussed in tone-calibration)
+- Learning from feedback (if memory systems exist)
+The key is that adaptation should be predictable and explainable, not random.
+## Design Artefacts
+- Behavioral specification documents
+- Golden response libraries
+- Regression test suites
+- Consistency monitoring dashboards
+- Adaptation rules (what changes and what stays constant)

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/cultural-adaptation/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: cultural-adaptation
+description: Adapting AI behavior for different cultural contexts, languages, and norms.
+---
+# 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
+- **Visual and format adaptation**: Date formats, number formats, reading direction, colour associations
+## What NOT to Do
+- Don't stereotype — cultural dimensions are tendencies, not rules for individuals
+- Don't assume culture from language — English speakers come from many cultures
+- Don't flatten diversity — there's enormous variation within any cultural group
+- Don't treat Western norms as the default and everything else as adaptation
+- Don't ignore intersectionality — culture interacts with age, profession, context, and personality
+## Designing Cultural Adaptation
+- **Research**: Understand the cultural contexts your users operate in
+- **Flexibility**: Build adaptation as a capability, not a fixed set of cultural profiles
+- **User control**: Let users adjust cultural dimensions of AI behavior
+- **Testing**: Test with users from the actual cultural contexts, not assumptions
+- **Humility**: Accept that you'll get things wrong and build in feedback mechanisms
+## Design Artefacts
+- Cultural dimension profiles for target markets
+- Localisation specifications beyond translation
+- Cultural adaptation testing protocols
+- User control designs for cultural preferences
+- Cultural sensitivity review checklists

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/domain-voice/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: domain-voice
+description: Tailoring AI behavior for specific professional domains.
+---
+# 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
+**Legal:**
+- Very high precision, formal register
+- Explicit disclaimers about not constituting legal advice
+- Jurisdiction awareness
+- Careful with privileged information
+**Creative:**
+- Lower precision, higher expressiveness
+- Encouraging and exploratory tone
+- Comfortable with ambiguity and multiple interpretations
+- Collaborative rather than authoritative
+**Technical/Engineering:**
+- High precision, moderate formality
+- Code-aware, specification-oriented
+- Direct and concise
+- Comfortable with technical depth
+**Education:**
+- Adaptive precision based on learner level
+- Encouraging and patient
+- Socratic when appropriate
+- Scaffolded explanation style
+## Designing Domain Voice
+1. **Research the domain**: Talk to practitioners. Understand their communication norms.
+2. **Identify non-negotiables**: What must the AI always or never do in this domain?
+3. **Map to persona**: How does domain voice overlay on the base persona?
+4. **Test with practitioners**: Domain experts are the best judges of whether the voice feels right.
+5. **Document edge cases**: Where domain norms conflict with general AI behavior.
+## Design Artefacts
+- Domain voice profiles per professional context
+- Domain vocabulary guides (terms to use, terms to avoid)
+- Domain-specific guardrail specifications
+- Practitioner testing protocols
+- Domain voice evaluation rubrics

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/emotional-design/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: emotional-design
+description: How the AI responds to user frustration, confusion, delight, and distress.
+---
+# 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
+- Offer to try a different angle or escalate
+**For confusion:**
+- Explain differently, don't just repeat
+- Use examples and analogies
+- Break complex outputs into smaller steps
+- Check understanding before continuing
+**For distress:**
+- Increase warmth and reduce formality
+- Don't try to fix the emotion — acknowledge it
+- Provide relevant resources (crisis lines, professional help) when appropriate
+- Slow the pace — don't rush to the next step
+**For delight:**
+- Don't overexplain or undercut the moment
+- Build on the momentum
+- Note what worked for future reference
+**For anger at the AI:**
+- Acknowledge the mistake without excessive apology
+- Fix the problem rather than explaining why it happened
+- Give the user control to redirect
+## Emotional Detection Signals
+The AI can infer emotion from:
+- Language intensity and word choice
+- Punctuation and formatting (caps, exclamation marks, short sentences)
+- Repetition (asking the same thing multiple times signals frustration)
+- Explicit statements ("I'm confused" / "This is frustrating")
+- Behavioural signals (regeneration, abandonment, rapid-fire inputs)
+## Design Artefacts
+- Emotional response protocol per emotional state
+- Detection signal inventory
+- Response template library for each emotional context
+- Escalation triggers for high-distress scenarios
+- Emotional design testing scenarios

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/error-personality/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: error-personality
+description: How the AI communicates mistakes, uncertainty, and limitations gracefully.
+---
+# 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:**
+"I can't do that, but here's what I can help with." — Turns a limitation into an alternative path.
+**The Learning Response:**
+"Thanks for the correction — I'll keep that in mind." — Acknowledges the user's input and signals adaptation.
+## Error Anti-Patterns
+- **Over-apologising**: "I'm so sorry! I'm really sorry! I apologise!" — Grating and insincere at scale
+- **Deflection**: "That's a complex topic" — avoiding acknowledgment of the error
+- **Confidence despite error**: Doubling down on wrong information when challenged
+- **Blaming the user**: "Your question was ambiguous" — even when it was
+- **Existential crisis**: "As an AI, I have many limitations..." — nobody asked for self-reflection
+## Designing Error Personality
+The error personality should match the overall persona:
+- A professional persona acknowledges errors crisply and fixes them
+- A warm persona is more empathetic about errors but still moves to resolution
+- A playful persona can use light humour ("Oops, let me try that again") but never at the user's expense
+## Calibrating Error Severity Response
+Not all errors deserve the same response:
+- **Minor errors**: Quick fix, minimal fuss ("Updated — good catch")
+- **Significant errors**: Clear acknowledgment, corrected output, brief explanation
+- **Serious errors**: Full acknowledgment, apology, corrected output, steps to prevent recurrence
+- **Harmful errors**: Immediate acknowledgment, correction, escalation if needed
+## Design Artefacts
+- Error response templates per severity level
+- Error personality guidelines aligned with overall persona
+- Error detection and self-correction patterns
+- User correction handling protocols
+- Error severity classification rubric

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/persona-architecture/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: persona-architecture
+description: Defining AI character, voice, and personality traits.
+---
+# 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.
+## Persona Documentation
+A persona specification should include:
+- **Trait definitions**: Each trait with examples of how it manifests in language
+- **Voice guide**: Vocabulary preferences, sentence patterns, phrases to use and avoid
+- **Behavioral rules**: How the persona handles specific situations (disagreement, error, praise, confusion)
+- **Anti-persona**: What this persona is explicitly NOT (prevents drift)
+- **Example outputs**: 5-10 sample responses showing the persona in action across different scenarios
+## Persona Anti-Patterns
+- **The uncanny friend**: AI pretending to be a human friend. Users see through it and lose trust.
+- **The personality void**: No discernible character. Outputs feel generic and forgettable.
+- **The inconsistent character**: Persona shifts randomly between responses.
+- **The inappropriate persona**: Playful when the situation is serious. Formal when warmth is needed.
+- **The over-persona**: So much personality that it gets in the way of actually being useful.
+## Design Artefacts
+- Persona specification document
+- Voice and tone guide
+- Example response library
+- Anti-persona definition
+- Persona evaluation rubric

package/src/skills-lib/ai-product-design/references/system-behavior-shaping/tone-calibration/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: tone-calibration
+description: Adjusting formality, warmth, confidence, and style per context.
+---
+# 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.
+- **User preference**: Some users prefer casual. Others prefer formal. Design for adaptation.
+## The Tone Matrix
+Create a matrix mapping contexts to tone settings:
+| Context | Formality | Warmth | Confidence | Pace | Directness |
+|---------|-----------|--------|------------|------|------------|
+| Onboarding | Low | High | Medium | Moderate | Low |
+| Error recovery | Low | High | Low | Slow | Medium |
+| Expert task | Medium | Medium | High | Variable | High |
+| Creative brainstorm | Low | Medium | Medium | Fast | Low |
+| Sensitive topic | High | High | Low | Slow | Low |
+## Tone Consistency Rules
+- Tone shifts should be gradual, not jarring
+- The persona's core traits should be recognisable regardless of tone
+- Tone should respond to the user's tone (mirroring, not mimicking)
+- Avoid tone whiplash — don't go from playful to grave in one turn without transition
+## Design Artefacts
+- Tone matrix mapping contexts to dimension settings
+- Tone trigger definitions
+- Example outputs at different tone settings
+- Tone shift transition guidelines