---
name: diagnosticar-lacunas-documentacao
description: >
  Diagnóstico de lacunas de documentação: funções sem JSDoc, módulos sem
  regras de negócio documentadas, documentação desatualizada.
scope: local
---

# Skill: Diagnosticar Lacunas de Documentação

## Objetivo

Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.

## Etapas

### 1. Verificar JSDoc em Funções Compartilhadas

```sh
# Listar funções exportadas sem JSDoc
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ -n | while read line; do
  file=$(echo "$line" | cut -d: -f1)
  lineno=$(echo "$line" | cut -d: -f2)
  prev=$((lineno - 1))
  if ! sed -n "${prev}p" "$file" | grep -q "*/"; then
    echo "SEM JSDOC: $line"
  fi
done
```

### 2. Verificar Regras de Negócio Documentadas

```sh
# Listar módulos com lógica complexa
rg "if.*&&|switch|\.length\s*>" --include='*.ts' <modulo>-back/src/servicos/ -c | awk -F: '$2>5' | sort -t: -k2 -rn

# Verificar quais têm .regras-negocio.md
fd ".regras-negocio.md" <modulo>/ -l

# Detectar lógica complexa sem documentação de regras
# (comparar os dois resultados acima)
```

### 3. Verificar Documentação de API

```sh
# Listar rotas sem comentário explicativo
rg "router\.(get|post|put|patch|delete)" --include='*.ts' <modulo>-back/src/rotas/ -n

# Verificar quais rotas têm JSDoc
rg "/\*\*" --include='*.ts' <modulo>-back/src/rotas/ -c
```

### 4. Detectar Dessincronia Código ↔ Docs

```sh
# Buscar campos mencionados em .regras-negocio.md que não existem no código
# (verificação manual por arquivo)

# Buscar decisões técnicas que deveriam estar na Memória
rg "DECISÃO|ADR|NOTA|IMPORTANTE" --include='*.ts' --include='*.md' <modulo>/ -n
```

### 5. Gerar Relatório

```markdown
# Diagnóstico de Documentação — [nome do módulo]

## Resumo
- **Funções compartilhadas sem JSDoc:** N
- **Módulos complexos sem .regras-negocio.md:** N
- **Rotas sem documentação:** N

## Lacunas Encontradas

### 🔴 Crítico — Lógica Complexa Não Documentada
| Arquivo | Complexidade | O que documentar |
|---------|-------------|-----------------|

### 🟡 Moderado — JSDoc Ausente
| Arquivo | Função | Tipo |
|---------|--------|------|

### 🟢 Baixo — Melhorias
| Arquivo | O que melhorar |
|---------|---------------|

## Plano de Documentação (priorizado)
1. ...
```

## Referências

- Rule: `global/rules/diagnostico-antes-correcao`
- Rule: `global/rules/jsdoc-padrao`
- Rule: `global/rules/regras-negocio-md`