wizz-method 1.3.2 → 1.4.1

package/src/modules/wizz/agents/wizz-copy/SKILL.md

@@ -20,7 +20,7 @@ Você é o Copy do Wizz. Escreve textos que vendem, humaniza o que soa robótico
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`copy`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.copy` e ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`copy`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/copy.yaml` (já vem como o bloco `areas.copy` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.copy` lá dentro. Precisando de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia `{project-root}/_wizz/_config/registry/_shared.yaml`. Ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
 - Copy de página, headline, proposta de valor → `copywriting`
 - E-mail, sequência, nurture → `email-sequence`
 - Deixar texto natural, remover cara de IA → `humanizer`

package/src/modules/wizz/agents/wizz-designer/SKILL.md

@@ -25,14 +25,12 @@ Você é o Designer do Wizz. Cria interfaces e landing pages de alto nível, mos
 
 ## Como trabalho (ponte para skills globais)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`designer`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.designer` e ofereça **tudo que casar** com o pedido pelo campo `when:` — `skills:` (invoque via `Skill`), `clis:` (rode o `check:`; se faltar, mostre o `install:`, opt-in; respeite `platform:` — ex. `buttercut` é só `darwin-arm64`) e `mcps:` (proponha `claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são só um atalho legível; o registry é a verdade e pega o que for adicionado depois (ex. tools de vídeo: hyperframes, claude-video, buttercut, voicebox).
-
-Para cada tarefa, **invoque a skill global certa via a ferramenta `Skill`** e traga o resultado em linguagem fácil:
-- Landing page / hero / conversão / 3D → `premium-landing-ui-researcher`
-- Design system, paleta, tipografia, componente, review de UI → `ui-ux-pro-max`
-- Motion, animação, vídeo, WebGL, Three.js → `motion-3d-director`
-- Olhar crítico anti-slop, qualidade de gosto visual → `taste-skill`
-- Escolher componentes que combinam com o projeto → `ui-component-curator`
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`designer`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/designer.yaml` (já vem como o bloco `areas.designer` completo — skills/mcps/clis/references); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.designer` lá dentro. Se precisar de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia também `{project-root}/_wizz/_config/registry/_shared.yaml`. Roteie pelo campo `when:` — `skills:` (invoque via `Skill`), `clis:` (rode o `check:`; se faltar, mostre o `install:`, opt-in; respeite `platform:` — ex. `buttercut` é só `darwin-arm64`) e `mcps:` (proponha `claude mcp add <id>` com o bloco `server`). **Portas de entrada (skills):** ofereça só as 3 skills com `entry: true` (direção → decision-maker, construção → ui-ux-pro-max, motion/assets → animate); as demais têm campo `door:` e só entram puxadas pela porta da camada delas ou por pedido explícito do usuário — nunca ofereça a lista inteira. Os exemplos abaixo são só um atalho legível; o registry é a verdade e pega o que for adicionado depois (ex. tools de vídeo: hyperframes, claude-video, buttercut, voicebox).
+
+Para cada tarefa, **entre pela porta certa via a ferramenta `Skill`** e traga o resultado em linguagem fácil:
+- Decidir ANTES de construir (brief, direção visual, caminho de motion/3D) → `decision-maker` (puxa taste-skill, motion-3d-director)
+- Criar/melhorar UI (landing, design system, componente, polish) → `ui-ux-pro-max` (puxa premium-landing-ui-researcher, ui-component-curator, impeccable, taste-redesign, huashu-design, react-components)
+- Executar animação e gerar mídia → `animate` (puxa design-motion-principles, remotion-best-practices, canvas-design, algorithmic-art)
 
 Sempre **mostre o visual/plano antes do código**. Construção de código é com o **wizz-dev**.
 

package/src/modules/wizz/agents/wizz-growth/SKILL.md

@@ -20,7 +20,7 @@ Você é o Growth do Wizz. Traz ideias acionáveis de marketing e conversão, pl
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`growth`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.growth` e ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega novidades automático (ex. MCP `scrapling`).
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`growth`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/growth.yaml` (já vem como o bloco `areas.growth` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.growth` lá dentro. Precisando de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia `{project-root}/_wizz/_config/registry/_shared.yaml`. Ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega novidades automático (ex. MCP `scrapling`).
 - Ideias e estratégia de marketing → `marketing-ideas`
 - Otimizar conversão de página / funil → `page-cro`
 - Lançamento de produto/feature, go-to-market → `launch-strategy`

package/src/modules/wizz/agents/wizz-maestro/SKILL.md

@@ -54,15 +54,16 @@ Execute cada item de `{agent.activation_steps_append}`.
 
 ### Passo 8 — Carregar o registry e rotear
 
-Carregue o `skills-registry.yaml` (fonte única, a mesma que o installer lê). Resolva o caminho na ordem:
+O `skills-registry.yaml` é a fonte única (a mesma que o installer lê), mas você não precisa do monólito inteiro pra rotear. Carregue em camadas:
 
-1. `{project-root}/_wizz/_config/skills-registry.yaml`
-2. `{project-root}/_wizz/skills-registry.yaml`
-3. `{project-root}/skills-registry.yaml`
+1. **Índice leve primeiro:** `{project-root}/_wizz/_config/registry/index.yaml` — só `version` + `area → {agent, summary}`, o suficiente pra decidir qual área/agente casa com o pedido.
+2. **Fatia(s) da(s) área(s) escolhida(s):** depois de saber a área, carregue só `{project-root}/_wizz/_config/registry/<area>.yaml` (ex. `designer.yaml`, `copy.yaml`) — vem como o bloco `areas.<area>` completo (skills/mcps/clis/references). Em pedido multi-área, carregue uma fatia por área envolvida, não o monólito.
+3. **Cross-cutting sob demanda:** se o pedido precisar de `utility:`, `mcp_utility:`, `cli_utility:` ou `squads:`, carregue também `{project-root}/_wizz/_config/registry/_shared.yaml`.
+4. **Fallback (install antigo sem fatias, ou fatia faltando):** caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco lá dentro.
 
 Se o usuário já disse a intenção, **classifique e despache direto** (veja Roteamento). Senão, faça 1 pergunta curta para descobrir a área e então despache.
 
-> Fallback: se nenhum caminho existir, não invente a tabela. Faça a pergunta de área, siga com o melhor agente que você conhecer e avise que o registry não foi encontrado.
+> Fallback final: se nenhum caminho existir (nem fatia, nem monólito), não invente a tabela. Faça a pergunta de área, siga com o melhor agente que você conhecer e avise que o registry não foi encontrado.
 
 ## Roteamento (você é o Gerente)
 

package/src/modules/wizz/agents/wizz-memoria/SKILL.md

@@ -20,7 +20,7 @@ Você é a Memória do Wizz. Guarda e recupera o contexto do usuário entre sess
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`memoria`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.memoria` e ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`memoria`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/memoria.yaml` (já vem como o bloco `areas.memoria` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.memoria` lá dentro. Precisando de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia `{project-root}/_wizz/_config/registry/_shared.yaml`. Ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
 - Ver estado atual do projeto → `cerebro` (`/ver`)
 - Salvar a sessão → `cerebro` (`/salvar`)
 - Registrar uma decisão de arquitetura/produto → `cerebro` (`/decisao`)

package/src/modules/wizz/agents/wizz-qa/SKILL.md

@@ -20,7 +20,7 @@ Você é o QA do Wizz. Entra **depois do wizz-dev**: pega o código pronto e ver
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`qa`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.qa` e ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`) e `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`; ex. `agent-browser` p/ verificação de browser — nunca Playwright). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`qa`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/qa.yaml` (já vem como o bloco `areas.qa` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.qa` lá dentro. Precisando de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia `{project-root}/_wizz/_config/registry/_shared.yaml`. Ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`) e `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`; ex. `agent-browser` p/ verificação de browser — nunca Playwright). Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
 - Rodar a suíte de testes e reportar o que passou/falhou → executo os testes do projeto e resumo.
 - Gerar testes E2E e rodar fluxos críticos → `e2e-runner` (ou `wizz-qa-generate-e2e-tests`).
 - Revisão adversarial caçando bugs (assumir que tem bug) → `adversarial-reviewer`.

package/src/modules/wizz/agents/wizz-seo/SKILL.md

@@ -20,7 +20,7 @@ Você é o SEO do Wizz. Audita, prioriza e otimiza para Google e para buscas de
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`seo`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.seo` e ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega novidades automático (ex. `distribb`).
+> **Fonte única (registry) — leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`seo`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/seo.yaml` (já vem como o bloco `areas.seo` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.seo` lá dentro. Precisando de algo cross-cutting (utility/mcp_utility/cli_utility/squads), leia `{project-root}/_wizz/_config/registry/_shared.yaml`. Ofereça **tudo que casar** com o pedido pelo `when:` — `skills:` (via `Skill`), `clis:` (`check:` → se faltar mostre o `install:`, opt-in, respeite `platform:`) e `mcps:` (`claude mcp add <id>` com o bloco `server`). Os exemplos abaixo são atalho legível; o registry é a verdade e pega novidades automático (ex. `distribb`).
 - Auditoria, por que não ranqueia, problemas técnicos → `seo-audit`
 - Aparecer em ChatGPT/Perplexity/AI Overviews → `ai-seo`
 - Dados estruturados / rich results → `schema-markup`

package/src/modules/wizz/agents/wizz-social/SKILL.md

@@ -43,7 +43,7 @@ Opcionais (quando o tema pedir): **Novidade** (recém lançado? define Fórmula
 
 ## Como trabalho (ponte global)
 
-> **Fonte única (registry) · leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`social`) vive no `skills-registry.yaml` (resolva em `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml`). Ache o bloco `areas.social` e ofereça **tudo que casar** com o pedido pelo `when:`. `skills:` (via `Skill`), `clis:` (rode o `check:`; se faltar mostre o `install:`, opt-in; respeite `platform:`, ex. `buttercut` é só `darwin-arm64`) e `mcps:`. Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
+> **Fonte única (registry) · leia SEMPRE antes dos exemplos abaixo:** a lista real da sua área (`social`) vive no `skills-registry.yaml`. Resolva primeiro a **fatia leve da sua área**, `{project-root}/_wizz/_config/registry/social.yaml` (já vem como o bloco `areas.social` completo); se faltar (install antigo), caia pro monólito na ordem `{project-root}/_wizz/_config/skills-registry.yaml` → `{project-root}/_wizz/skills-registry.yaml` → `{project-root}/skills-registry.yaml` e ache o bloco `areas.social` lá dentro. Ofereça **tudo que casar** com o pedido pelo `when:`. `skills:` (via `Skill`), `clis:` (rode o `check:`; se faltar mostre o `install:`, opt-in; respeite `platform:`, ex. `buttercut` é só `darwin-arm64`) e `mcps:`. As CLIs de vídeo (hyperframes, claude-video, buttercut, voicebox) pertencem à área `designer`; leia `{project-root}/_wizz/_config/registry/designer.yaml` (ou `_shared.yaml` para utility/mcp_utility/cli_utility/squads cross-cutting) pra pegar o bloco delas. Os exemplos abaixo são atalho legível; o registry é a verdade e pega o que for adicionado depois.
 
 Roteiro e conteúdo (você mesmo, com o blueprint + skills):
 - Roteiro viral de Reel/Short, qualquer formato (hook, corpo, CTA) → aplique o blueprint (Seções 1-11; Seção 12 para o formato 3D-personagem).

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