.
This commit is contained in:
parent
f5abcec365
commit
e7adba8fd8
84 changed files with 4222 additions and 2182 deletions
|
|
@ -1,188 +0,0 @@
|
|||
---
|
||||
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`
|
||||
Loading…
Add table
Add a link
Reference in a new issue