96 lines
2.5 KiB
Text
96 lines
2.5 KiB
Text
---
|
|
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`
|