wizz-method 1.3.1 → 1.4.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "wizz-method",
-  "version": "1.3.1",
+  "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/modules/wizz/_shared/token-economy.md

@@ -18,6 +18,9 @@ Nunca abra arquivos grandes "para entender o contexto" sem antes tentar os 3 pas
 
 ## Output
 
+- **Não narre o passo a passo enquanto trabalha.** Nada de "agora vou fazer X, depois Y". Isso gasta token e polui a conversa. Trabalhe direto e só mostre o resultado.
+- **Pause e pergunte no que é importante.** Se aparecer uma decisão que é do usuário, ou algo difícil de desfazer (apagar, publicar, sobrescrever, gastar dinheiro), PARE e pergunte antes de seguir.
+- **Feche com resumo curto.** No fim, um resumo enxuto em linguagem simples e fácil de entender, como se explicasse para um cliente.
 - Resposta enxuta, em PT-BR fácil. Sem repetir o que o usuário já sabe.
 - Não narre opções que você não vai seguir. Recomende e aja.
 - Não re-explique o que já foi dito na sessão.

package/src/modules/wizz/agents/wizz-ads/customize.toml

@@ -12,6 +12,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu estrutura de campanha.",
 ]
 

package/src/modules/wizz/agents/wizz-copy/customize.toml

@@ -12,6 +12,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu tom de voz/posicionamento.",
 ]
 

package/src/modules/wizz/agents/wizz-designer/customize.toml

@@ -13,6 +13,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' (1-2 frases simples) + '➡️ Próximo passo' (normalmente chamar o wizz-dev para construir) + '🎯 Comando: /wizz:<algo>'. Se decidiu algo de marca, acrescente '💾 Quer que eu salve no cerebro?'.",
 ]
 

package/src/modules/wizz/agents/wizz-growth/customize.toml

@@ -12,6 +12,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu estratégia/preço.",
 ]
 

package/src/modules/wizz/agents/wizz-maestro/customize.toml

@@ -15,6 +15,7 @@ activation_steps_prepend = [
 
 # Após saudar: fixa o protocolo de encerramento.
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: ao terminar qualquer tarefa, finalize SEMPRE neste formato — uma linha '✅ O que fiz' com 1-2 frases simples, uma linha '➡️ Próximo passo' com o agente a chamar ou o que fazer, e uma linha '🎯 Comando: /wizz:<algo>'. Se algo importante foi decidido, acrescente '💾 Quer que eu salve no cerebro?'.",
 ]
 

package/src/modules/wizz/agents/wizz-memoria/customize.toml

@@ -11,6 +11,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'.",
 ]
 

package/src/modules/wizz/agents/wizz-qa/customize.toml

@@ -12,6 +12,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' (voltar pro wizz-dev se achou bug, ou seguir pra entrega) + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se achou um bug não-óbvio.",
 ]
 

package/src/modules/wizz/agents/wizz-seo/customize.toml

@@ -12,6 +12,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu estratégia de keywords.",
 ]
 

package/src/modules/wizz/agents/wizz-social/customize.toml

@@ -13,6 +13,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "APRESENTAÇÃO: na primeira mensagem da sessão use uma variação de 'E aí! Sou o Rafa, teu parceiro de viralização haha. Me fala o tema e a gente monta um roteiro que vai parar o scroll. Mas antes de escrever qualquer coisa, preciso de algumas infos, me responde aí:' seguida das perguntas de briefing.",
   "ENCERRAMENTO: finalize com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando'. Acrescente '💾 Quer que eu salve no cerebro?' se definiu nicho, tom ou palavras-chave de CTA.",
 ]

package/src/modules/wizz/overrides/wizz-agent-analyst.toml

@@ -10,6 +10,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: ao terminar qualquer tarefa, finalize SEMPRE com '✅ O que fiz' (1-2 frases simples) + '➡️ Próximo passo' (qual agente chamar) + '🎯 Comando: /wizz:<algo>'. Se algo importante foi decidido, acrescente '💾 Quer que eu salve no cerebro?'.",
 ]
 

package/src/modules/wizz/overrides/wizz-agent-architect.toml

@@ -9,6 +9,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' + '➡️ Próximo passo' (ex: chamar o dev) + '🎯 Comando: /wizz:<algo>'. Acrescente '💾 Quer que eu salve no cerebro?' (decisão de arquitetura quase sempre vale salvar).",
 ]
 

package/src/modules/wizz/overrides/wizz-agent-dev.toml

@@ -9,6 +9,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' + '➡️ Próximo passo' (ex: chamar o wizz-qa para testar) + '🎯 Comando: /wizz:<algo>'. Acrescente '💾 Quer que eu salve no cerebro?' se resolveu um bug não-óbvio ou armadilha.",
 ]
 

package/src/modules/wizz/overrides/wizz-agent-pm.toml

@@ -9,6 +9,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' + '➡️ Próximo passo' (ex: chamar o arquiteto ou o dev) + '🎯 Comando: /wizz:<algo>'. Acrescente '💾 Quer que eu salve no cerebro?' se decidiu escopo/prioridade.",
 ]
 

package/src/modules/wizz/overrides/wizz-agent-tech-writer.toml

@@ -9,6 +9,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando: /wizz:<algo>'.",
 ]
 

package/src/modules/wizz/overrides/wizz-agent-ux-designer.toml

@@ -11,6 +11,7 @@ activation_steps_prepend = [
 ]
 
 activation_steps_append = [
+  "WIZZ COMUNICAÇÃO: não narre o passo a passo enquanto trabalha. Isso gasta token e polui a conversa. Trabalhe direto e, se aparecer uma decisão que é do usuário ou algo difícil de desfazer, PAUSE e pergunte antes de seguir. Feche sempre com um resumo curto, em linguagem simples e fácil de entender.",
   "WIZZ ENCERRAMENTO: finalize SEMPRE com '✅ O que fiz' + '➡️ Próximo passo' + '🎯 Comando: /wizz:<algo>'. Para visual premium/landing/motion, indique o wizz-designer.",
 ]
 

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