.agent/rules/diagnostico-antes-correcao.md

type	name	description	scope	trigger	priority	updatedAt
rule	diagnostico-antes-correcao	Todo agente DEVE realizar diagnóstico antes de implementar qualquer correção ou mudança	global	always_on	alta	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
@back	Verificar rotas, queries, schemas Zod, filas, logs de erro
@front	Verificar componente, composable, props/emits, estados de UI, console do navegador
@refatorar	Executar skill diagnosticar-code-smells antes de qualquer refatoração
@testes	Mapear cobertura existente, identificar cenários ausentes
@deploy	Verificar logs, healthchecks, variáveis de ambiente, estado dos containers
@arquiteto	Verificar fronteiras de módulo, dependências, contratos de API
@ux	Verificar fluxo de uso completo, estados de interface, mensagens ao usuário
@documentacao	Verificar JSDoc existente, .regras-negocio.md, dessincronia código/docs
@agente	Auditar personas, 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/refatorar/skills/diagnosticar-code-smells/SKILL
• Rule: global/rules/autonomia-agente