188 lines
5.3 KiB
Text
188 lines
5.3 KiB
Text
---
|
|
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`
|