.agent/agents/documentacao/skills/diagnosticar-lacunas-documentacao/SKILL.md

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

# 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

# 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

# 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

# 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

# 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