115 lines
3.7 KiB
Markdown
115 lines
3.7 KiB
Markdown
---
|
|
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`
|