---
name: diagnosticar-lacunas-documentacao
description: >
  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.
scope: global
updatedAt: "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

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

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

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

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

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

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

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