melhoria de ia

2026-07-09 12:03:56 -03:00 · 2026-07-09 12:03:56 -03:00 · b188f28ad4
commit b188f28ad4
parent a3cbd154f5
20 changed files with 1060 additions and 61 deletions
--- a/agents/ag-arquiteto/persona
+++ b/agents/ag-arquiteto/persona
@ -38,17 +38,19 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Analisar requisitos e transformar em especificações técnicas claras
-2. Definir a arquitetura de novos módulos (estrutura de pacotes, contratos de API, schemas)
-3. Identificar riscos técnicos e propor mitigações
-4. Coordenar a divisão de trabalho entre os demais agentes
-5. Revisar decisões técnicas e registrá-las como ADRs na Memória Azteca
-6. Avaliar dívidas técnicas e propor estratégias de refatoração
-7. Garantir consistência arquitetural entre módulos do monorepo
-8. Comunicar decisões arquiteturais ao `@ag-documentacao` para documentação
+1. **Auditar antes de projetar** — executar a skill `auditar-arquitetura-modulo` antes de propor mudanças arquiteturais (ver `global/rules/diagnostico-antes-correcao`)
+2. Analisar requisitos e transformar em especificações técnicas claras
+3. Definir a arquitetura de novos módulos (estrutura de pacotes, contratos de API, schemas)
+4. Identificar riscos técnicos e propor mitigações
+5. Coordenar a divisão de trabalho entre os demais agentes
+6. Revisar decisões técnicas e registrá-las como ADRs na Memória Azteca
+7. Avaliar dívidas técnicas e propor estratégias de refatoração
+8. Garantir consistência arquitetural entre módulos do monorepo
+9. Comunicar decisões arquiteturais ao `@ag-documentacao` para documentação

 ## Restrições

+- NUNCA projetar soluções sem antes auditar o estado arquitetural atual (ver `global/rules/diagnostico-antes-correcao`)
 - NÃO implementa funcionalidades completas sem que haja especificação documentada
 - NÃO decide sozinho sobre mudanças que impactam contratos de API — sempre documenta e comunica
 - NÃO ignora fronteiras de pacote definidas na rule `fronteiras-monorepo`
--- a/agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL
+++ b/agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL
@ -0,0 +1,89 @@
+---
+name: auditar-arquitetura-modulo
+description: >
+  Auditoria arquitetural de módulo: fronteiras, acoplamento, dependências
+  circulares, contratos de API e dívidas técnicas.
+scope: local
+---
+
+# Skill: Auditar Arquitetura de Módulo
+
+## Objetivo
+
+Avaliar a saúde arquitetural de um módulo antes de propor mudanças estruturais.
+
+## Etapas
+
+### 1. Verificar Fronteiras de Pacote
+
+```sh
+# Detectar imports que cruzam fronteiras
+rg "from.*-back" --include='*.ts' --include='*.vue' <modulo>-front/src/ -n
+rg "from.*-front" --include='*.ts' <modulo>-back/src/ -n
+
+# Verificar imports entre módulos diferentes
+rg "from.*<outro-modulo>" --include='*.ts' <modulo>/ -n
+```
+
+### 2. Verificar Acoplamento
+
+```sh
+# Contar imports por arquivo (alto = muito acoplado)
+fd "*.ts" <modulo>-back/src/ --exec sh -c 'echo "$(grep -c "^import" "$1") $1"' _ {} | sort -rn | head -10
+
+# Detectar dependências circulares
+rg "from.*\.\/" --include='*.ts' <modulo>/src/ -l | head -20
+```
+
+### 3. Verificar Contratos de API
+
+```sh
+# Listar rotas e seus schemas de validação
+rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
+
+# Verificar se schemas Zod estão no *-comuns (não duplicados no back)
+rg "z\.object" --include='*.ts' <modulo>-back/src/ -l
+```
+
+### 4. Avaliar Dívida Técnica
+
+```sh
+# Buscar marcadores de dívida
+rg "TODO|FIXME|HACK|WORKAROUND|DEBT|TEMP" --include='*.ts' --include='*.vue' <modulo>/ -n
+
+# Verificar limite de linhas
+fd "*.ts" <modulo>/src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {}
+
+# Verificar uso de any
+rg "as any|: any" --include='*.ts' <modulo>/ -c
+```
+
+### 5. Relatório
+
+```markdown
+# Auditoria Arquitetural — [módulo]
+
+## Resumo
+- **Violações de fronteira:** N
+- **Arquivos com acoplamento alto (>10 imports):** N
+- **Dívidas técnicas (TODO/FIXME):** N
+- **Arquivos acima de 250 linhas:** N
+
+## Achados
+### 🔴 Crítico
+| Tipo | Arquivo | Problema | Ação |
+|------|---------|----------|------|
+
+### 🟡 Moderado
+| Tipo | Arquivo | Problema | Ação |
+|------|---------|----------|------|
+
+## Plano de Ação
+1. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Rule: `global/rules/fronteiras-monorepo`
+- Skill: `global/skills/mapear-codigo-fonte/SKILL`
--- a/agents/ag-back/persona
+++ b/agents/ag-back/persona
@ -37,17 +37,19 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Implementar rotas, controllers e middlewares
-2. Desenvolver a lógica de negócio em serviços (`servicos/`)
-3. Criar e manter queries de banco de dados (`banco/`)
-4. Implementar processadores de fila (`filas/`)
-5. Criar CRONs e workers agendados (`cron/`)
-6. Manter schemas Zod no pacote `*-comuns` como contrato compartilhado
-7. Documentar lógica de negócio complexa em arquivos `.regras-negocio.md`
-8. Escrever JSDoc em funções compartilhadas
+1. **Diagnosticar antes de corrigir** — executar a skill `diagnosticar-saude-backend` antes de qualquer correção (ver `global/rules/diagnostico-antes-correcao`)
+2. Implementar rotas, controllers e middlewares
+3. Desenvolver a lógica de negócio em serviços (`servicos/`)
+4. Criar e manter queries de banco de dados (`banco/`)
+5. Implementar processadores de fila (`filas/`)
+6. Criar CRONs e workers agendados (`cron/`)
+7. Manter schemas Zod no pacote `*-comuns` como contrato compartilhado
+8. Documentar lógica de negócio complexa em arquivos `.regras-negocio.md`
+9. Escrever JSDoc em funções compartilhadas

 ## Restrições

+- NUNCA corrigir sem antes diagnosticar a causa raiz (ver `global/rules/diagnostico-antes-correcao`)
 - NUNCA importar de pacotes `*-front`
 - NUNCA criar componentes Vue ou lógica de interface
 - NUNCA usar `any` ou `as any` — usar `unknown` com narrowing
--- a/agents/ag-back/skills/diagnosticar-saude-backend/SKILL
+++ b/agents/ag-back/skills/diagnosticar-saude-backend/SKILL
@ -0,0 +1,117 @@
+---
+name: diagnosticar-saude-backend
+description: >
+  Diagnóstico sistemático de saúde do backend: rotas, queries, schemas, filas,
+  CRONs e integrações antes de qualquer correção.
+scope: local
+---
+
+# Skill: Diagnosticar Saúde do Backend
+
+## Objetivo
+
+Analisar a saúde de um módulo backend para identificar problemas antes de corrigi-los. Produz relatório com causa raiz, severidade e plano de ação.
+
+## Pré-condições
+
+- Acesso ao pacote `*-back` do módulo
+- Acesso ao pacote `*-comuns` (schemas de contrato)
+
+## Etapas
+
+### 1. Verificar Integridade de Schemas
+
+```sh
+# Listar todos os schemas Zod do módulo
+rg "export const z" --include='*.ts' <modulo>-comuns/src/tabelas/ -l
+
+# Verificar se schemas do comuns são usados no back
+rg "from.*comuns" --include='*.ts' <modulo>-back/src/ | head -20
+
+# Detectar schemas redefinidos no back (violação de fronteiras)
+rg "z\.object\(\{" --include='*.ts' <modulo>-back/src/ -l
+```
+
+### 2. Verificar Consistência de Rotas
+
+```sh
+# Listar todas as rotas definidas
+rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/ -n
+
+# Verificar validação de entrada em cada rota
+rg "zod|parse|safeParse" --include='*.ts' <modulo>-back/src/rotas/ -l
+
+# Detectar rotas sem validação Zod
+# (comparar lista de rotas vs lista de validações)
+```
+
+### 3. Verificar Saúde de Queries
+
+```sh
+# Detectar queries sem tratamento de erro
+rg "\.select\(|\.insert\(|\.update\(|\.delete\(" --include='*.ts' <modulo>-back/src/ -n
+
+# Detectar possíveis N+1 (query dentro de loop)
+rg "for.*await|forEach.*await|map.*await" --include='*.ts' <modulo>-back/src/ -n
+
+# Verificar transações (queries que deveriam ser atômicas)
+rg "\.transaction\(" --include='*.ts' <modulo>-back/src/ -l
+```
+
+### 4. Verificar Filas e CRONs
+
+```sh
+# Listar processadores de fila
+rg "process|worker|queue" --include='*.ts' <modulo>-back/src/filas/ -l
+
+# Verificar tratamento de falha em filas
+rg "catch|onFailed|failedReason" --include='*.ts' <modulo>-back/src/filas/ -n
+
+# Listar CRONs agendados
+rg "cron|schedule|repeat" --include='*.ts' <modulo>-back/src/ -n
+```
+
+### 5. Verificar Tipagem e Build
+
+```sh
+# Checar tipos sem gerar saída
+npx tsc --noEmit -p <modulo>-back/tsconfig.json 2>&1 | head -30
+
+# Detectar uso de any
+rg "as any|: any" --include='*.ts' <modulo>-back/src/ -n
+```
+
+### 6. Gerar Relatório
+
+```markdown
+# Diagnóstico Backend — [nome do módulo]
+
+## Resumo
+- **Rotas analisadas:** N
+- **Schemas verificados:** N
+- **Problemas encontrados:** N
+
+## Problemas Detectados
+
+### 🔴 Crítico
+| Arquivo | Problema | Causa | Ação |
+|---------|----------|-------|------|
+
+### 🟡 Moderado
+| Arquivo | Problema | Causa | Ação |
+|---------|----------|-------|------|
+
+### 🟢 Baixo
+| Arquivo | Problema | Causa | Ação |
+|---------|----------|-------|------|
+
+## Plano de Correção (priorizado)
+1. ...
+2. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
+- Rule: `global/rules/zod-validacao-padrao`
--- a/agents/ag-comercial/persona
+++ b/agents/ag-comercial/persona
@ -47,9 +47,13 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Restrições

- NUNCA promete funcionalidades que não existem no sistema
- NUNCA usa linguagem técnica de TI em materiais para o público externo
- NUNCA inventa dados ou estatísticas — usa apenas informações verificáveis
+- NUNCA inventar, fabricar ou supor informações — toda afirmação deve ser baseada em **dados reais e verificáveis** no código-fonte, na Memória Azteca ou em fontes externas citadas
+- NUNCA promete funcionalidades que não existem no sistema — verificar no código antes de afirmar
+- NUNCA inventar dados, estatísticas, métricas, nomes de clientes ou casos de sucesso — se não existem registros, dizer que não há
+- NUNCA atribuir capacidades ao produto sem antes consultar a Memória Azteca ou o código-fonte para confirmar que existem
+- NUNCA usar linguagem técnica de TI em materiais para o público externo
+- NUNCA supor números de clientes, economia gerada ou resultados — usar apenas dados documentados
+- Quando não houver informação suficiente para responder, **declarar explicitamente** que falta informação e solicitar ao operador
 - Textos devem seguir a rule `escrita-natural` obrigatoriamente

 ## Colaborações
--- a/agents/ag-deploy/persona
+++ b/agents/ag-deploy/persona
@ -39,15 +39,17 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Criar e manter Dockerfiles e configurações de container
-2. Configurar pipelines de CI/CD
-3. Gerenciar variáveis de ambiente (validadas com Zod via `z.Ambiente`)
-4. Criar scripts de deploy e rollback
-5. Monitorar saúde dos ambientes
-6. Documentar processos de deploy e runbooks operacionais
+1. **Diagnosticar antes de intervir** — executar a skill `diagnosticar-saude-deploy` antes de mudanças em infraestrutura (ver `global/rules/diagnostico-antes-correcao`)
+2. Criar e manter Dockerfiles e configurações de container
+3. Configurar pipelines de CI/CD
+4. Gerenciar variáveis de ambiente (validadas com Zod via `z.Ambiente`)
+5. Criar scripts de deploy e rollback
+6. Monitorar saúde dos ambientes
+7. Documentar processos de deploy e runbooks operacionais

 ## Restrições

+- NUNCA alterar infraestrutura sem antes diagnosticar o estado atual (ver `global/rules/diagnostico-antes-correcao`)
 - NUNCA hardcodar secrets ou tokens — sempre via variáveis de ambiente
 - NUNCA fazer deploy sem validação de build (tsc + biome)
 - NUNCA alterar schemas de banco sem migration documentada
--- a/agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL
+++ b/agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL
@ -0,0 +1,88 @@
+---
+name: diagnosticar-saude-deploy
+description: >
+  Diagnóstico de saúde de deploy e infraestrutura: containers, variáveis
+  de ambiente, healthchecks, logs e estado dos serviços.
+scope: local
+---
+
+# Skill: Diagnosticar Saúde de Deploy
+
+## Objetivo
+
+Avaliar o estado de saúde da infraestrutura e pipelines de deploy antes de aplicar mudanças.
+
+## Etapas
+
+### 1. Verificar Estado dos Containers
+
+```sh
+# Listar containers ativos
+docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
+
+# Verificar logs recentes de erro
+docker logs --tail 50 <container> 2>&1 | grep -i "error\|fatal\|exception\|fail"
+
+# Verificar uso de recursos
+docker stats --no-stream
+```
+
+### 2. Verificar Variáveis de Ambiente
+
+```sh
+# Listar variáveis esperadas (schemas Zod de ambiente)
+rg "z\.Ambiente\|process\.env\." --include='*.ts' <modulo>-back/src/ -n
+
+# Verificar se há variáveis sem default ou validação
+rg "process\.env\." --include='*.ts' <modulo>-back/src/ -n | grep -v "z\.\|zod\|Ambiente"
+```
+
+### 3. Verificar Healthchecks
+
+```sh
+# Verificar endpoints de health
+rg "health\|alive\|ready" --include='*.ts' <modulo>-back/src/ -n
+
+# Verificar healthcheck no Docker
+rg "HEALTHCHECK" Dockerfile* docker-compose* -n
+```
+
+### 4. Verificar Build
+
+```sh
+# Testar build completo
+pnpm build 2>&1 | tail -20
+
+# Verificar migrations pendentes
+rg "migration\|migrate" --include='*.ts' <modulo>-migracao/src/ -l
+```
+
+### 5. Gerar Relatório
+
+```markdown
+# Diagnóstico de Deploy — [nome do módulo]
+
+## Resumo
+- **Containers:** N ativos / N esperados
+- **Healthchecks:** N configurados
+- **Variáveis de ambiente:** N validadas / N sem validação
+- **Build:** ✅ OK | ❌ Falha
+
+## Problemas Detectados
+
+### 🔴 Crítico
+| Área | Problema | Impacto | Ação |
+|------|----------|---------|------|
+
+### 🟡 Moderado
+| Área | Problema | Impacto | Ação |
+|------|----------|---------|------|
+
+## Plano de Ação
+1. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
--- a/agents/ag-documentacao/persona
+++ b/agents/ag-documentacao/persona
@ -38,18 +38,23 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa
-2. Escrever JSDoc em funções e serviços compartilhados
-3. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)
-4. Manter o `README` e documentação do projeto atualizada
-5. Documentar APIs internas (contratos de rotas, parâmetros, retornos)
+1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)
+2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa
+3. Escrever JSDoc em funções e serviços compartilhados
+4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)
+5. Manter o `README` e documentação do projeto atualizada
+6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)

 ## Restrições

- NÃO inventa regras de negócio — documenta o que o código implementa
+- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)
+- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou
+- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar
+- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema
 - NÃO duplica conteúdo entre artefatos — referencia via links
 - Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos
 - JSDoc documenta o "porquê", não o "o quê" (que o TypeScript já expressa)
+- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir

 ## Colaborações

--- a/agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL
+++ b/agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL
@ -0,0 +1,96 @@
+---
+name: diagnosticar-lacunas-documentacao
+description: >
+  Diagnóstico de lacunas de documentação: funções sem JSDoc, módulos sem
+  regras de negócio documentadas, documentação desatualizada.
+scope: local
+---
+
+# Skill: Diagnosticar Lacunas de Documentação
+
+## Objetivo
+
+Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.
+
+## Etapas
+
+### 1. Verificar JSDoc em Funções Compartilhadas
+
+```sh
+# Listar funções exportadas sem JSDoc
+rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ -n | while read line; do
+  file=$(echo "$line" | cut -d: -f1)
+  lineno=$(echo "$line" | cut -d: -f2)
+  prev=$((lineno - 1))
+  if ! sed -n "${prev}p" "$file" | grep -q "*/"; then
+    echo "SEM JSDOC: $line"
+  fi
+done
+```
+
+### 2. Verificar Regras de Negócio Documentadas
+
+```sh
+# Listar módulos com lógica complexa
+rg "if.*&&|switch|\.length\s*>" --include='*.ts' <modulo>-back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn
+
+# Verificar quais têm .regras-negocio.md
+fd ".regras-negocio.md" <modulo>/ -l
+
+# Detectar lógica complexa sem documentação de regras
+# (comparar os dois resultados acima)
+```
+
+### 3. Verificar Documentação de API
+
+```sh
+# Listar rotas sem comentário explicativo
+rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n
+
+# Verificar quais rotas têm JSDoc
+rg "/\*\*" --include='*.ts' <modulo>-back/src/rotas/ -c
+```
+
+### 4. Detectar Dessincronia Código ↔ Docs
+
+```sh
+# Buscar campos mencionados em .regras-negocio.md que não existem no código
+# (verificação manual por arquivo)
+
+# Buscar decisões técnicas que deveriam estar na Memória
+rg "DECISÃO|ADR|NOTA|IMPORTANTE" --include='*.ts' --include='*.md' <modulo>/ -n
+```
+
+### 5. Gerar Relatório
+
+```markdown
+# Diagnóstico de Documentação — [nome do módulo]
+
+## Resumo
+- **Funções compartilhadas sem JSDoc:** N
+- **Módulos complexos sem .regras-negocio.md:** N
+- **Rotas sem documentação:** N
+
+## Lacunas Encontradas
+
+### 🔴 Crítico — Lógica Complexa Não Documentada
+| Arquivo | Complexidade | O que documentar |
+|---------|-------------|-----------------|
+
+### 🟡 Moderado — JSDoc Ausente
+| Arquivo | Função | Tipo |
+|---------|--------|------|
+
+### 🟢 Baixo — Melhorias
+| Arquivo | O que melhorar |
+|---------|---------------|
+
+## Plano de Documentação (priorizado)
+1. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Rule: `global/rules/jsdoc-padrao`
+- Rule: `global/rules/regras-negocio-md`
--- a/agents/ag-front/persona
+++ b/agents/ag-front/persona
@ -37,16 +37,18 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Implementar páginas e componentes Vue 3 (`paginas/`, `componentes/`)
-2. Criar composables reutilizáveis (`composables/use*.ts`)
-3. Integrar com APIs do backend via `*-comuns` (schemas compartilhados)
-4. Garantir mensagens de UI no vocabulário do domínio (não técnico)
-5. Extrair CSS para arquivos co-localizados quando necessário
-6. Manter componentes dentro do limite de 250 linhas
-7. Implementar fluxos de navegação e estados de interface
+1. **Diagnosticar antes de corrigir** — executar a skill `diagnosticar-saude-frontend` antes de qualquer correção (ver `global/rules/diagnostico-antes-correcao`)
+2. Implementar páginas e componentes Vue 3 (`paginas/`, `componentes/`)
+3. Criar composables reutilizáveis (`composables/use*.ts`)
+4. Integrar com APIs do backend via `*-comuns` (schemas compartilhados)
+5. Garantir mensagens de UI no vocabulário do domínio (não técnico)
+6. Extrair CSS para arquivos co-localizados quando necessário
+7. Manter componentes dentro do limite de 250 linhas
+8. Implementar fluxos de navegação e estados de interface

 ## Restrições

+- NUNCA corrigir sem antes diagnosticar a causa raiz (ver `global/rules/diagnostico-antes-correcao`)
 - NUNCA importar de pacotes `*-back` diretamente
 - NUNCA usar `any` ou `as any`
 - Todo componente Vue deve usar `defineComponent` com `setup()`
--- a/agents/ag-front/skills/diagnosticar-saude-frontend/SKILL
+++ b/agents/ag-front/skills/diagnosticar-saude-frontend/SKILL
@ -0,0 +1,108 @@
+---
+name: diagnosticar-saude-frontend
+description: >
+  Diagnóstico sistemático de saúde do frontend: componentes, composables,
+  estados de UI, acessibilidade e integração com API.
+scope: local
+---
+
+# Skill: Diagnosticar Saúde do Frontend
+
+## Objetivo
+
+Analisar a saúde de um módulo frontend Vue 3 para identificar problemas antes de corrigi-los.
+
+## Etapas
+
+### 1. Verificar Estrutura de Componentes
+
+```sh
+# Listar componentes e tamanho
+fd "*.vue" <modulo>-front/src/ --exec wc -l {} | sort -rn | head -20
+
+# Detectar componentes acima do limite (250 linhas)
+fd "*.vue" <modulo>-front/src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {}
+
+# Verificar se usam defineComponent com setup()
+rg "defineComponent" --include='*.vue' <modulo>-front/src/ -l
+```
+
+### 2. Verificar Estados de Interface
+
+```sh
+# Detectar componentes sem estado de loading
+rg "loading|carregando|isLoading" --include='*.vue' <modulo>-front/src/ -l
+
+# Detectar componentes sem tratamento de erro
+rg "erro|error|catch" --include='*.vue' <modulo>-front/src/ -l
+
+# Detectar componentes sem estado vazio
+rg "vazio|empty|sem.*dados|nenhum" --include='*.vue' <modulo>-front/src/ -l
+```
+
+### 3. Verificar Integração com Schemas
+
+```sh
+# Verificar se schemas são importados do *-comuns
+rg "from.*comuns" --include='*.ts' --include='*.vue' <modulo>-front/src/ | head -20
+
+# Detectar schemas redefinidos no front (violação)
+rg "z\.object\(\{" --include='*.ts' --include='*.vue' <modulo>-front/src/ -l
+
+# Detectar uso de any
+rg "as any|: any" --include='*.ts' --include='*.vue' <modulo>-front/src/ -n
+```
+
+### 4. Verificar Composables
+
+```sh
+# Listar composables existentes
+fd "use*.ts" <modulo>-front/src/composables/ -l
+
+# Verificar composables duplicando lógica
+rg "ref\(|reactive\(|computed\(" --include='*.vue' <modulo>-front/src/ -c | sort -t: -k2 -rn | head -10
+```
+
+### 5. Verificar Mensagens ao Usuário
+
+```sh
+# Detectar mensagens técnicas expostas ao usuário
+rg "Error:|Exception:|null|undefined|NaN" --include='*.vue' <modulo>-front/src/ -n
+
+# Verificar se mensagens usam linguagem do domínio
+rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts' <modulo>-front/src/ -n
+```
+
+### 6. Gerar Relatório
+
+```markdown
+# Diagnóstico Frontend — [nome do módulo]
+
+## Resumo
+- **Componentes analisados:** N
+- **Composables verificados:** N
+- **Problemas encontrados:** N
+
+## Problemas Detectados
+
+### 🔴 Crítico
+| Componente | Problema | Impacto | Ação |
+|------------|----------|---------|------|
+
+### 🟡 Moderado
+| Componente | Problema | Impacto | Ação |
+|------------|----------|---------|------|
+
+### 🟢 Baixo
+| Componente | Problema | Impacto | Ação |
+|------------|----------|---------|------|
+
+## Plano de Correção (priorizado)
+1. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
+- Rule: `global/rules/estrutura-vue` (via ag-front)
--- a/agents/ag-memoria/persona
+++ b/agents/ag-memoria/persona
@ -59,11 +59,15 @@ A memória perde valor se estiver fragmentada. É sua responsabilidade garantir
 ## Restrições

 - **NUNCA executar `git commit`, `git push` ou qualquer comando que altere o histórico do repositório** — o controle de versão é responsabilidade exclusiva do usuário humano (ver `global/rules/proibido-commit-ia`)
+- NUNCA inventar, fabricar, presumir ou extrapolar conhecimento — registrar e recuperar **exclusivamente** informações reais e verificáveis
 - NUNCA registre informações sem um `resumo` significativo
 - NUNCA registre dados sensíveis (senhas, tokens reais, dados pessoais de terceiros)
- NÃO invente conhecimento — se a busca não retornar resultados, informe que não há registros
+- NUNCA criar memórias com conteúdo inventado, hipotético ou especulativo — todo registro deve refletir algo que **realmente aconteceu** ou foi **decidido explicitamente**
+- NUNCA responder uma consulta com informações fabricadas — se a busca não retornar resultados, informar que **não há registros** e nunca preencher lacunas com suposições
+- NUNCA atribuir decisões, regras ou funcionalidades ao projeto sem evidência concreta na memória ou no código-fonte
 - NÃO atue como desenvolvedor (escrevendo código de features) ou arquiteto (definindo padrões do ecossistema) — seu foco é **consultar e persistir o conhecimento**
 - NÃO duplique memórias — busque antes de criar e edite quando a informação já existir
+- Quando houver dúvida sobre a veracidade de uma informação, **perguntar ao operador** em vez de registrar

 ## Colaborações

--- a/agents/ag-refatorar/persona
+++ b/agents/ag-refatorar/persona
@ -154,6 +154,7 @@ Você nunca refatora por vaidade. Toda refatoração deve ter um **motivo claro*

 ## Restrições

+- NUNCA refatorar sem antes diagnosticar code smells e violações — executar `diagnosticar-code-smells` (ver `global/rules/diagnostico-antes-correcao`)
 - NUNCA alterar comportamento externo durante refatoração — se o comportamento precisa mudar, é feature, não refatoração
 - NUNCA refatorar por estética — toda mudança deve ter justificativa técnica (acoplamento, duplicação, complexidade, violação SOLID)
 - NUNCA introduzir padrão sem problema que o justifique — "Generalidade Especulativa" é um code smell
--- a/agents/ag-testes/persona
+++ b/agents/ag-testes/persona
@ -37,16 +37,18 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Criar e manter testes unitários para lógica de negócio crítica
-2. Criar testes de integração para rotas de API
-3. Elaborar roteiros de teste manual (cenários passo a passo)
-4. Definir critérios de aceite para cada feature
-5. Identificar casos extremos e cenários de falha não cobertos
-6. Validar schemas Zod contra dados reais de produção
-7. Documentar bugs encontrados com passos de reprodução
+1. **Diagnosticar antes de testar** — executar a skill `diagnosticar-cobertura-testes` para mapear gaps antes de criar testes (ver `global/rules/diagnostico-antes-correcao`)
+2. Criar e manter testes unitários para lógica de negócio crítica
+3. Criar testes de integração para rotas de API
+4. Elaborar roteiros de teste manual (cenários passo a passo)
+5. Definir critérios de aceite para cada feature
+6. Identificar casos extremos e cenários de falha não cobertos
+7. Validar schemas Zod contra dados reais de produção
+8. Documentar bugs encontrados com passos de reprodução

 ## Restrições

+- NUNCA criar testes sem antes diagnosticar a cobertura existente (ver `global/rules/diagnostico-antes-correcao`)
 - NÃO modifica código de produção — apenas cria/modifica arquivos de teste
 - NÃO aprova uma feature sem cobertura dos cenários críticos
 - Testes devem ser independentes e repetíveis
--- a/agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL
+++ b/agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL
@ -0,0 +1,97 @@
+---
+name: diagnosticar-cobertura-testes
+description: >
+  Diagnóstico de cobertura de testes: identificar áreas sem cobertura,
+  priorizar criação de testes e mapear cenários ausentes.
+scope: local
+---
+
+# Skill: Diagnosticar Cobertura de Testes
+
+## Objetivo
+
+Mapear a cobertura de testes de um módulo para identificar gaps críticos antes de criar novos testes ou validar correções.
+
+## Etapas
+
+### 1. Inventariar Testes Existentes
+
+```sh
+# Listar arquivos de teste
+fd "*.spec.ts" <modulo>/ -l
+fd "*.test.ts" <modulo>/ -l
+
+# Contar testes por pacote
+echo "=== Back ===" && fd "*.spec.ts" <modulo>-back/ | wc -l
+echo "=== Front ===" && fd "*.spec.ts" <modulo>-front/ | wc -l
+echo "=== Comuns ===" && fd "*.spec.ts" <modulo>-comuns/ | wc -l
+```
+
+### 2. Mapear Código Sem Testes
+
+```sh
+# Listar arquivos de código sem arquivo de teste correspondente
+for f in $(fd "*.ts" <modulo>-back/src/ --exclude "*.spec.ts" --exclude "*.test.ts" --exclude "*.d.ts"); do
+  base=$(basename "$f" .ts)
+  if ! fd "${base}.spec.ts" <modulo>/ -q && ! fd "${base}.test.ts" <modulo>/ -q; then
+    echo "SEM TESTE: $f"
+  fi
+done
+```
+
+### 3. Classificar por Criticidade
+
+| Criticidade | O que testar primeiro |
+|-------------|----------------------|
+| 🔴 Crítico | Lógica de negócio em `servicos/`, schemas Zod, máquinas de estado |
+| 🟡 Importante | Rotas de API, processadores de fila, composables complexos |
+| 🟢 Desejável | Utils, helpers, componentes de UI puros |
+
+### 4. Verificar Qualidade dos Testes Existentes
+
+```sh
+# Detectar testes sem assertions
+rg "expect\(|assert\(|toBe\(|toEqual\(" --include='*.spec.ts' <modulo>/ -c | awk -F: '$2==0'
+
+# Detectar testes com descrições vagas
+rg "it\('" --include='*.spec.ts' <modulo>/ -n | grep -i "should work\|test\|funciona"
+
+# Verificar mocks sem documentação
+rg "mock\(|jest\.fn\(|vi\.fn\(" --include='*.spec.ts' <modulo>/ -n
+```
+
+### 5. Gerar Relatório
+
+```markdown
+# Diagnóstico de Cobertura — [nome do módulo]
+
+## Resumo
+- **Arquivos de código:** N
+- **Arquivos de teste:** N
+- **Cobertura estimada:** N%
+- **Gaps críticos:** N
+
+## Gaps de Cobertura
+
+### 🔴 Sem teste — Lógica Crítica
+| Arquivo | Responsabilidade | Risco |
+|---------|-----------------|-------|
+
+### 🟡 Sem teste — Funcionalidade Importante
+| Arquivo | Responsabilidade | Risco |
+|---------|-----------------|-------|
+
+## Testes Existentes com Problemas
+| Arquivo de Teste | Problema | Ação |
+|-----------------|----------|------|
+
+## Plano de Priorização
+1. [Crítico] Criar testes para ...
+2. [Crítico] Criar testes para ...
+3. [Importante] Criar testes para ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
--- a/agents/ag-ux/persona
+++ b/agents/ag-ux/persona
@ -37,16 +37,18 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas

 ## Responsabilidades

-1. Revisar telas implementadas e propor melhorias de usabilidade
-2. Definir fluxos de navegação claros e intuitivos
-3. Garantir que mensagens de interface estejam em linguagem do domínio
-4. Propor estados visuais para todos os cenários (loading, erro, vazio, sucesso)
-5. Organizar a hierarquia de informação das telas
-6. Revisar labels, placeholders e textos de ajuda
-7. Identificar inconsistências de UX entre módulos
+1. **Auditar antes de propor** — executar a skill `auditar-ux-heuristicas` antes de sugerir mudanças de UX (ver `global/rules/diagnostico-antes-correcao`)
+2. Revisar telas implementadas e propor melhorias de usabilidade
+3. Definir fluxos de navegação claros e intuitivos
+4. Garantir que mensagens de interface estejam em linguagem do domínio
+5. Propor estados visuais para todos os cenários (loading, erro, vazio, sucesso)
+6. Organizar a hierarquia de informação das telas
+7. Revisar labels, placeholders e textos de ajuda
+8. Identificar inconsistências de UX entre módulos

 ## Restrições

+- NUNCA propor mudanças de UX sem antes auditar o estado atual (ver `global/rules/diagnostico-antes-correcao`)
 - NÃO implementa código Vue diretamente — orienta o `@ag-front`
 - NÃO usa jargões técnicos de TI em textos de interface
 - NÃO propõe fluxos que violem regras de negócio documentadas
--- a/agents/ag-ux/skills/auditar-ux-heuristicas/SKILL
+++ b/agents/ag-ux/skills/auditar-ux-heuristicas/SKILL
@ -0,0 +1,63 @@
+---
+name: auditar-ux-heuristicas
+description: >
+  Auditoria de UX baseada em heurísticas de Nielsen e verificação de estados de UI.
+scope: local
+---
+
+# Skill: Auditar UX por Heurísticas
+
+## Objetivo
+
+Avaliar UX de tela ou fluxo antes de propor mudanças.
+
+## Etapas
+
+### 1. Heurísticas de Nielsen
+
+| # | Heurística | Pergunta |
+|---|-----------|----------|
+| 1 | Visibilidade do status | Sistema informa o que acontece? |
+| 2 | Compatibilidade | Mensagens usam linguagem do domínio? |
+| 3 | Controle e liberdade | Pode desfazer, voltar, cancelar? |
+| 4 | Consistência | Mesmos conceitos, mesma aparência? |
+| 5 | Prevenção de erros | Campos obrigatórios claros? Confirmação em ações destrutivas? |
+| 6 | Reconhecimento > Lembrança | Labels descritivos? |
+| 7 | Flexibilidade | Ações frequentes acessíveis? |
+| 8 | Estética minimalista | Info desnecessária? |
+| 9 | Recuperação de erros | Mensagens orientam correção? |
+| 10 | Ajuda | Ajuda contextual disponível? |
+
+### 2. Estados de Interface
+
+Para cada componente: `□ Loading □ Vazio □ Sucesso □ Erro □ Desabilitado`
+
+### 3. Acessibilidade Básica
+
+```sh
+rg "<img" --include='*.vue' <modulo>-front/src/ -n | grep -v "alt="
+rg "<v-btn\|<button" --include='*.vue' <modulo>-front/src/ -n | grep -v "aria-label\|title"
+```
+
+### 4. Relatório
+
+```markdown
+# Auditoria UX — [tela/fluxo]
+
+## Achados por Heurística
+| # | Heurística | Status | Problema | Recomendação |
+|---|-----------|--------|----------|--------------|
+
+## Estados de Interface
+| Componente | Loading | Vazio | Erro | Sucesso |
+|------------|---------|-------|------|---------|
+
+## Plano de Melhoria
+1. ...
+```
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Rule: `global/rules/mensagens-usuario`
+- Rule: `global/rules/feedback-visivel`
--- a/global/rules/diagnostico-antes-correcao
+++ b/global/rules/diagnostico-antes-correcao
@ -0,0 +1,121 @@
+---
+type: rule
+name: diagnostico-antes-correcao
+description: Todo agente DEVE realizar diagnóstico antes de implementar qualquer correção ou mudança
+scope: global
+trigger: always_on
+priority: alta
+updatedAt: "2026-07-09"
+---
+
+# Regra: Diagnóstico Obrigatório Antes de Correção
+
+## Contexto
+
+Corrigir sem diagnosticar é tratar sintomas sem entender a causa. Isso leva a correções superficiais que reintroduzem o problema ou criam efeitos colaterais. Todo agente deve primeiro **entender** o problema para depois **resolver**.
+
+## Regra
+
+Antes de implementar qualquer correção, mudança ou refatoração, o agente **DEVE** executar um diagnóstico mínimo que responda três perguntas:
+
+1. **O que está errado?** — Identificar o problema concreto (erro, smell, inconsistência)
+2. **Por que está errado?** — Entender a causa raiz, não apenas o sintoma
+3. **Qual o impacto?** — Avaliar quais arquivos, módulos ou funcionalidades são afetados
+
+## Protocolo Mínimo de Diagnóstico
+
+### Etapa 1 — Coleta de evidências
+
+Antes de editar qualquer arquivo, o agente deve:
+
+- Ler o código afetado integralmente (não apenas a linha do erro)
+- Verificar dependências e importações do arquivo
+- Consultar a Memória Azteca para soluções anteriores do mesmo problema
+- Verificar se há `.regras-negocio.md` relevante
+
+### Etapa 2 — Análise de causa raiz
+
+O agente deve diferenciar:
+
+| Tipo | Exemplo | Abordagem |
+|------|---------|-----------|
+| **Sintoma** | "Campo X não aparece na tela" | NÃO corrigir direto |
+| **Causa intermediária** | "O tipo não inclui o campo X" | Investigar mais |
+| **Causa raiz** | "A migração não adicionou a coluna X no banco" | ESTA é a correção |
+
+### Etapa 3 — Plano de correção
+
+Antes de implementar, declarar ao operador:
+
+```
+DIAGNÓSTICO:
+- Problema: [descrição objetiva]
+- Causa raiz: [identificação da causa]
+- Arquivos afetados: [lista]
+- Plano de correção: [passos]
+- Riscos: [efeitos colaterais possíveis]
+```
+
+## Diagnóstico por Domínio
+
+Cada agente aplica o protocolo mínimo acima com foco no seu domínio:
+
+| Agente | Diagnóstico Específico |
+|--------|----------------------|
+| `@ag-back` | Verificar rotas, queries, schemas Zod, filas, logs de erro |
+| `@ag-front` | Verificar componente, composable, props/emits, estados de UI, console do navegador |
+| `@ag-refatorar` | Executar skill `diagnosticar-code-smells` antes de qualquer refatoração |
+| `@ag-testes` | Mapear cobertura existente, identificar cenários ausentes |
+| `@ag-deploy` | Verificar logs, healthchecks, variáveis de ambiente, estado dos containers |
+| `@ag-arquiteto` | Verificar fronteiras de módulo, dependências, contratos de API |
+| `@ag-ux` | Verificar fluxo de uso completo, estados de interface, mensagens ao usuário |
+| `@ag-documentacao` | Verificar JSDoc existente, `.regras-negocio.md`, dessincronia código/docs |
+| `@ag-agente` | Executar `auditar-agentes.sh`, verificar contradições entre personas |
+
+## Exceções
+
+A etapa de diagnóstico pode ser **simplificada** (não eliminada) quando:
+
+- O erro é trivial e isolado (typo, import faltando, formatação)
+- O operador fornece diagnóstico completo junto com a solicitação
+- É uma continuação de correção já diagnosticada na mesma conversa
+
+Mesmo nesses casos, o agente deve confirmar a compreensão do problema antes de agir.
+
+## Exemplos
+
+### ✅ Correto
+
+```
+Operador: "O campo email não está salvando"
+Agente:
+  1. Leu o componente de formulário → campo existe, emite evento corretamente
+  2. Leu a rota da API → recebe o campo, mas o schema Zod não inclui 'email'
+  3. Verificou o schema no *-comuns → campo ausente
+  DIAGNÓSTICO: Schema Zod em _contatos.ts não inclui o campo 'email'.
+  Causa raiz: migração de contatos alterou estrutura sem atualizar schema.
+  PLANO: Adicionar campo ao schema → rodar build → verificar front.
+```
+
+### ❌ Incorreto
+
+```
+Operador: "O campo email não está salvando"
+Agente: "Vou adicionar o campo email no componente Vue."
+→ Não investigou a causa. Pode ser problema no schema, na API ou no banco.
+```
+
+## Impacto
+
+Sem esta regra:
+- Agentes corrigem sintomas ao invés de causas raiz
+- Correções criam novos bugs em cascata
+- O operador perde tempo revisando correções superficiais
+- A mesma classe de problema reaparece repetidamente
+
+## Referências
+
+- Skill: `global/skills/diagnosticar-antes-corrigir/SKILL`
+- Skill: `global/skills/diagnosticar-erros-build/SKILL`
+- Skill: `agents/ag-refatorar/skills/diagnosticar-code-smells/SKILL`
+- Rule: `global/rules/autonomia-agente`
--- a/global/skills/diagnosticar-antes-corrigir/SKILL
+++ b/global/skills/diagnosticar-antes-corrigir/SKILL
@ -0,0 +1,192 @@
+---
+name: diagnosticar-antes-corrigir
+scope: global
+updatedAt: "2026-07-09"
+description: >
+  Protocolo universal de diagnóstico que todo agente deve seguir antes de implementar
+  correções, mudanças ou refatorações. Define etapas, ferramentas e formato de saída.
+---
+
+# Skill: Diagnosticar Antes de Corrigir
+
+Use esta skill **sempre** que receber uma solicitação de correção, ajuste ou mudança. Ela é a implementação operacional da rule `diagnostico-antes-correcao`.
+
+---
+
+## PASSO 1 — Compreender a Solicitação
+
+Antes de qualquer ação, responder internamente:
+
+| Pergunta | Resposta esperada |
+|----------|-------------------|
+| O que o operador reportou? | Descrição objetiva do problema |
+| É um erro de build, runtime, lógica ou visual? | Classificação |
+| Qual módulo/pacote é afetado? | `*-back`, `*-front`, `*-comuns`, `*-migracao` |
+| O operador já forneceu diagnóstico? | Se sim, validar antes de aceitar |
+
+---
+
+## PASSO 2 — Coletar Evidências
+
+### 2.1. Ler o código afetado (completo)
+
+```sh
+# Não ler apenas a linha do erro — ler o arquivo inteiro para contexto
+view_file <arquivo_afetado>
+
+# Verificar imports e dependências
+rg "import.*from" <arquivo_afetado>
+
+# Verificar quem usa este arquivo
+rg "<nome_do_export>" --include='*.ts' --include='*.vue' -l
+```
+
+### 2.2. Verificar erros de build (se aplicável)
+
+```sh
+# Verificar se o build passa
+pnpm --filter <pacote> build 2>&1 | head -50
+
+# Ou checagem de tipos isolada
+npx tsc --noEmit -p <caminho>/tsconfig.json 2>&1 | head -30
+```
+
+### 2.3. Consultar memória (obrigatório)
+
+```sh
+# Buscar problemas semelhantes já resolvidos
+curl -s -X POST "https://memoria-ia.idz.one/api/busca/rapida" \
+  -H 'Content-Type: application/json' \
+  -H "CHAVE: banana" \
+  -d '{"termo": "PALAVRAS_CHAVE_DO_PROBLEMA"}' | jq '.items[] | {codigo, titulo, resumo}'
+```
+
+### 2.4. Verificar regras de negócio documentadas
+
+```sh
+# Buscar .regras-negocio.md no diretório afetado
+fd ".regras-negocio.md" <diretorio_do_modulo>
+
+# Buscar comentários explicativos no código
+rg "HACK|FIXME|TODO|NOTA|IMPORTANTE|REGRA" <arquivo_afetado>
+```
+
+---
+
+## PASSO 3 — Análise de Causa Raiz
+
+### 3.1. Técnica dos 5 Porquês
+
+Aplicar progressivamente até chegar à causa raiz:
+
+```
+Por que o campo não salva?
+  → Porque a API retorna 400.
+Por que a API retorna 400?
+  → Porque a validação Zod rejeita o campo.
+Por que o Zod rejeita?
+  → Porque o schema não inclui esse campo.
+Por que o schema não inclui?
+  → Porque a migração adicionou a coluna mas o schema não foi atualizado.
+CAUSA RAIZ: Schema Zod desatualizado após migração.
+```
+
+### 3.2. Classificar a causa
+
+| Categoria | Exemplos |
+|-----------|----------|
+| **Schema/Tipo** | Zod schema desatualizado, tipo TypeScript incorreto |
+| **Banco de dados** | Coluna ausente, migração não executada |
+| **Lógica de negócio** | Condição errada, regra não implementada |
+| **Integração** | API fora do contrato, fila não processando |
+| **Interface** | Componente não reativo, estado inconsistente |
+| **Configuração** | Variável de ambiente, tsconfig, dependência |
+| **Infraestrutura** | Container, deploy, proxy, certificado |
+
+---
+
+## PASSO 4 — Avaliar Impacto
+
+```sh
+# Quais arquivos usam o código afetado?
+rg "<simbolo_afetado>" --include='*.ts' --include='*.vue' --include='*.tsx' -l
+
+# Quantos módulos são impactados?
+rg "<simbolo_afetado>" --include='*.ts' -l | xargs -I{} dirname {} | sort -u
+```
+
+Classificar o impacto:
+
+| Severidade | Critério |
+|------------|----------|
+| 🔴 Alto | Afeta 3+ módulos, pode causar regressão |
+| 🟡 Médio | Afeta 1-2 arquivos, impacto limitado |
+| 🟢 Baixo | Isolado, sem dependentes |
+
+---
+
+## PASSO 5 — Declarar Diagnóstico
+
+**OBRIGATÓRIO:** Antes de editar qualquer arquivo, apresentar ao operador:
+
+```markdown
+## 🔍 Diagnóstico
+
+**Problema:** [descrição objetiva do problema observado]
+**Causa raiz:** [identificação precisa da causa]
+**Categoria:** [Schema/Tipo | Banco | Lógica | Integração | Interface | Config | Infra]
+**Severidade:** [🔴 Alto | 🟡 Médio | 🟢 Baixo]
+
+### Arquivos afetados
+- `caminho/arquivo1.ts` — [o que precisa mudar]
+- `caminho/arquivo2.vue` — [o que precisa mudar]
+
+### Plano de correção
+1. [Primeiro passo]
+2. [Segundo passo]
+3. [Verificação]
+
+### Riscos
+- [Efeito colateral possível, se houver]
+```
+
+---
+
+## PASSO 6 — Executar Correção
+
+Somente após o diagnóstico declarado:
+
+1. Aplicar as mudanças conforme o plano
+2. Verificar build após cada mudança significativa
+3. Confirmar que o problema original foi resolvido
+4. Verificar se não houve regressão nos arquivos afetados
+
+---
+
+## Atalho para Problemas Triviais
+
+Quando o problema é **evidentemente trivial** (typo, import faltando, formatação), o diagnóstico pode ser condensado em uma linha:
+
+```
+DIAGNÓSTICO: Import ausente de `zContato` em `_contatos.ts` (linha 5). Adicionando.
+```
+
+A etapa de diagnóstico **nunca é eliminada** — apenas simplificada proporcionalmente à complexidade.
+
+---
+
+## Checklist
+
+- [ ] O código afetado foi lido integralmente (não apenas a linha do erro)?
+- [ ] A Memória Azteca foi consultada para soluções anteriores?
+- [ ] A causa raiz foi identificada (não apenas o sintoma)?
+- [ ] O impacto foi avaliado (arquivos e módulos afetados)?
+- [ ] O diagnóstico foi declarado ao operador antes da correção?
+- [ ] A correção resolve a causa raiz, não apenas o sintoma?
+
+## Referências
+
+- Rule: `global/rules/diagnostico-antes-correcao`
+- Skill: `global/skills/diagnosticar-erros-build/SKILL`
+- Skill: `agents/ag-refatorar/skills/diagnosticar-code-smells/SKILL`
+- Rule: `global/rules/autonomia-agente`
--- a/manifesto.json
+++ b/manifesto.json
@ -1,7 +1,7 @@
 {
  "versao": "3.0.0",
  "base_url": "https://paiol.idz.one/desenvolvimento/agent-ia",
-  "gerado_em": "2026-07-02T10:07:14-03:00",
+  "gerado_em": "2026-07-09T15:03:29-03:00",
  "artefatos": {
    "global": {
      "rules": [
@ -10,6 +10,7 @@
        "global/rules/coleta-automatica-memorias",
        "global/rules/consultar-banco-query-ia",
        "global/rules/css-global-betha",
+        "global/rules/diagnostico-antes-correcao",
        "global/rules/escrita-natural",
        "global/rules/estilos-design-system",
        "global/rules/feedback-visivel",
@ -36,6 +37,7 @@
      ],
      "skills": [
        "global/skills/criar-schema-zod/SKILL",
+        "global/skills/diagnosticar-antes-corrigir/SKILL",
        "global/skills/diagnosticar-erros-build/SKILL",
        "global/skills/documentar-decisao-tecnica/SKILL",
        "global/skills/documentar-dominio-modulo/SKILL",
@ -69,7 +71,7 @@

        ],
        "skills": [
-
+          "agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL"
        ]
      },
      "ag-back": {
@ -82,7 +84,7 @@

        ],
        "skills": [
-
+          "agents/ag-back/skills/diagnosticar-saude-backend/SKILL"
        ]
      },
      "ag-comercial": {
@ -111,7 +113,7 @@
          "agents/ag-deploy/workflows/atualizar-agente"
        ],
        "skills": [
-
+          "agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL"
        ]
      },
      "ag-documentacao": {
@ -124,7 +126,7 @@

        ],
        "skills": [
-
+          "agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL"
        ]
      },
      "ag-front": {
@ -138,7 +140,7 @@
          "agents/ag-front/workflows/criar-fluxograma"
        ],
        "skills": [
-
+          "agents/ag-front/skills/diagnosticar-saude-frontend/SKILL"
        ]
      },
      "ag-land": {
@ -192,7 +194,7 @@

        ],
        "skills": [
-
+          "agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL"
        ]
      },
      "ag-ux": {
@ -205,7 +207,7 @@

        ],
        "skills": [
-
+          "agents/ag-ux/skills/auditar-ux-heuristicas/SKILL"
        ]
      }
    }