.agent/skills/diagnosticar-saude-backend/SKILL.md

name	description	scope
diagnosticar-saude-backend	Diagnóstico sistemático de saúde do backend: rotas, queries, schemas, filas, CRONs e integrações antes de qualquer correção.	local

Skill: Diagnosticar Saúde do Backend

Objetivo

Analisar a saúde de um módulo backend para identificar problemas antes de corrigi-los. Produz relatório com causa raiz, severidade e plano de ação.

Pré-condições

• Acesso ao pacote *-back do módulo
• Acesso ao pacote *-comuns (schemas de contrato)

Etapas

1. Verificar Integridade de Schemas

# Listar todos os schemas Zod do módulo
rg "export const z" --include='*.ts' <modulo>-comuns/src/tabelas/ -l

# Verificar se schemas do comuns são usados no back
rg "from.*comuns" --include='*.ts' <modulo>-back/src/ | head -20

# Detectar schemas redefinidos no back (violação de fronteiras)
rg "z\.object\(\{" --include='*.ts' <modulo>-back/src/ -l

2. Verificar Consistência de Rotas

# Listar todas as rotas definidas
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/ -n

# Verificar validação de entrada em cada rota
rg "zod|parse|safeParse" --include='*.ts' <modulo>-back/src/rotas/ -l

# Detectar rotas sem validação Zod
# (comparar lista de rotas vs lista de validações)

3. Verificar Saúde de Queries

# Detectar queries sem tratamento de erro
rg "\.select\(|\.insert\(|\.update\(|\.delete\(" --include='*.ts' <modulo>-back/src/ -n

# Detectar possíveis N+1 (query dentro de loop)
rg "for.*await|forEach.*await|map.*await" --include='*.ts' <modulo>-back/src/ -n

# Verificar transações (queries que deveriam ser atômicas)
rg "\.transaction\(" --include='*.ts' <modulo>-back/src/ -l

4. Verificar Filas e CRONs

# Listar processadores de fila
rg "process|worker|queue" --include='*.ts' <modulo>-back/src/filas/ -l

# Verificar tratamento de falha em filas
rg "catch|onFailed|failedReason" --include='*.ts' <modulo>-back/src/filas/ -n

# Listar CRONs agendados
rg "cron|schedule|repeat" --include='*.ts' <modulo>-back/src/ -n

5. Verificar Tipagem e Build

# Checar tipos sem gerar saída
npx tsc --noEmit -p <modulo>-back/tsconfig.json 2>&1 | head -30

# Detectar uso de any
rg "as any|: any" --include='*.ts' <modulo>-back/src/ -n

6. Gerar Relatório

# Diagnóstico Backend — [nome do módulo]

## Resumo
- **Rotas analisadas:** N
- **Schemas verificados:** N
- **Problemas encontrados:** N

## Problemas Detectados

### 🔴 Crítico
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|

### 🟡 Moderado
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|

### 🟢 Baixo
| Arquivo | Problema | Causa | Ação |
|---------|----------|-------|------|

## Plano de Correção (priorizado)
1. ...
2. ...

Referências

• Rule: global/rules/diagnostico-antes-correcao
• Skill: global/skills/diagnosticar-antes-corrigir/SKILL
• Rule: global/rules/zod-validacao-padrao