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

```sh
# 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

```sh
# 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

```sh
# 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

```sh
# 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

```sh
# 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

```markdown
# 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`