From b188f28ad4710790eb6161a7897276886f63b9b3 Mon Sep 17 00:00:00 2001 From: Luiz Silva Date: Thu, 9 Jul 2026 12:03:56 -0300 Subject: [PATCH] melhoria de ia --- agents/ag-arquiteto/persona | 18 +- .../skills/auditar-arquitetura-modulo/SKILL | 89 ++++++++ agents/ag-back/persona | 18 +- .../skills/diagnosticar-saude-backend/SKILL | 117 +++++++++++ agents/ag-comercial/persona | 10 +- agents/ag-deploy/persona | 14 +- .../skills/diagnosticar-saude-deploy/SKILL | 88 ++++++++ agents/ag-documentacao/persona | 17 +- .../diagnosticar-lacunas-documentacao/SKILL | 96 +++++++++ agents/ag-front/persona | 16 +- .../skills/diagnosticar-saude-frontend/SKILL | 108 ++++++++++ agents/ag-memoria/persona | 6 +- agents/ag-refatorar/persona | 1 + agents/ag-testes/persona | 16 +- .../diagnosticar-cobertura-testes/SKILL | 97 +++++++++ agents/ag-ux/persona | 16 +- .../ag-ux/skills/auditar-ux-heuristicas/SKILL | 63 ++++++ global/rules/diagnostico-antes-correcao | 121 +++++++++++ .../skills/diagnosticar-antes-corrigir/SKILL | 192 ++++++++++++++++++ manifesto.json | 18 +- 20 files changed, 1060 insertions(+), 61 deletions(-) create mode 100644 agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL create mode 100644 agents/ag-back/skills/diagnosticar-saude-backend/SKILL create mode 100644 agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL create mode 100644 agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL create mode 100644 agents/ag-front/skills/diagnosticar-saude-frontend/SKILL create mode 100644 agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL create mode 100644 agents/ag-ux/skills/auditar-ux-heuristicas/SKILL create mode 100644 global/rules/diagnostico-antes-correcao create mode 100644 global/skills/diagnosticar-antes-corrigir/SKILL diff --git a/agents/ag-arquiteto/persona b/agents/ag-arquiteto/persona index 48a9f6d..ca2d7aa 100644 --- 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` diff --git a/agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL b/agents/ag-arquiteto/skills/auditar-arquitetura-modulo/SKILL new file mode 100644 index 0000000..148d693 --- /dev/null +++ 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' -front/src/ -n +rg "from.*-front" --include='*.ts' -back/src/ -n + +# Verificar imports entre módulos diferentes +rg "from.*" --include='*.ts' / -n +``` + +### 2. Verificar Acoplamento + +```sh +# Contar imports por arquivo (alto = muito acoplado) +fd "*.ts" -back/src/ --exec sh -c 'echo "$(grep -c "^import" "$1") $1"' _ {} | sort -rn | head -10 + +# Detectar dependências circulares +rg "from.*\.\/" --include='*.ts' /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' -back/src/rotas/ -n + +# Verificar se schemas Zod estão no *-comuns (não duplicados no back) +rg "z\.object" --include='*.ts' -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' / -n + +# Verificar limite de linhas +fd "*.ts" /src/ --exec sh -c 'lines=$(wc -l < "$1"); [ "$lines" -gt 250 ] && echo "$lines $1"' _ {} + +# Verificar uso de any +rg "as any|: any" --include='*.ts' / -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` diff --git a/agents/ag-back/persona b/agents/ag-back/persona index f500f08..9a2ff93 100644 --- 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 diff --git a/agents/ag-back/skills/diagnosticar-saude-backend/SKILL b/agents/ag-back/skills/diagnosticar-saude-backend/SKILL new file mode 100644 index 0000000..2568600 --- /dev/null +++ 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' -comuns/src/tabelas/ -l + +# Verificar se schemas do comuns são usados no back +rg "from.*comuns" --include='*.ts' -back/src/ | head -20 + +# Detectar schemas redefinidos no back (violação de fronteiras) +rg "z\.object\(\{" --include='*.ts' -back/src/ -l +``` + +### 2. Verificar Consistência de Rotas + +```sh +# Listar todas as rotas definidas +rg "router\.(get|post|put|patch|delete)" --include='*.ts' -back/src/ -n + +# Verificar validação de entrada em cada rota +rg "zod|parse|safeParse" --include='*.ts' -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' -back/src/ -n + +# Detectar possíveis N+1 (query dentro de loop) +rg "for.*await|forEach.*await|map.*await" --include='*.ts' -back/src/ -n + +# Verificar transações (queries que deveriam ser atômicas) +rg "\.transaction\(" --include='*.ts' -back/src/ -l +``` + +### 4. Verificar Filas e CRONs + +```sh +# Listar processadores de fila +rg "process|worker|queue" --include='*.ts' -back/src/filas/ -l + +# Verificar tratamento de falha em filas +rg "catch|onFailed|failedReason" --include='*.ts' -back/src/filas/ -n + +# Listar CRONs agendados +rg "cron|schedule|repeat" --include='*.ts' -back/src/ -n +``` + +### 5. Verificar Tipagem e Build + +```sh +# Checar tipos sem gerar saída +npx tsc --noEmit -p -back/tsconfig.json 2>&1 | head -30 + +# Detectar uso de any +rg "as any|: any" --include='*.ts' -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` diff --git a/agents/ag-comercial/persona b/agents/ag-comercial/persona index b022c3e..dda5df3 100644 --- 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 diff --git a/agents/ag-deploy/persona b/agents/ag-deploy/persona index d265e20..657776c 100644 --- 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 diff --git a/agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL b/agents/ag-deploy/skills/diagnosticar-saude-deploy/SKILL new file mode 100644 index 0000000..0b78a29 --- /dev/null +++ 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 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' -back/src/ -n + +# Verificar se há variáveis sem default ou validação +rg "process\.env\." --include='*.ts' -back/src/ -n | grep -v "z\.\|zod\|Ambiente" +``` + +### 3. Verificar Healthchecks + +```sh +# Verificar endpoints de health +rg "health\|alive\|ready" --include='*.ts' -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' -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` diff --git a/agents/ag-documentacao/persona b/agents/ag-documentacao/persona index 8245945..c3dd8a7 100644 --- 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 diff --git a/agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL b/agents/ag-documentacao/skills/diagnosticar-lacunas-documentacao/SKILL new file mode 100644 index 0000000..dd241ea --- /dev/null +++ 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' -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' -back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn + +# Verificar quais têm .regras-negocio.md +fd ".regras-negocio.md" / -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' -back/src/rotas/ -n + +# Verificar quais rotas têm JSDoc +rg "/\*\*" --include='*.ts' -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' / -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` diff --git a/agents/ag-front/persona b/agents/ag-front/persona index c0d32a3..e306bff 100644 --- 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()` diff --git a/agents/ag-front/skills/diagnosticar-saude-frontend/SKILL b/agents/ag-front/skills/diagnosticar-saude-frontend/SKILL new file mode 100644 index 0000000..61b5d03 --- /dev/null +++ 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" -front/src/ --exec wc -l {} | sort -rn | head -20 + +# Detectar componentes acima do limite (250 linhas) +fd "*.vue" -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' -front/src/ -l +``` + +### 2. Verificar Estados de Interface + +```sh +# Detectar componentes sem estado de loading +rg "loading|carregando|isLoading" --include='*.vue' -front/src/ -l + +# Detectar componentes sem tratamento de erro +rg "erro|error|catch" --include='*.vue' -front/src/ -l + +# Detectar componentes sem estado vazio +rg "vazio|empty|sem.*dados|nenhum" --include='*.vue' -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' -front/src/ | head -20 + +# Detectar schemas redefinidos no front (violação) +rg "z\.object\(\{" --include='*.ts' --include='*.vue' -front/src/ -l + +# Detectar uso de any +rg "as any|: any" --include='*.ts' --include='*.vue' -front/src/ -n +``` + +### 4. Verificar Composables + +```sh +# Listar composables existentes +fd "use*.ts" -front/src/composables/ -l + +# Verificar composables duplicando lógica +rg "ref\(|reactive\(|computed\(" --include='*.vue' -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' -front/src/ -n + +# Verificar se mensagens usam linguagem do domínio +rg "snackbar\|toast\|notify\|mensagem\|alerta" --include='*.vue' --include='*.ts' -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) diff --git a/agents/ag-memoria/persona b/agents/ag-memoria/persona index dccdaa1..aa5aeca 100644 --- 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 diff --git a/agents/ag-refatorar/persona b/agents/ag-refatorar/persona index 2ac8afd..8f4aee5 100644 --- 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 diff --git a/agents/ag-testes/persona b/agents/ag-testes/persona index daf0f98..4bd9089 100644 --- 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 diff --git a/agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL b/agents/ag-testes/skills/diagnosticar-cobertura-testes/SKILL new file mode 100644 index 0000000..324cec1 --- /dev/null +++ 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" / -l +fd "*.test.ts" / -l + +# Contar testes por pacote +echo "=== Back ===" && fd "*.spec.ts" -back/ | wc -l +echo "=== Front ===" && fd "*.spec.ts" -front/ | wc -l +echo "=== Comuns ===" && fd "*.spec.ts" -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" -back/src/ --exclude "*.spec.ts" --exclude "*.test.ts" --exclude "*.d.ts"); do + base=$(basename "$f" .ts) + if ! fd "${base}.spec.ts" / -q && ! fd "${base}.test.ts" / -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' / -c | awk -F: '$2==0' + +# Detectar testes com descrições vagas +rg "it\('" --include='*.spec.ts' / -n | grep -i "should work\|test\|funciona" + +# Verificar mocks sem documentação +rg "mock\(|jest\.fn\(|vi\.fn\(" --include='*.spec.ts' / -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` diff --git a/agents/ag-ux/persona b/agents/ag-ux/persona index dbd5a25..df9a0dc 100644 --- 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 diff --git a/agents/ag-ux/skills/auditar-ux-heuristicas/SKILL b/agents/ag-ux/skills/auditar-ux-heuristicas/SKILL new file mode 100644 index 0000000..337b414 --- /dev/null +++ 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 "-front/src/ -n | grep -v "alt=" +rg "-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` diff --git a/global/rules/diagnostico-antes-correcao b/global/rules/diagnostico-antes-correcao new file mode 100644 index 0000000..0389962 --- /dev/null +++ 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` diff --git a/global/skills/diagnosticar-antes-corrigir/SKILL b/global/skills/diagnosticar-antes-corrigir/SKILL new file mode 100644 index 0000000..025944f --- /dev/null +++ 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 + +# Verificar imports e dependências +rg "import.*from" + +# Verificar quem usa este arquivo +rg "" --include='*.ts' --include='*.vue' -l +``` + +### 2.2. Verificar erros de build (se aplicável) + +```sh +# Verificar se o build passa +pnpm --filter build 2>&1 | head -50 + +# Ou checagem de tipos isolada +npx tsc --noEmit -p /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" + +# Buscar comentários explicativos no código +rg "HACK|FIXME|TODO|NOTA|IMPORTANTE|REGRA" +``` + +--- + +## 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 "" --include='*.ts' --include='*.vue' --include='*.tsx' -l + +# Quantos módulos são impactados? +rg "" --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` diff --git a/manifesto.json b/manifesto.json index 226beb3..d7395fb 100644 --- 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" ] } }