121 lines
4.4 KiB
Text
121 lines
4.4 KiB
Text
---
|
|
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 |
|
|
|--------|----------------------|
|
|
| `@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`
|