Luiz Silva 4a9f5f70ff aprimoração de ia

2026-08-10 16:18:49 -03:00

5.3 KiB

Raw Blame History

name	scope	updatedAt	description
diagnosticar-antes-corrigir	global	2026-07-09	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)

# 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)

# 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)

grep -rn "PALAVRAS_CHAVE_DO_PROBLEMA" .

2.4. Verificar regras de negócio documentadas

# 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

# 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:

## 🔍 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:

Aplicar as mudanças conforme o plano
Verificar build após cada mudança significativa
Confirmar que o problema original foi resolvido
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/refatorar/skills/diagnosticar-code-smells/SKILL
Rule: global/rules/autonomia-agente

5.3 KiB Raw Blame History