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

name	description	scope	updatedAt
diagnosticar-lacunas-documentacao	Diagnóstico de lacunas de documentação cobrindo os 6 pilares: comentários de aplicação no código, ajuda na tela (.ajuda.md), wiki de usuário, wiki dev, rota /llm.md e memórias da IA.	global	2026-09-01

Skill: Diagnosticar Lacunas de Documentação e Memória

Objetivo

Identificar proativamente onde a documentação e memórias estão ausentes, incompletas ou desatualizadas antes de criar ou corrigir código.

---

Etapas de Diagnóstico nos 6 Pilares

1. Pilar 1 — Comentários e JSDoc no Código-Fonte

# Listar funções exportadas sem JSDoc
rg "^export (const|function|async function)" --include='*.ts' <modulo>-comuns/src/ <modulo>-back/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 DE APLICAÇÃO: $line"
  fi
done

2. Pilar 2 — Ajuda na Tela (UI) em .ajuda.md

# Listar modais/telas Vue que não possuem arquivo .ajuda.md correspondente
find <modulo>-front/src -name "modal*.vue" -o -name "Modal*.vue" | while read vueFile; do
  dir=$(dirname "$vueFile")
  base=$(basename "$vueFile" .vue)
  ajudaFile="$dir/$base.ajuda.md"
  if [ ! -f "$ajudaFile" ]; then
    echo "MODAL SEM AJUDA: $vueFile → falta $base.ajuda.md"
  fi
done

3. Pilar 3 — Wiki do Usuário (<modulo-wiki>/<modulo-id>/)

# Verificar se existe documentação de usuário do módulo (modulo-wiki com fallback para ../wiki)
ls -la <modulo-wiki>/<modulo-id>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM <modulo-wiki>/<modulo-id>/"

4. Pilar 4 — Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/)

# Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs
ls -la <modulo-wiki>/dev/<modulo-id>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM <modulo-wiki>/dev/<modulo-id>/"

5. Pilar 5 — Rota de Integração de IA (/llm.md)

# Verificar se o backend possui a rota /llm.md registrada
rg "llm\.md" --include='*.ts' <modulo>-back/src/ -n || echo "ROTA /llm.md NÃO ENCONTRADA NO BACKEND"

6. Pilar 6 — Memória das Ações da IA e Identidade (<base_projeto>/memorias-ia/)

# 1. Verificar arquivo obrigatório modulo.yml e chaves
if [ -f "memorias-ia/modulo.yml" ]; then
  for chave in modulo-id modulo-caminho modulo-descricao modulo-tipo modulo-acesso modulo-wiki; do
    grep -q "^$chave:" memorias-ia/modulo.yml || echo "CHAVE AUSENTE OU RECOMENDADA EM modulo.yml: $chave"
  done
else
  echo "CRÍTICO: memorias-ia/modulo.yml AUSENTE"
fi

# 2. Verificar memórias registradas para o projeto
ls -la memorias-ia/ 2>/dev/null || echo "DIRETÓRIO memorias-ia/ NÃO ENCONTRADO NA RAIZ DO PROJETO"

---

Relatório Consolidado de Diagnóstico

# Diagnóstico de Documentação e Memória — [Módulo]

## Resumo dos 6 Pilares
- **Código-fonte sem JSDoc de aplicação:** N
- **Modais/Telas sem .ajuda.md co-localizado:** N
- **Wiki de Usuário (<modulo-wiki>/<modulo-id>/):** Presente / Ausente
- **Wiki de Desenvolvimento (<modulo-wiki>/dev/<modulo-id>/):** Presente / Ausente
- **Rota /llm.md no backend:** Configurada / Ausente
- **Identidade em memorias-ia/modulo.yml:** Conforme / Ausente
- **Registros em memorias-ia/:** N registros


## Ações Recomendadas
1. ...

---

Referências

• Rule: rules/ddd-documentacao-primeiro.md
• Rule: rules/jsdoc-padrao.md
• Rule: rules/regras-negocio-md.md
• Skill: skills/adicionar-ajuda/SKILL.md
• Skill: skills/documentar-dominio-modulo/SKILL.md
• Skill: skills/documentar-decisao-tecnica/SKILL.md