---
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
grep -rn "PALAVRAS_CHAVE_DO_PROBLEMA" .
```

### 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/refatorar/skills/diagnosticar-code-smells/SKILL`
- Rule: `global/rules/autonomia-agente`