wizz-method 1.3.2 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "description": "Wizz Method — método de agência orientado por IA em PT-BR (fork independente do BMad Method)",
   "keywords": [
     "agile",

package/skills-registry.yaml

@@ -76,6 +76,14 @@ areas:
         when: "Direção de motion/animação, 3D, WebGL, scroll cinematográfico, image-to-video."
       - id: remotion-best-practices
         when: "Vídeo programático em React (Remotion) especificamente."
+      - id: animate
+        when: "Craft de animação/micro-interação: regras do Emil Kowalski (saída > entrada, só transform/opacity, respeitar reduced-motion). Complementa o motion-3d-director com a execução fina. Traz references + exemplos .tsx."
+      - id: design-motion-principles
+        when: "Auditor de movimento: revisa animação existente e aponta scale(0) no início, easing cru, reduced-motion faltando; pesa contenção/polimento/diversão pelo contexto."
+      - id: canvas-design
+        when: "Gerar PNG/PDF editável por código (carrossel, quote card, infográfico) com fonte/cor/logo sempre certos. Traz canvas-fonts."
+      - id: algorithmic-art
+        when: "Visual generativo por código (flow fields, ruído, partículas) para fundo/textura de hero, único a cada render, sem cara de banco de imagem."
       - id: taste-skill
         when: "Anti-slop em briefs NOVOS: lê o brief, define a direção e audita contra defaults de AI."
       - id: taste-redesign
@@ -259,9 +267,9 @@ areas:
     summary: "Arquitetura, banco, segurança, infra, decisões técnicas."
     skills:
       - id: web-security
-        when: "Auditar segurança web, OWASP, XSS/CSRF/injeção, headers, rate limit, antes de deploy/PR."
+        when: "Auditar segurança web, OWASP, XSS/CSRF/injeção/SQLi, IDOR, headers, rate limit (IP+conta), CORS, clickjacking, vazamento de PII na resposta, antes de deploy/PR."
       - id: auth-and-secrets
-        when: "Auth (JWT/OAuth/SSO/Clerk), gestão de secrets, rotação de credenciais."
+        when: "Auth (JWT/OAuth/SSO/Clerk), token no header vs URL, revogar no logout, enumeração de usuário, gestão de secrets, rotação de credenciais."
       - id: desktop-security
         when: "Segurança desktop/Electron (contextIsolation, code signing)."
       - id: database-scaling
@@ -276,6 +284,8 @@ areas:
         when: "Dependências/packages, vulnerabilidades, npm audit."
       - id: supabase-postgres-best-practices
         when: "Performance e boas práticas de Postgres/Supabase (queries, schema, RLS)."
+      - id: ai-product-design
+        when: "Construir/melhorar um agente ou produto de IA: escrever/revisar system prompt, definir persona/tom, guardrails e recusas, few-shot, chain-of-thought, orquestração multi-agente, handoff, detecção de frustração, generative UI, avaliar qualidade de saída. Base para desenhar os próprios agentes do método. 44 padrões (Owl-Listener, MIT)."
     mcps:
       - id: supabase
         when: "Operar Supabase de verdade: rodar SQL, migrations, inspecionar schema/RLS, logs."

package/src/skills-lib/ai-product-design/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: ai-product-design
+description: >
+  Design de produtos e agentes de IA: como o agente se comporta, como escrever o prompt/system prompt,
+  guardrails e trust/safety, orquestração multi-agente e avaliação. Usar quando: criar ou melhorar um
+  agente/assistente/chatbot, escrever ou revisar system prompt, definir persona/tom/voz, montar few-shot,
+  chain-of-thought, guardrails, recusas, escalonamento pra humano, handoff entre agentes, detecção de
+  frustração, generative UI, ou medir qualidade de saída de IA. Base: Owl-Listener/ai-design-skills (MIT).
+  44 padrões em 6 categorias, cada um detalhado em references/.
+---
+
+# AI Product Design — 44 padrões
+
+Biblioteca de padrões pra desenhar **como uma IA/agente se comporta** e **como o prompt dele é escrito**.
+Cada item abaixo tem o texto completo em `references/<categoria>/<nome>/SKILL.md`. Este arquivo é o índice:
+ache o padrão pela intenção, depois abra a reference pro detalhe.
+
+> Uso no método: é a base pra construir e revisar os próprios agentes do Wizz Method (os 15 `customize.toml`,
+> system prompts, guardrails, handoffs). Consulte antes de criar/ajustar qualquer agente ou prompt.
+
+## 1. Comportamento do agente (`references/system-behavior-shaping/`)
+Como o agente soa e reage.
+- **persona-architecture** — define personagem, voz e traços uma vez, pra não derivar entre sessões
+- **tone-calibration** — botões de tom por contexto (formalidade, calor, confiança)
+- **emotional-design** — resposta a frustração, confusão, alegria, angústia (valida sem amplificar)
+- **error-personality** — como comunicar erro, incerteza e limite com elegância
+- **behavioral-consistency** — comportar-se previsível entre sessões, edge cases e modalidades
+- **domain-voice** — ajustar o comportamento pra um domínio profissional específico
+- **cultural-adaptation** — adaptar a contexto cultural, idioma e normas
+
+## 2. Interação humano-IA (`references/model-interaction-design/`)
+Como a conversa flui.
+- **conversation-patterns** — turnos, sequências de reparo, checkpoints de alinhamento
+- **frustration-detection** — ler frustração por caps, pontuação, repetição, latência e adaptar
+- **mixed-initiative-flow** — quando o agente lidera vs. quando o usuário lidera, com handoff limpo
+- **progressive-disclosure** — revelar o poder da ferramenta aos poucos, sem afogar no turno 1
+- **generative-ui** — quando renderizar um componente (date picker, card, gráfico) vs. texto puro
+- **multimodal-orchestration** — sequenciar texto, imagem, voz e uso de tool num fluxo só
+- **feedback-loops** — correção do usuário, thumbs, edição inline como sinal que muda o comportamento
+- **context-window-design** — orçamento de tokens, memória, resumir vs. buscar, degradação suave
+
+## 3. Arquitetura de prompt (`references/prompt-architecture/`)
+Como o prompt é escrito. **A camada mais direta pra melhorar agentes.**
+- **system-prompt-structure** — anatomia: identidade, contexto, regras, formato, exemplos (o que importa no começo/fim)
+- **constraint-specification** — limites testáveis: formato, tamanho, tom, conteúdo proibido
+- **few-shot-patterns** — exemplos que miram os erros que o modelo insiste em cometer
+- **chain-of-thought-design** — cadeias de raciocínio deliberadas pra tarefa de vários passos
+- **template-design** — templates parametrizados com variáveis nomeadas e seções condicionais
+- **context-engineering** — o que entra no contexto e em que ordem
+- **prompt-versioning** — versionar prompts, testar mudanças, rastrear o que funciona
+
+## 4. Trust & Safety (`references/ai-alignment-reasoning/`)
+O que o agente pode e não pode; como não enganar o usuário.
+- **guardrail-design** — limites de comportamento e padrões de recusa explícitos (o "pode/não pode")
+- **transparency-patterns** — mostrar o que o modelo sabe, não sabe e o quão certo está
+- **trust-calibration** — nem overtrust nem undertrust; sinalizar incerteza em vez de blefar
+- **escalation-design** — quando escalar pra humano, recusar, ou pedir esclarecimento
+- **harm-anticipation** — mapear failure modes, mau uso e consequências não intencionais
+- **value-specification** — traduzir valores da organização em constraints do sistema
+- **consent-and-agency** — consentimento informado, opt-out e override humano
+- **bias-detection-design** — workflows de review pra achar e mitigar viés
+
+## 5. Orquestração multi-agente (`references/design-agent-orchestration/`)
+Pra sistemas com vários agentes (o caso do próprio método: Diretor → maestro → agentes).
+- **agent-role-design** — o que cada agente faz, sabe e é dono num sistema multi-agente
+- **task-decomposition** — quebrar objetivo complexo em subtarefas que os agentes resolvem
+- **handoff-protocols** — transições suaves entre agentes e entre IA e humano
+- **state-management** — contexto, memória e estado compartilhados entre agentes
+- **human-in-the-loop** — pontos de intervenção onde o humano revisa, aprova ou redireciona
+- **failure-recovery** — quando um agente falha: retry, fallback, escalar, degradação suave
+- **observability-design** — tornar o workflow multi-agente visível e debugável
+
+## 6. Avaliação (`references/evaluation/`)
+Como saber se a IA está boa.
+- **output-quality-rubrics** — definir o que é "bom": acurácia, relevância, utilidade
+- **task-success-metrics** — medir se a IA de fato ajudou o usuário a concluir a meta
+- **user-satisfaction-signals** — ler sinais implícitos/explícitos: edições, regenerações, abandono
+- **failure-taxonomy** — classificar falhas: alucinação, recusa, irrelevância, tom errado, latência
+- **comparative-evaluation** — A/B, comparação lado a lado, ranking de preferência
+- **heuristic-evaluation-ai** — heurísticas de Nielsen adaptadas + heurísticas próprias de IA
+- **longitudinal-measurement** — qualidade ao longo do tempo: drift, degradação, melhoria
+
+---
+
+**Créditos:** Owl-Listener/ai-design-skills (licença MIT, ver `references/LICENSE`). Índice traduzido/curado para o Wizz Method.

package/src/skills-lib/ai-product-design/references/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MC Dean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/bias-detection-design/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: bias-detection-design
+description: Designing review workflows to surface and mitigate bias in AI outputs.
+---
+# Bias Detection Design
+AI systems inherit biases from training data, amplify them through pattern-matching, and embed them in outputs that appear authoritative. Bias detection design creates the workflows, processes, and interfaces that help teams find and fix bias before users encounter it.
+## Types of Bias in AI Products
+- **Representation bias**: Some groups are overrepresented or underrepresented in outputs (images, examples, personas)
+- **Performance bias**: The AI works better for some users than others (languages, accents, cultural contexts)
+- **Framing bias**: The AI presents information in ways that favour certain perspectives
+- **Allocation bias**: AI-driven decisions distribute resources or opportunities unevenly
+- **Association bias**: The AI links concepts in stereotypical ways
+## Designing Bias Detection Workflows
+Bias detection is a team practice, not a one-time audit:
+- **Regular review cycles**: Schedule periodic reviews of AI outputs for bias patterns
+- **Diverse review panels**: Include reviewers from different backgrounds, cultures, and perspectives
+- **Structured evaluation**: Use rubrics and checklists, not intuition
+- **Real-world sampling**: Test with real user inputs, not just curated test cases
+- **Longitudinal monitoring**: Bias can emerge over time as usage patterns change
+## Detection Methods
+- **Comparative testing**: Give the AI the same task with different demographic variables. Compare outputs.
+- **Edge case exploration**: Test inputs from underrepresented groups or unusual contexts.
+- **Output auditing**: Review a sample of real outputs for patterns of bias.
+- **User feedback analysis**: Look for bias-related complaints or differential satisfaction.
+- **Benchmark evaluation**: Test against established fairness benchmarks for the domain.
+## From Detection to Mitigation
+Finding bias is step one. Addressing it requires:
+- **Root cause analysis**: Is the bias in training data, prompt design, model architecture, or product design?
+- **Mitigation options**: Retraining, prompt adjustment, output filtering, user controls, or design changes
+- **Tradeoff analysis**: Fixing one bias might introduce another. Document the tradeoffs.
+- **Verification**: After mitigation, verify the fix worked without creating new problems.
+## Design Artefacts
+- Bias audit checklists per feature
+- Review panel composition guidelines
+- Comparative testing protocols
+- Bias incident documentation templates
+- Mitigation tracking logs

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/consent-and-agency/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: consent-and-agency
+description: Designing for informed user consent, opt-out, and human override.
+---
+# Consent and Agency
+AI products make decisions, take actions, and process information on behalf of users. Consent and agency design ensures users remain in control — understanding what the AI does, agreeing to it, and being able to override it.
+## Informed Consent for AI
+Users should understand and agree to:
+- **What data the AI uses**: Conversation history, personal data, uploaded documents, browsing behaviour
+- **What the AI does with it**: Training, personalisation, sharing with third parties, storage
+- **What actions the AI takes**: Sending messages, making changes, accessing systems
+- **What the AI can't do**: Limitations that might affect the user's expectations
+Consent is not a checkbox at sign-up. It's an ongoing design challenge throughout the experience.
+## Designing for Agency
+Agency means the user feels — and is — in control:
+- **Opt-in over opt-out**: AI features should be activated by the user, not imposed
+- **Reversibility**: AI actions should be undoable wherever possible
+- **Override mechanisms**: The user can always stop, redirect, or override the AI
+- **Exit paths**: The user can disengage from AI assistance at any point without penalty
+- **Preference controls**: The user can adjust AI behaviour, scope, and autonomy levels
+## Consent Patterns
+- **Progressive consent**: Ask for permission incrementally as new capabilities are needed, not all at once
+- **Contextual consent**: Ask at the moment the action is about to happen, not in advance
+- **Granular consent**: Let users consent to specific actions or data uses, not blanket permissions
+- **Revocable consent**: Users can withdraw consent and have that withdrawal take effect
+## Agency Anti-Patterns
+- **Dark patterns**: Making it hard to opt out or override the AI
+- **Consent fatigue**: Asking for permission so often that users click through without reading
+- **Learned helplessness**: AI does so much that users forget how to do things themselves
+- **Invisible actions**: The AI takes actions the user doesn't know about
+- **Irreversible defaults**: AI actions that can't be undone without user awareness
+## Design Artefacts
+- Consent flow diagrams per feature
+- Agency checkpoint specifications
+- Override mechanism inventory
+- Data use transparency matrix
+- Opt-out path designs

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/escalation-design/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: escalation-design
+description: When and how AI should escalate to humans, refuse, or ask for clarification.
+---
+# Escalation Design
+Escalation is what happens when the AI reaches the boundary of what it should handle alone. Designing escalation well means the user gets help instead of a dead end — and the AI knows its limits.
+## Escalation Triggers
+The AI should escalate when:
+- **Confidence is low**: The AI isn't sure its output is correct or helpful
+- **Stakes are high**: The decision has significant consequences (financial, medical, legal, safety)
+- **Emotional distress**: The user shows signs of crisis, distress, or vulnerability
+- **Ambiguity is unresolvable**: The AI can't determine intent even after clarification
+- **Scope boundary**: The request is outside what the AI is designed to handle
+- **Policy boundary**: The request approaches or crosses a guardrail
+- **Conflict**: The user disagrees with the AI and the disagreement can't be resolved
+## Escalation Types
+- **To human support**: Transfer to a human agent with full context
+- **To the user themselves**: "This decision is yours to make" — handing back agency
+- **To a specialist**: Routing to domain-specific help (medical, legal, technical)
+- **To a supervisor/admin**: Flagging for organisational review
+- **Self-escalation**: The AI flags its own output for review before delivering it
+## Designing the Escalation Experience
+The user's experience of escalation matters:
+- **Context transfer**: When escalating to a human, pass the full conversation. Don't make the user repeat themselves.
+- **Warm handoff**: "I'm connecting you with someone who can help with this" — not a cold redirect.
+- **Expectation setting**: Tell the user what will happen next and how long it might take.
+- **Graceful degradation**: If no human is available, offer alternatives — not a dead end.
+- **Dignity**: Never make the user feel stupid for needing escalation.
+## Escalation Anti-Patterns
+- **The infinite loop**: AI keeps trying instead of escalating, frustrating the user
+- **Premature escalation**: AI escalates when it could easily handle the request, annoying the user
+- **Context loss**: User has to start over after escalation
+- **Blame shifting**: AI implies the user caused the problem
+- **Hidden escalation**: Escalation happens without the user knowing
+## Design Artefacts
+- Escalation trigger matrix: Trigger | Threshold | Escalation Type | User Experience
+- Escalation flow diagrams per feature
+- Context handoff specifications
+- Fallback path designs for when escalation isn't available
+- Escalation quality metrics

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/guardrail-design/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: guardrail-design
+description: Defining behavioral boundaries — what the AI should and shouldn't do.
+---
+# Guardrail Design
+Guardrails are the behavioral boundaries that define what an AI product will and won't do. They're not just safety constraints — they're design decisions that shape the entire user experience.
+## Types of Guardrails
+- **Content guardrails**: What topics the AI will and won't discuss. What it generates and refuses to generate.
+- **Action guardrails**: What the AI can do in the world — send emails, make purchases, delete data — and what requires human approval.
+- **Tone guardrails**: How the AI communicates — what language it uses, how formal or casual, when it's direct vs. diplomatic.
+- **Scope guardrails**: What the AI considers in and out of scope for its role. A coding assistant shouldn't give medical advice.
+- **Confidence guardrails**: When the AI should express uncertainty, hedge, or refuse rather than guessing.
+## Designing Guardrails as Product Decisions
+Every guardrail is a product decision with tradeoffs:
+- **Too strict**: The product feels limited, frustrating, and paternalistic. Users route around the guardrails.
+- **Too loose**: The product causes harm, loses trust, and creates liability.
+- **Inconsistent**: Users can't predict what the AI will and won't do, eroding trust.
+The goal is guardrails that feel like good judgment, not arbitrary restrictions.
+## Guardrail Specification
+For each guardrail, define:
+- **What it prevents**: The specific behavior or output being constrained
+- **Why it exists**: The harm it prevents or the value it protects
+- **How it manifests**: What the user sees when the guardrail activates (refusal message, alternative suggestion, escalation)
+- **Edge cases**: Grey areas where the guardrail might be too strict or too loose
+- **Override conditions**: Whether and how the guardrail can be relaxed (admin settings, user confirmation, context-dependent)
+## Guardrail Communication
+How the AI communicates a guardrail matters as much as the guardrail itself:
+- **Transparent refusal**: "I can't help with that because..." — honest about the boundary
+- **Redirective refusal**: "I can't do X, but I can help you with Y" — offering alternatives
+- **Silent guardrail**: The AI steers away from the boundary without mentioning it
+- **Escalation**: "This needs a human to review" — handing off rather than refusing
+## Design Artefacts
+- Guardrail specification table: Category | Rule | Rationale | User Experience | Edge Cases
+- Refusal message templates per guardrail type
+- Guardrail severity tiers (hard block vs. soft warning vs. nudge)
+- Testing scenarios for each guardrail

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/harm-anticipation/SKILL.md

@@ -0,0 +1,108 @@
+---
+name: harm-anticipation
+description: Proactively identifying failure modes, misuse, and unintended consequences.
+---
+# Harm Anticipation
+
+Harm anticipation is systematically thinking through how an AI product could cause harm — before it does. Preventive design, not reactive crisis management.
+
+The work is unglamorous and easy to skip. Done well, it produces specific testable mitigations. Done badly, it produces a doc nobody reads.
+
+## Categories of AI harm
+
+- **Direct harm**: the AI outputs something harmful — dangerous advice, discriminatory content, privacy violations
+- **Facilitated harm**: the AI helps a user do something harmful, even if the AI's output itself is benign
+- **Emergent harm**: harmful patterns from scale or interaction effects, not from any single output
+- **Omission harm**: the AI fails to act when it should — not flagging a crisis, not escalating
+- **Erosion harm**: gradual negative effects — dependency, deskilling, manipulation, trust erosion
+
+## Structured anticipation
+
+Work through each harm category with five lenses:
+
+1. **Who could be harmed?** The user, people the user interacts with, vulnerable populations, society at large.
+2. **How could they be harmed?** Physical, emotional, financial, reputational, privacy, autonomy.
+3. **What's the likelihood?** Common use case vs. edge case vs. adversarial attack.
+4. **What's the severity?** Inconvenience vs. distress vs. irreversible damage.
+5. **What's the detectability?** Obvious and immediate vs. subtle and delayed.
+
+## Misuse scenarios
+
+Think like an adversary:
+
+- How would someone deliberately misuse this feature?
+- What's the easiest way to extract harmful output?
+- Could this be used to manipulate, deceive, or coerce?
+- What if the user lies about their intent?
+- What happens at scale, automated?
+
+## Unintended consequences
+
+Think second-order:
+
+- What happens at millions of users?
+- What skills do users lose by relying on this?
+- Could this create unfair advantages or disadvantages?
+- What power dynamics shift?
+- What becomes possible that wasn't before — for better and worse?
+
+## Decision rules
+
+- **Score by frequency × severity, not severity alone.** A common moderate harm beats a rare catastrophic one in cumulative impact, almost every time. Teams chronically over-weight catastrophic-rare and under-weight chronic-moderate.
+- **Each harm needs a falsifiable test.** "If the AI does X to user type Y, the system should Z." If you can't write the test, you haven't specified the harm precisely enough — refine before mitigating.
+- **Mitigate at the lowest layer that works.** Filtering output is weaker than constraining the prompt; constraining the prompt is weaker than scoping the feature; scoping the feature is weaker than not building it.
+- **Re-anticipate after each scale jump.** Harms at 1k users differ from 100k differ from 10M. The same checklist gives different answers at each tier.
+- **Vulnerable users define the floor, not the ceiling.** If the worst-off user is well-served, others will be too. Designing for the median user with edge-case patches is the wrong shape.
+- **Prefer reversible mitigations during the discovery phase.** Lock-in early and you'll be scared to revisit assumptions.
+
+## Anti-patterns
+
+- **Pre-mortem theatre**: writing the harm anticipation doc as a deliverable, then never opening it again. The doc is the artefact; the practice is the value.
+- **Worst-case-only thinking**: only catastrophic harms get attention. Moderate-frequency moderate-severity harms accumulate unaddressed and become the actual product story.
+- **Adversary-only framing**: anticipating bad actors but missing harms from well-intentioned users in unexpected contexts (the helpful suicide-line responder, the well-meaning legal advice giver).
+- **Mitigation-by-checklist**: treating harms as boxes to tick rather than ongoing design constraints. Once boxed, the harm is "handled" until it isn't.
+- **Externalised liability**: "the user agreed to ToS, we're covered." Liability ≠ harm reduction. Users are still hurt; the company is just protected.
+- **Single-axis thinking**: anticipating along one harm category and missing intersections. "We checked for bias and we checked for privacy" — but bias × privacy at intersection is its own failure mode.
+- **Optimist's mitigation**: writing mitigations that depend on the user noticing, the user reporting, the AI detecting. If the mitigation requires a working sensor, audit whether the sensor actually works.
+
+## When not to use this
+
+- **For routine UX paper-cuts** (slow loads, awkward copy) — reach for `failure-taxonomy` or `user-satisfaction-signals` instead. Harm anticipation is for *consequences*, not friction.
+- **For purely technical reliability** (latency, uptime) — those are SRE concerns; harm anticipation is the product-level layer above them.
+- **In place of red-teaming** — anticipation is a planning activity; red-teaming is a probing activity. Both, not either.
+- **As a one-off audit at launch** — the anticipation that catches harms is the one done continuously, especially after each significant change.
+
+## See also
+
+- `trust-calibration` — overtrust is itself a harm category; calibrated trust is one of the strongest mitigations.
+- `escalation-design` — many harms are mitigated by *not handling it alone*. Anticipation surfaces the trigger; escalation handles the moment.
+- `bias-detection-design` — bias is a harm category with its own dedicated detection methodology; reach for that skill once you've identified bias risks here.
+- `value-specification` — harm anticipation populates the constraints; value specification arbitrates between them when they conflict.
+- `guardrail-design` — anticipation produces the requirements; guardrail-design is the mechanism.
+
+## Design Artefacts
+
+- Harm anticipation matrix
+- Misuse scenario catalogue
+- Pre-mortem analysis documents
+- Risk-severity heatmaps for product features
+- Mitigation tracking log with pass/fail tests per harm
+
+Worked example — one row of the harm anticipation matrix for an AI mental-health-support chatbot:
+
+| Field | Value |
+| --- | --- |
+| Scenario | User in acute crisis (suicidal ideation language) asks for advice. |
+| Harm category | Omission harm + Direct harm. |
+| Who is harmed | The user, their dependents. |
+| How | AI provides general advice without recognising crisis; user delays seeking emergency help. |
+| Likelihood | Medium — crisis users are a minority of usage but represent peak-stakes interactions. |
+| Severity | Catastrophic, irreversible. |
+| Detectability | Low at the per-interaction level (no obvious bad output); medium retrospectively (post-incident review). |
+| Mitigation | Crisis-marker classifier on user input; on detection, replace the AI response with hardcoded crisis-line copy + warm handoff to human counsellor. Falsifiable test: red-team prompts containing 30 documented crisis-language patterns; 100% must trigger the override. |
+| Mitigation strength | Lower-layer than output filtering — replaces the response entirely rather than scrubbing. |
+| Re-anticipate at | 10× user growth, model version change, language expansion. |
+
+The mitigation has a test. The test is run on every model update. That makes the harm anticipation a living constraint, not a doc.
+
+Adapted from work on responsible AI deployment (Raji et al. on closing the AI accountability gap; Weidinger et al. on taxonomies of risk from language models) and pre-mortem methodology from cognitive psychology (Klein on prospective hindsight).

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/transparency-patterns/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: transparency-patterns
+description: Showing users what the AI knows, doesn't know, and how confident it is.
+---
+# Transparency Patterns
+Transparency in AI products means making the system's knowledge, limitations, and confidence visible to users. It's how you build warranted trust — trust based on understanding, not blind faith.
+## What to Make Transparent
+- **Source**: Where did the AI get this information? Training data, retrieved documents, user input, inference?
+- **Confidence**: How certain is the AI? Is this a well-supported answer or a best guess?
+- **Limitations**: What doesn't the AI know? What can't it do? Where does its knowledge end?
+- **Process**: How did the AI arrive at this output? What steps did it take?
+- **Identity**: This is an AI, not a human. Never obscure this.
+## Transparency Patterns
+- **Confidence indicators**: Visual or textual signals of certainty ("I'm fairly confident" vs. "I'm not sure about this")
+- **Source attribution**: Citing where information came from
+- **Reasoning traces**: Showing the AI's step-by-step thinking
+- **Limitation disclosure**: Proactively stating what the AI can't do or doesn't know
+- **Model cards**: High-level descriptions of what the AI is, how it works, and what it's good and bad at
+- **Uncertainty highlighting**: Visually distinguishing confident outputs from uncertain ones
+## Calibrating Transparency
+Too much transparency overwhelms. Too little erodes trust. Calibrate by:
+- **User expertise**: Experts want more detail. Novices want simple signals.
+- **Task stakes**: High-stakes decisions need full transparency. Low-stakes interactions need less.
+- **Output confidence**: Show more transparency when the AI is uncertain, less when it's confident.
+- **User request**: Let users drill into details on demand rather than showing everything upfront.
+## Transparency Anti-Patterns
+- **Performative transparency**: Showing a reasoning trace that doesn't actually explain the decision
+- **Buried disclaimers**: Putting limitations in fine print nobody reads
+- **False confidence**: The AI sounds certain when it's guessing
+- **Opaque refusal**: "I can't help with that" with no explanation
+- **Transparency theatre**: Making the system look transparent without actually being informative
+## Design Artefacts
+- Transparency level specifications per feature
+- Confidence communication guidelines
+- Source attribution patterns
+- Limitation disclosure templates

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/trust-calibration/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: trust-calibration
+description: Helping users form warranted trust in the AI — neither overtrust nor undertrust — through deliberate confidence and source signalling.
+---
+# Trust Calibration
+
+Calibrated trust is the difference between an AI that augments user judgment and one that displaces it. Overtrust causes harm when the AI is wrong. Undertrust wastes the AI when it's right. Both failure modes are common, and neither shows up in standard accuracy metrics.
+
+Designing for trust means giving users the information they need to update their trust appropriately, turn by turn.
+
+## What shapes user trust in the moment
+
+- **Surface confidence** — how certain the AI sounds, regardless of whether it should
+- **Track record** — prior interactions in this and previous sessions
+- **Stakes legibility** — how clearly the user understands what could go wrong
+- **Source visibility** — whether the AI shows reasoning, sources, or alternatives
+- **Persona fit** — a "professional" persona gets more trust than a "friendly" one for the same content
+
+These shape trust whether you design for them or not. Designing for them deliberately is what trust calibration is.
+
+## Trust failure modes
+
+- **Sycophancy-driven overtrust**: AI tells the user what they want to hear; user trusts the agreement and acts on it
+- **Confidence-mismatch overtrust**: AI sounds certain about something it shouldn't be (hallucinations, edge cases)
+- **Defensive undertrust**: AI hedges everything ("might be", "could possibly") even when right; user tunes out the qualifier
+- **Authority-collapse undertrust**: one wrong answer in a high-stakes context destroys trust for the whole product
+- **Trust laundering**: low-confidence outputs presented with high-confidence formatting (bold headers, decisive bullets) — visual authority disconnected from epistemic authority
+
+## Calibration signals from the AI side
+
+The AI shapes trust deliberately through:
+
+- **Confidence markers proportionate to actual epistemic state**: "I'm fairly sure" / "I'd verify this" / "I don't know" — used because they're true, not as decoration
+- **Source attribution**: "According to [X]" rather than unsourced assertion. Cite when possible; flag the gap when not.
+- **Alternative surfacing**: "Two interpretations: A and B. I went with A because…" — shows the model's working
+- **Failure transparency**: "I got that wrong earlier — here's the correction." Long-term trust gain at short-term cost.
+- **Capability fence-posting**: "I can help with X but not Y." Defines the boundary so trust isn't tested in the wrong place.
+
+## Calibration signals from the user side
+
+Trust is two-way. The AI also helps the user calibrate:
+
+- **Showing the cost of being wrong**: "If this is wrong, you'd want to verify against [source] before [action]"
+- **Recommending verification thresholds**: "Low-stakes: this is probably fine. High-stakes: double-check."
+- **Acknowledging variance**: "This worked for most users in your situation; yours may differ."
+
+## Decision rules
+
+- **High stakes + low confidence → bias toward undertrust by default.** The cost of an action on bad info exceeds the cost of an extra verification step.
+- **If the user has corrected the AI in this session, raise hedging on similar outputs for the rest of the session.** *Show* the AI updating.
+- **Never inflate confidence to match the user's apparent expectation.** Sycophancy is the worst trust failure because it compounds across turns.
+- **Prefer "I don't know" over a confident wrong answer.** The trust cost of "I don't know" is lower than the trust cost of being caught wrong.
+- **If the AI must guess, flag it.** "Best guess: X. Reasoning: Y. Confidence: low — verify if this matters."
+- **If the AI changes position based on user pushback, name the update.** Silent flips destroy trust faster than disagreement does.
+
+## Anti-patterns
+
+- **Universal hedging**: every output ends with "but you should verify". The qualifier loses signal and reads as legal cover.
+- **Confidence theatre**: bold formatting, decisive language, perfect grammar applied to outputs the AI is uncertain about. Visual confidence ≠ epistemic confidence.
+- **Apology as trust-building**: over-apologising for errors signals incompetence, not calibration. One clean acknowledgement is more trustworthy than five.
+- **Personality-driven confidence**: the AI's persona dictates its confidence level rather than its actual epistemic state ("I'm a confident assistant!").
+- **Silent updating**: the AI changes position on user pushback without flagging it. Users notice; trust drops sharply.
+- **Trust transfer by association**: "Anthropic-built" / "GPT-4-powered" framed as a quality guarantee. Pedigree ≠ correctness in a specific case.
+
+## When not to use this
+
+- **Low-stakes recreational AI** (creative writing, brainstorming) where calibrated trust isn't the operating mode. Reach for `tone-calibration` or `progressive-disclosure` instead.
+- **Deterministic-output products** (code formatting, image conversion) where outputs are checkable directly. Verification is cheap; trust calibration matters less.
+- **First-touch onboarding**, where the user has no prior relationship. Trust builds through repeated interaction, not through hedges in turn one.
+
+## See also
+
+- `transparency-patterns` — the operational mechanism (showing reasoning, sources, alternatives). Trust calibration is the *outcome*; transparency is one *tool*.
+- `error-personality` — how the AI handles being wrong is the highest-leverage trust signal in the product.
+- `consent-and-agency` — closely related: trust calibration without preserved user agency tips into manipulation.
+- `escalation-design` — knowing when to hand off is itself a trust-building behaviour ("I won't pretend to handle this").
+
+## Design Artefacts
+
+A trust calibration matrix:
+
+| Stakes | AI confidence | Recommended language |
+| --- | --- | --- |
+| Low | Low | "Best guess: X. Easy to check by [Y]." |
+| Low | High | Direct answer, no hedge. |
+| Medium | Low | "I'd suggest X based on [Y]. If your situation differs, talk to [Z]." |
+| Medium | High | Direct answer + one-line source. |
+| High | Low | "I'm not the right tool for this. Try [Z]." |
+| High | High | Direct answer + source + recommended verification step. |
+
+Worked example:
+- User asks an AI assistant: "is it safe to take ibuprofen with my blood thinner?"
+- Stakes: high. AI confidence: low (medical question without patient record).
+- Response: "I can't give medical advice on drug interactions — for blood thinners specifically the answer depends on which one and your dosage. Please ask your prescriber or call a pharmacist; many have free phone consults."
+
+Other artefacts:
+- A confidence-language rubric: a banned-phrase list ("I'm 100% sure", "always", "never" without justification) and an approved-phrase set tied to confidence levels
+- Sycophancy stress tests: inputs designed to elicit agreement; measure whether expressed confidence inflates when the user pushes
+- A trust-loss audit: classify sessions where users push back as "AI right, user wrong" / "AI wrong, user right" / "ambiguous". Track AI behaviour across categories — does it cave to pushback even when right?
+- Persona-confidence audit: hold the same factual claim constant; vary the persona; measure perceived authority. Tune until persona doesn't drive trust independent of content.
+
+Adapted from research on calibrated trust in human-AI teams (Lee & See 2004 on appropriate reliance; Lai et al. on trust in machine learning systems).

package/src/skills-lib/ai-product-design/references/ai-alignment-reasoning/value-specification/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: value-specification
+description: Translating organisational values and user expectations into system constraints.
+---
+# Value Specification
+Values are abstract. AI systems need concrete rules. Value specification is the design work of translating organisational principles and user expectations into implementable constraints.
+## The Translation Problem
+Organisations say things like "be helpful" and "be responsible." These are useless as system constraints because they conflict:
+- Being maximally helpful might mean giving dangerous information
+- Being maximally responsible might mean refusing to help at all
+- Being "fair" means different things in different contexts
+The designer's job is to resolve these tensions into specific, testable rules.
+## Value Hierarchy
+Not all values are equal. Establish a hierarchy:
+1. **Safety**: Prevent harm to users and others. This overrides everything.
+2. **Accuracy**: Don't mislead. When uncertain, say so.
+3. **Helpfulness**: Actually accomplish what the user needs.
+4. **Respect**: Treat users as capable adults. Don't patronise.
+5. **Brand alignment**: Reflect the organisation's identity and tone.
+When values conflict, the hierarchy resolves the conflict. A safety concern overrides helpfulness. Accuracy overrides brand voice.
+## From Values to Rules
+For each value, derive concrete rules:
+- **Value**: "We respect user autonomy"
+- **Rule**: "Always present options rather than making decisions for the user"
+- **Implementation**: When the AI has multiple valid approaches, present them as choices with tradeoffs rather than picking one
+- **Test**: Give the AI an ambiguous request. Does it ask the user to choose, or decide unilaterally?
+## Stakeholder Alignment
+Different stakeholders have different value priorities:
+- **Users** want helpfulness and speed
+- **Legal** wants compliance and liability protection
+- **Brand** wants consistency and tone
+- **Ethics** wants fairness and transparency
+- **Engineering** wants feasibility and maintainability
+The designer mediates between these perspectives and produces a unified specification.
+## Design Artefacts
+- Value hierarchy document with conflict resolution rules
+- Value-to-rule mapping table
+- Stakeholder value alignment matrix
+- Test cases derived from value specifications