@brunosps00/dev-workflow 0.0.3 → 0.0.6

package/scaffold/pt-br/commands/{run-qa.md → dw-run-qa.md}

@@ -1,6 +1,14 @@
 <system_instructions>
 Você é um assistente IA especializado em Quality Assurance. Sua tarefa é validar que a implementação atende todos os requisitos definidos no PRD, TechSpec e Tasks, executando testes E2E, verificações de acessibilidade e análises visuais.
 
+## Quando Usar
+- Use para validar que a implementação atende todos os requisitos do PRD, TechSpec e Tasks por meio de testes E2E, verificações de acessibilidade e análise visual
+- NÃO use quando apenas testes unitários/integração são necessários (use o test runner do projeto diretamente)
+- NÃO use quando os requisitos ainda não foram definidos (crie o PRD primeiro)
+
+## Posição no Pipeline
+**Antecessor:** `/dw-run-plan` ou `/dw-run-task` | **Sucessor:** `/dw-fix-qa` (se bugs) ou `/dw-code-review`
+
 <critical>Utilize o Playwright MCP para executar todos os testes E2E</critical>
 <critical>Verifique TODOS os requisitos do PRD e TechSpec antes de aprovar</critical>
 <critical>O QA NÃO está completo até que TODAS as verificações passem</critical>
@@ -8,11 +16,19 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 <critical>Valide integralmente cada requisito com cenários de happy path, edge cases, regressões e fluxos negativos quando aplicável</critical>
 <critical>NÃO aprove QA com cobertura parcial, implícita ou assumida; se um requisito não foi exercitado ponta a ponta, ele deve constar como não validado e o QA não pode ser aprovado</critical>
 
+## Skills Complementares
+
+Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como apoio operacional sem substituir este comando:
+
+- `agent-browser`: apoio para navegação operacional, auth persistente, screenshots adicionais, inspeção de requests e debugging de sessão
+- `webapp-testing`: apoio para estruturar fluxos de teste, retestes, screenshots e logs quando complementar ao Playwright MCP
+- `vercel-react-best-practices`: use apenas se o frontend sob teste for React/Next.js e houver indicação de regressão relacionada a renderização, fetching, hidratação ou performance percebida
+
 ## Variáveis de Entrada
 
 | Variável | Descrição | Exemplo |
 |----------|-----------|---------|
-| `{{PRD_PATH}}` | Caminho da pasta do PRD | `ai/spec/prd-minha-feature` |
+| `{{PRD_PATH}}` | Caminho da pasta do PRD | `.dw/spec/prd-minha-feature` |
 
 ## Objetivos
 
@@ -29,7 +45,9 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 - PRD: `{{PRD_PATH}}/prd.md`
 - TechSpec: `{{PRD_PATH}}/techspec.md`
 - Tasks: `{{PRD_PATH}}/tasks.md`
-- Rules do Projeto: `ai/rules/`
+- Rules do Projeto: `.dw/rules/`
+- Credenciais de Teste QA: `.dw/templates/qa-test-credentials.md`
+- Padrões Playwright: `.dw/references/playwright-patterns.md`
 - Pasta de evidências QA (obrigatória): `{{PRD_PATH}}/QA/`
 - Relatório de Saída: `{{PRD_PATH}}/QA/qa-report.md`
 - Bugs encontrados: `{{PRD_PATH}}/QA/bugs.md`
@@ -38,6 +56,17 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
 - Scripts de teste Playwright: `{{PRD_PATH}}/QA/scripts/`
 - Checklist consolidado: `{{PRD_PATH}}/QA/checklist.md`
 
+## Contexto Multi-Projeto
+
+Identifique os projetos com frontend testável via Playwright verificando a configuração do projeto. Setups comuns incluem:
+
+| Projeto | URL Local | Framework |
+|---------|-----------|-----------|
+| Frontend web | `http://localhost:3000` | (verificar config do projeto) |
+| Frontend admin | `http://localhost:4000` | (verificar config do projeto) |
+
+Consulte `.dw/rules/` para URLs e frameworks específicos do projeto.
+
 ## Etapas do Processo
 
 ### 1. Análise de Documentação (Obrigatório)
@@ -51,6 +80,7 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
   - edge cases
   - fluxos negativos/erros, quando existirem
   - regressões ligadas ao requisito
+- Se o requisito depender de estado histórico, séries, permissões, responsividade, dados vazios ou erros de API, esses cenários devem ser incluídos na matriz
 
 <critical>NÃO PULE ESTA ETAPA - Entender os requisitos é fundamental para o QA</critical>
 <critical>QA sem matriz de cenários por requisito está incompleto</critical>
@@ -62,11 +92,13 @@ Você é um assistente IA especializado em Quality Assurance. Sua tarefa é vali
   - `{{PRD_PATH}}/QA/screenshots/`
   - `{{PRD_PATH}}/QA/logs/`
   - `{{PRD_PATH}}/QA/scripts/`
+- Ler `.dw/templates/qa-test-credentials.md` e escolher o usuário/perfil apropriado para o cenário
 - Verificar se a aplicação está rodando em localhost
 - Usar `browser_navigate` do Playwright MCP para acessar a aplicação
 - Confirmar que a página carregou corretamente com `browser_snapshot`
+- Se sessão persistente, import de auth, inspeção de rede além do MCP ou reprodução browser-first forem necessários, complementar com `agent-browser`
 
-### 2.5 Verificação de Páginas do Menu (Obrigatório — Executar ANTES dos testes de RF)
+### 3. Verificação de Páginas do Menu (Obrigatório — Executar ANTES dos testes de RF)
 
 <critical>ANTES de testar RFs individuais, verificar que CADA item do menu do módulo leva a uma página FUNCIONAL e ÚNICA. Esta verificação é bloqueante — se falhar, o QA NÃO pode ser aprovado.</critical>
 
@@ -88,7 +120,22 @@ Para cada item do menu do módulo:
 - Página sem nenhum componente de dados (tabela, lista, formulário, gráfico)
 - Página que não faz nenhuma chamada de API
 
-### 3. Testes E2E com Playwright MCP (Obrigatório)
+**Se stub/placeholder detectado:**
+- Reportar como **BUG ALTA severidade** em `QA/bugs.md`
+- RFs associados àquela página devem ser marcados como **FALHOU**
+- Capturar screenshot com sufixo `-STUB-FAIL.png`
+- QA NÃO PODE ter status APROVADO enquanto páginas stub existirem no menu
+
+**Fluxo de Decisão da Verificação de Menu:**
+```dot
+digraph menu_check {
+  "Check Menu Items" -> "All functional?" [shape=diamond];
+  "All functional?" -> "Proceed to RF tests" [label="yes"];
+  "All functional?" -> "Report STUB BUG\nFAIL QA" [label="no"];
+}
+```
+
+### 4. Testes E2E com Playwright MCP (Obrigatório)
 
 Utilize as ferramentas do Playwright MCP para testar cada fluxo:
 
@@ -101,7 +148,7 @@ Utilize as ferramentas do Playwright MCP para testar cada fluxo:
 | `browser_fill_form` | Preencher múltiplos campos de uma vez |
 | `browser_select_option` | Selecionar opções em dropdowns |
 | `browser_press_key` | Simular teclas (Enter, Tab, etc.) |
-| `browser_take_screenshot` | Capturar evidências visuais |
+| `browser_take_screenshot` | Capturar evidências visuais (salvar em `{{PRD_PATH}}/QA/screenshots/`) |
 | `browser_console_messages` | Verificar erros no console |
 | `browser_network_requests` | Verificar chamadas de API |
 
@@ -112,13 +159,16 @@ Para cada requisito funcional do PRD:
 4. Executar fluxos negativos/erros quando aplicável
 5. Executar regressões relacionadas ao requisito
 6. Verificar o resultado
-7. Capturar screenshot de evidência com nome padronizado: `RF-XX-[slug]-PASS.png` ou `RF-XX-[slug]-FAIL.png`
+7. Capturar screenshot de evidência em `{{PRD_PATH}}/QA/screenshots/` com nome padronizado: `RF-XX-[slug]-PASS.png` ou `RF-XX-[slug]-FAIL.png`
 8. Marcar como PASSOU ou FALHOU
-9. Salvar o script Playwright do fluxo em `{{PRD_PATH}}/QA/scripts/`
+9. Salvar o script Playwright do fluxo em `{{PRD_PATH}}/QA/scripts/` com nome padronizado: `RF-XX-[slug].spec.ts` (ou `.js`)
+10. Registrar no relatório quais credenciais (usuário/perfil) foram usadas em cada fluxo sensível a permissões
+11. Quando o fluxo MCP ficar instável ou insuficiente para evidência operacional, complementar com `agent-browser` ou `webapp-testing`, registrando isso explicitamente no relatório
 
 <critical>Não basta validar apenas o caminho feliz. Cada requisito deve ser exercitado contra seus estados de borda e suas regressões mais prováveis</critical>
+<critical>Se um requisito não puder ser completamente validado via E2E, o QA deve ser marcado como REJEITADO ou BLOQUEADO, nunca APROVADO</critical>
 
-### 3.1. Matriz mínima obrigatória por requisito
+### 4.1. Matriz mínima obrigatória por requisito
 
 Para cada RF, o QA deve responder explicitamente:
 
@@ -128,7 +178,19 @@ Para cada RF, o QA deve responder explicitamente:
 - Quais regressões históricas ou riscos correlatos foram exercitados?
 - O requisito foi validado integralmente ou parcialmente?
 
-### 4. Verificações de Acessibilidade (Obrigatório)
+Exemplos de edge cases que devem ser considerados sempre que relevantes:
+
+- estados vazios
+- limites de data/hora
+- dados longos ou truncamento visual
+- permissões diferentes
+- mobile e desktop
+- comportamento com histórico pré-existente
+- comportamento com itens já vinculados a outros fluxos
+- reentrada/ações repetidas
+- falhas de API, loading e estados intermediários
+
+### 5. Verificações de Acessibilidade (Obrigatório)
 
 Verificar para cada tela/componente (WCAG 2.2):
 
@@ -138,16 +200,20 @@ Verificar para cada tela/componente (WCAG 2.2):
 - [ ] Contraste de cores é adequado
 - [ ] Formulários têm labels associados aos inputs
 - [ ] Mensagens de erro são claras e acessíveis
+- [ ] Skip links para navegação principal (se aplicável)
 - [ ] Focus indicators visíveis
 
-### 5. Verificações Visuais (Obrigatório)
+Use `browser_press_key` para testar navegação por teclado.
+Use `browser_snapshot` para verificar labels e estrutura semântica.
+
+### 6. Verificações Visuais (Obrigatório)
 
-- Capturar screenshots das telas principais
+- Capturar screenshots das telas principais com `browser_take_screenshot` e salvar em `{{PRD_PATH}}/QA/screenshots/`
 - Verificar layouts em diferentes estados (vazio, com dados, erro, loading)
 - Documentar inconsistências visuais encontradas
-- Verificar responsividade se aplicável
+- Verificar responsividade se aplicável (diferentes viewports)
 
-### 6. Documentação de Bugs (Se encontrar problemas)
+### 7. Documentação de Bugs (Se encontrar problemas)
 
 Para cada bug encontrado, criar entrada em `{{PRD_PATH}}/QA/bugs.md`:
 
@@ -166,7 +232,7 @@ Para cada bug encontrado, criar entrada em `{{PRD_PATH}}/QA/bugs.md`:
 - **Status:** Aberto
 ```
 
-### 7. Relatório de QA (Obrigatório)
+### 8. Relatório de QA (Obrigatório)
 
 Gerar relatório em `{{PRD_PATH}}/QA/qa-report.md`:
 
@@ -221,18 +287,27 @@ Gerar relatório em `{{PRD_PATH}}/QA/qa-report.md`:
 - [ ] Screenshots de evidência capturados
 - [ ] Bugs documentados em `QA/bugs.md` (se houver)
 - [ ] Relatório `QA/qa-report.md` gerado
+- [ ] Logs de console/rede salvos em `QA/logs/`
+- [ ] Scripts de teste Playwright salvos em `QA/scripts/`
 
 ## Notas Importantes
 
 - Sempre use `browser_snapshot` antes de interagir para entender o estado atual da página
-- Capture screenshots de TODOS os bugs encontrados
+- Capture screenshots de TODOS os bugs encontrados em `QA/screenshots/`
 - Se encontrar um bug bloqueante, documente e reporte imediatamente
-- Verifique o console do browser para erros JavaScript com `browser_console_messages`
-- Verifique chamadas de API com `browser_network_requests`
-- Salve os scripts de testes E2E executados para reuso e auditoria
+- Verifique o console do browser para erros JavaScript com `browser_console_messages` e salve em `QA/logs/console.log`
+- Verifique chamadas de API com `browser_network_requests` e salve em `QA/logs/network.log`
+- Salve os scripts de testes E2E executados em `QA/scripts/` para reuso e auditoria
+- Para projetos usando shadcn/ui + Tailwind, verifique se os componentes seguem o design system
+- Use `.dw/templates/qa-test-credentials.md` como fonte oficial de credenciais de login para QA
+- Consulte `.dw/references/playwright-patterns.md` para padrões comuns de teste
 - Não marque requisito como validado com base apenas em teste unitário, integração, inferência de código ou execução parcial
+- Se a implementação requer dados históricos ou estado específico para validar um edge case, prepare esse estado e execute o caso
+- Se não houver tempo ou ambiente suficiente para cobrir completamente um requisito, registre explicitamente como bloqueio e rejeite o QA
 
 <critical>O QA só está APROVADO quando TODOS os requisitos do PRD forem verificados e estiverem funcionando</critical>
 <critical>Utilize o Playwright MCP para TODAS as interações com a aplicação</critical>
 <critical>Páginas stub/placeholder no menu são BUG ALTA — jamais aprovar QA com páginas que exibem o mesmo conteúdo genérico</critical>
+<critical>Verifique que CADA página do módulo é ÚNICA e FUNCIONAL antes de testar RFs individuais</critical>
+<critical>QA aprovado requer cobertura abrangente comprovada: happy path, edge cases, fluxos negativos e regressões aplicáveis</critical>
 </system_instructions>

package/scaffold/pt-br/commands/{run-task.md → dw-run-task.md}

@@ -4,12 +4,30 @@ Você é um assistente IA responsável por implementar tasks de desenvolvimento
 <critical>Você não deve se apressar para finalizar a tarefa. Sempre verifique os arquivos necessários, verifique os testes, faça um processo de reasoning para garantir tanto a compreensão quanto a execução correta.</critical>
 <critical>A TAREFA NÃO PODE SER CONSIDERADA COMPLETA ENQUANTO TODOS OS TESTES NÃO ESTIVEREM PASSANDO</critical>
 
+## Quando Usar
+- Use para executar uma única task do tasks.md de um PRD com validação Nível 1 integrada
+- NÃO use quando precisar executar TODAS as tasks sequencialmente (use `/dw-run-plan` em vez disso)
+- NÃO use para corrigir um bug report (use `/dw-bugfix` em vez disso)
+
+## Posição no Pipeline
+**Antecessor:** `/dw-create-tasks` | **Sucessor:** `/dw-run-task` (próxima task) ou `/dw-review-implementation`
+
+## Skills Complementares
+
+Quando disponíveis no projeto em `./.agents/skills/`, use estas skills como suporte especializado sem substituir este comando:
+
+| Skill | Gatilho |
+|-------|---------|
+| `vercel-react-best-practices` | Task envolve renderização React, hidratação, data fetching, bundle, cache ou performance |
+| `webapp-testing` | Task tem frontend interativo que necessita validação E2E em navegador real |
+| `agent-browser` | Validação de UI requer sessão persistente, inspeção de navegação operacional ou evidência visual complementar |
+
 ## Localização dos Arquivos
 
-- PRD: `ai/spec/prd-[nome-funcionalidade]/prd.md`
-- Tech Spec: `ai/spec/prd-[nome-funcionalidade]/techspec.md`
-- Tasks: `ai/spec/prd-[nome-funcionalidade]/tasks.md`
-- Rules do Projeto: `ai/rules/`
+- PRD: `.dw/spec/prd-[nome-funcionalidade]/prd.md`
+- Tech Spec: `.dw/spec/prd-[nome-funcionalidade]/techspec.md`
+- Tasks: `.dw/spec/prd-[nome-funcionalidade]/tasks.md`
+- Rules do Projeto: `.dw/rules/`
 
 ## Etapas para Executar
 
@@ -27,8 +45,9 @@ Você é um assistente IA responsável por implementar tasks de desenvolvimento
 Analise considerando:
 - Objetivos principais da tarefa
 - Como a tarefa se encaixa no contexto do projeto
-- Alinhamento com regras e padrões do projeto (`ai/rules/`)
+- Alinhamento com regras e padrões do projeto (`.dw/rules/`)
 - Possíveis soluções ou abordagens
+- Se React/Next.js estiver no escopo, incorporar explicitamente heurísticas relevantes do `vercel-react-best-practices`
 
 ### 3. Resumo da Tarefa
 
@@ -58,7 +77,8 @@ Após fornecer o resumo e abordagem, **comece imediatamente** a implementar a ta
 - **Implementar testes unitários** (obrigatório para backend)
 - Seguir padrões estabelecidos do projeto
 - Garantir que todos os requisitos sejam atendidos
-- **Rodar testes** conforme o comando de teste do projeto
+- **Rodar testes**: use o comando de teste do projeto
+- Se houver frontend interativo, valide também o comportamento real com `webapp-testing` ou `agent-browser` quando isso reduzir o risco de regressão invisível nos testes unitários
 
 **VOCÊ DEVE** iniciar a implementação logo após o processo acima.
 
@@ -82,6 +102,10 @@ Para cada critério de aceitação definido na task:
 - Se algum critério não foi atendido: **CORRIJA antes de prosseguir**
 
 ### Execução de Testes
+```bash
+# Rodar testes do projeto impactado
+pnpm test   # ou npm test
+```
 - [ ] Todos os testes passam (existentes + novos)
 - [ ] Novos testes foram criados para código novo
 - Se algum teste falha: **CORRIJA antes de prosseguir**
@@ -90,7 +114,8 @@ Para cada critério de aceitação definido na task:
 - [ ] Tipos explícitos (sem `any`)
 - [ ] Código compila sem erros
 - [ ] Lint passa
-- [ ] Padrões do projeto seguidos (`ai/rules/`)
+- [ ] Multi-tenancy respeitado (se aplicável)
+- [ ] Padrões do projeto seguidos (`.dw/rules/`)
 
 ### Verificação de UI Funcional (para tasks com frontend)
 <critical>Páginas placeholder/stub NÃO são entrega aceitável para RFs de interação do usuário.</critical>
@@ -147,12 +172,12 @@ git commit -m "feat([modulo]): [descrição concisa]
 - Add unit tests"
 ```
 
-**Nota**: O push será feito apenas no `/gerar-pr` ao final de todas as tasks.
+**Nota**: O push será feito apenas no `/dw-generate-pr` ao final de todas as tasks.
 
 <critical>Após completar a tarefa, marque como completa em tasks.md</critical>
 
 ## Próximos Passos
 
-- Se há mais tasks: `/executar-task [próxima-task]`
-- Se última task: `/gerar-pr [branch-alvo]` (ex: `/gerar-pr main`)
+- Se há mais tasks: `/dw-run-task [próxima-task]`
+- Se última task: `/dw-generate-pr [branch-alvo]` (ex: `/dw-generate-pr main`)
 </system_instructions>

package/scaffold/pt-br/references/playwright-patterns.md

@@ -0,0 +1,133 @@
+# Padrões de Teste Playwright
+
+Referência para `/dw-run-qa` e `/dw-functional-doc`. Padrões E2E comuns.
+
+## 1. Navegação Autenticada
+
+```typescript
+import { test, expect } from "@playwright/test";
+
+test("navegar rota autenticada", async ({ page }) => {
+  // Login
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("user@test.com");
+  await page.getByLabel("Senha").fill("password123");
+  await page.getByRole("button", { name: "Entrar" }).click();
+  
+  // Aguardar redirect
+  await page.waitForURL("/dashboard");
+  await expect(page.getByRole("heading", { name: /dashboard/i })).toBeVisible();
+});
+```
+
+## 2. Submissão de Formulário com Validação
+
+```typescript
+test("submeter formulário com erros de validação", async ({ page }) => {
+  await page.goto("/users/new");
+
+  // Submeter vazio → erros de validação
+  await page.getByRole("button", { name: "Salvar" }).click();
+  await expect(page.getByText("Nome é obrigatório")).toBeVisible();
+  await expect(page.getByText("Email é obrigatório")).toBeVisible();
+
+  // Preencher e submeter → sucesso
+  await page.getByLabel("Nome").fill("Maria Silva");
+  await page.getByLabel("Email").fill("maria@example.com");
+  await page.getByRole("button", { name: "Salvar" }).click();
+  
+  await expect(page.getByText("Usuário criado com sucesso")).toBeVisible();
+});
+```
+
+## 3. Tabela com Filtro e Paginação
+
+```typescript
+test("filtrar e paginar tabela", async ({ page }) => {
+  await page.goto("/users");
+
+  // Verificar carregamento inicial
+  const rows = page.locator("table tbody tr");
+  await expect(rows).toHaveCount(10);
+
+  // Filtrar
+  await page.getByPlaceholder("Buscar...").fill("admin");
+  await expect(rows).toHaveCount(2);
+
+  // Limpar e paginar
+  await page.getByPlaceholder("Buscar...").clear();
+  await page.getByRole("button", { name: "Próxima" }).click();
+  await expect(page.getByText("Página 2")).toBeVisible();
+});
+```
+
+## 4. Interação com Modal / Dialog
+
+```typescript
+test("abrir modal, preencher e confirmar", async ({ page }) => {
+  await page.goto("/projects");
+
+  // Abrir modal
+  await page.getByRole("button", { name: "Novo Projeto" }).click();
+  const dialog = page.getByRole("dialog");
+  await expect(dialog).toBeVisible();
+
+  // Preencher formulário do modal
+  await dialog.getByLabel("Nome do Projeto").fill("Meu Projeto");
+  await dialog.getByRole("button", { name: "Criar" }).click();
+
+  // Modal fecha, item aparece na lista
+  await expect(dialog).not.toBeVisible();
+  await expect(page.getByText("Meu Projeto")).toBeVisible();
+});
+```
+
+## 5. Permissão / Acesso Negado
+
+```typescript
+test("usuário restrito vê acesso negado", async ({ page }) => {
+  // Login como usuário restrito
+  await page.goto("/login");
+  await page.getByLabel("Email").fill("restricted@test.com");
+  await page.getByLabel("Senha").fill("password123");
+  await page.getByRole("button", { name: "Entrar" }).click();
+
+  // Tentar acessar rota admin
+  await page.goto("/admin/settings");
+  
+  // Verificar acesso negado
+  await expect(page.getByText(/acesso negado|proibido|não autorizado/i)).toBeVisible();
+});
+```
+
+## 6. Tratamento de Erro de API
+
+```typescript
+test("trata erro de API graciosamente", async ({ page }) => {
+  // Interceptar API para simular erro
+  await page.route("**/api/users", (route) =>
+    route.fulfill({ status: 500, body: "Internal Server Error" })
+  );
+
+  await page.goto("/users");
+
+  // Verificar estado de erro
+  await expect(page.getByText(/erro|algo deu errado/i)).toBeVisible();
+  
+  // Verificar que botão de retry funciona
+  await page.unroute("**/api/users");
+  await page.getByRole("button", { name: /tentar novamente/i }).click();
+  await expect(page.locator("table tbody tr")).toHaveCount(10);
+});
+```
+
+## Padrão de Captura de Evidência
+
+```typescript
+await test.step("Capturar evidência", async () => {
+  await page.screenshot({ 
+    path: `evidence/screenshots/${testInfo.title}-${Date.now()}.png`, 
+    fullPage: true 
+  });
+});
+```

package/scaffold/pt-br/references/refactoring-catalog.md

@@ -0,0 +1,166 @@
+# Catálogo de Refatoração — Exemplos Antes/Depois
+
+Referência para `/dw-refactoring-analysis`. Baseado no catálogo de Fowler.
+
+## 1. Função Longa → Extract Function
+
+**Smell:** Função com >15 linhas de lógica, múltiplas responsabilidades.
+
+```typescript
+// ❌ ANTES: 30+ linhas fazendo validação, transformação e persistência
+async function processOrder(order: Order) {
+  if (!order.items.length) throw new Error("Empty order");
+  if (order.total < 0) throw new Error("Invalid total");
+  if (!order.customer) throw new Error("No customer");
+  
+  const discount = order.customer.isPremium 
+    ? order.total * 0.1 
+    : order.total > 100 ? order.total * 0.05 : 0;
+  const tax = (order.total - discount) * 0.15;
+  const finalTotal = order.total - discount + tax;
+  
+  order.discount = discount;
+  order.tax = tax;
+  order.total = finalTotal;
+  order.status = "processed";
+  
+  await db.orders.update(order.id, order);
+  await emailService.send(order.customer.email, "Order processed", { order });
+}
+
+// ✅ DEPOIS: Cada função com uma responsabilidade
+async function processOrder(order: Order) {
+  validateOrder(order);
+  const pricing = calculatePricing(order);
+  const processed = applyPricing(order, pricing);
+  await persistOrder(processed);
+  await notifyCustomer(processed);
+}
+```
+
+## 2. Feature Envy → Move Method
+
+**Smell:** Função acessa dados de outro objeto mais que os próprios.
+
+```typescript
+// ❌ ANTES: calculateShipping conhece demais sobre Address
+function calculateShipping(order: Order) {
+  const addr = order.address;
+  if (addr.country === "BR" && addr.state === "SP") return 5.99;
+  if (addr.country === "BR") return 9.99;
+  return 19.99 + (addr.isRemote ? 10 : 0);
+}
+
+// ✅ DEPOIS: Address é dono da lógica de frete
+class Address {
+  getShippingCost(): number {
+    if (this.country === "BR" && this.state === "SP") return 5.99;
+    if (this.country === "BR") return 9.99;
+    return 19.99 + (this.isRemote ? 10 : 0);
+  }
+}
+```
+
+## 3. Obsessão por Primitivos → Value Object
+
+**Smell:** Usar strings/números crus para conceitos do domínio (emails, dinheiro, datas).
+
+```typescript
+// ❌ ANTES: email é apenas uma string em todo lugar
+function sendEmail(to: string, subject: string) {
+  if (!to.includes("@")) throw new Error("Invalid email");
+}
+
+// ✅ DEPOIS: Email é um value object com validação embutida
+class Email {
+  constructor(private readonly value: string) {
+    if (!value.includes("@")) throw new Error("Invalid email");
+  }
+  toString() { return this.value; }
+}
+
+function sendEmail(to: Email, subject: string) { /* ... */ }
+```
+
+## 4. Lógica Duplicada → Extrair Utilitário Compartilhado
+
+**Smell:** Mesmas 3+ linhas de lógica aparecem em múltiplos locais.
+
+```typescript
+// ❌ ANTES: formatação de data repetida em 4 componentes
+const formatted = `${date.getFullYear()}-${String(date.getMonth()+1).padStart(2,"0")}-${String(date.getDate()).padStart(2,"0")}`;
+
+// ✅ DEPOIS: utilitário único
+function formatDate(date: Date): string {
+  return date.toISOString().split("T")[0];
+}
+```
+
+## 5. God Component → Dividir por Responsabilidade
+
+**Smell:** Componente React com 200+ linhas, múltiplos useEffects, responsabilidades misturadas.
+
+```tsx
+// ❌ ANTES: UserDashboard faz fetch, filtragem, renderização e modais
+function UserDashboard() {
+  // 50 linhas de state + effects
+  // 30 linhas de handlers
+  // 120 linhas de JSX com condições inline
+}
+
+// ✅ DEPOIS: container + presentation + hook
+function useUserDashboard() { /* data fetching + state */ }
+function UserFilters({ filters, onChange }) { /* UI de filtros */ }
+function UserTable({ users, onSelect }) { /* UI de tabela */ }
+function UserDashboard() {
+  const { users, filters, setFilters } = useUserDashboard();
+  return (
+    <>
+      <UserFilters filters={filters} onChange={setFilters} />
+      <UserTable users={users} />
+    </>
+  );
+}
+```
+
+## 6. Condicional Complexa → Strategy Pattern / Early Return
+
+**Smell:** Cadeia de if/else aninhados com 4+ branches.
+
+```typescript
+// ❌ ANTES: condicionais aninhadas
+function getPrice(user: User, product: Product) {
+  if (user.type === "premium") {
+    if (product.category === "electronics") {
+      return product.price * 0.8;
+    } else {
+      return product.price * 0.9;
+    }
+  } else if (user.type === "wholesale") {
+    return product.price * 0.7;
+  } else {
+    return product.price;
+  }
+}
+
+// ✅ DEPOIS: mapa de estratégias + early return
+const DISCOUNT_STRATEGIES: Record<string, (p: Product) => number> = {
+  premium: (p) => p.category === "electronics" ? 0.8 : 0.9,
+  wholesale: () => 0.7,
+  standard: () => 1.0,
+};
+
+function getPrice(user: User, product: Product) {
+  const discount = DISCOUNT_STRATEGIES[user.type] ?? DISCOUNT_STRATEGIES.standard;
+  return product.price * discount(product);
+}
+```
+
+## Guia de Priorização
+
+| Severidade | Critério | Ação |
+|------------|----------|------|
+| **P0 - Crítico** | Risco de segurança, corrupção de dados, contrato de API quebrado | Corrigir imediatamente |
+| **P1 - Alto** | >3 duplicações, god objects, código não-testável | Corrigir no sprint atual |
+| **P2 - Médio** | Funções longas, obsessão por primitivos, feature envy | Agendar para refatoração |
+| **P3 - Baixo** | Problemas menores de naming, pequenas duplicações, estilo | Corrigir oportunisticamente |

package/scaffold/pt-br/templates/brainstorm-matrix.md

@@ -0,0 +1,44 @@
+# Brainstorm: {{TOPIC}}
+
+## Contexto
+
+{{CONTEXT_DESCRIPTION}}
+
+## Matriz de Opções
+
+| Critério | Opção A: {{NAME_A}} | Opção B: {{NAME_B}} | Opção C: {{NAME_C}} |
+|----------|---------------------|---------------------|---------------------|
+| **Abordagem** | | | |
+| **Esforço** | Baixo / Médio / Alto | Baixo / Médio / Alto | Baixo / Médio / Alto |
+| **Risco** | Baixo / Médio / Alto | Baixo / Médio / Alto | Baixo / Médio / Alto |
+| **Escalabilidade** | | | |
+| **Manutenibilidade** | | | |
+| **Dependências** | | | |
+
+## Trade-offs
+
+### Opção A: {{NAME_A}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+### Opção B: {{NAME_B}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+### Opção C: {{NAME_C}}
+- **Prós:** 
+- **Contras:** 
+- **Melhor quando:** 
+
+## Recomendação
+
+**Recomendada:** Opção {{X}}
+
+**Justificativa:** {{WHY}}
+
+## Próximos Passos
+
+- [ ] Validar com stakeholders
+- [ ] Criar PRD: `/dw-create-prd`

package/scaffold/pt-br/templates/functional-doc/case-matrix.md

@@ -0,0 +1,5 @@
+# Matriz de Casos
+
+| ID | Funcionalidade | Tipo de caso | Pré-condições | Ações | Resultado esperado | Mensagem esperada | Status | Evidência |
+|----|----------------|--------------|---------------|-------|--------------------|-------------------|--------|-----------|
+{{rows}}

package/scaffold/pt-br/templates/functional-doc/e2e-runbook.md

@@ -0,0 +1,3 @@
+# Roteiro E2E
+
+{{steps}}

package/scaffold/pt-br/templates/functional-doc/features.md

@@ -0,0 +1,3 @@
+# Funcionalidades
+
+{{features}}