otimização do agent para docuemntação

agents/documentacao/skills/diagnosticar-lacunas-documentacao/SKILL

@@ -1,96 +1,104 @@
 ---
 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
+  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
+# Skill: Diagnosticar Lacunas de Documentação e Memória
 
 ## Objetivo
 
-Identificar proativamente onde a documentação está ausente, incompleta ou desatualizada antes de criar ou corrigir documentação.
+Identificar proativamente onde a documentação e memórias estão ausentes, incompletas ou desatualizadas antes de criar ou corrigir código.
 
-## Etapas
+---
 
-### 1. Verificar JSDoc em Funções Compartilhadas
+## 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/ -n | while read line; do
+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: $line"
+    echo "SEM JSDOC DE APLICAÇÃO: $line"
   fi
 done
 ```
 
-### 2. Verificar Regras de Negócio Documentadas
+### 2. Pilar 2 — Ajuda na Tela (UI) em `.ajuda.md`
 
 ```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)
+# 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. Verificar Documentação de API
+### 3. Pilar 3 — Wiki do Usuário (`../../wiki/<modulo>/`)
 
 ```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
+# Verificar se existe documentação de usuário do módulo
+ls -la ../../wiki/<modulo>/*.md 2>/dev/null || echo "WIKI DE USUÁRIO AUSENTE EM ../../wiki/<modulo>/"
 ```
 
-### 4. Detectar Dessincronia Código ↔ Docs
+### 4. Pilar 4 — Wiki de Desenvolvimento (`../../wiki/dev/<modulo>/`)
 
 ```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
+# Verificar se existe documentação de desenvolvimento, regras de negócio ({modulo}.regras-negocio.md) e ADRs
+ls -la ../../wiki/dev/<modulo>/*.md 2>/dev/null || echo "WIKI DEV AUSENTE EM ../../wiki/dev/<modulo>/"
 ```
 
-### 5. Gerar Relatório
+### 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 (`<base_projeto>/memorias-ia/`)
+
+```sh
+# 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 — [nome do módulo]
+# Diagnóstico de Documentação e Memória — [Módulo]
 
-## Resumo
-- **Funções compartilhadas sem JSDoc:** N
-- **Módulos complexos sem .regras-negocio.md:** N
-- **Rotas sem documentação:** N
+## 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 (../../wiki/<modulo>/):** Presente / Ausente
+- **Wiki de Desenvolvimento (../../wiki/dev/<modulo>/):** Presente / Ausente
+- **Rota /llm.md no backend:** Configurada / Ausente
+- **Registros em memorias-ia/:** N registros
 
-## 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)
+## Ações Recomendadas
 1. ...
 ```
 
+---
+
 ## Referências
 
-- Rule: `global/rules/diagnostico-antes-correcao`
-- Rule: `global/rules/jsdoc-padrao`
-- Rule: `global/rules/regras-negocio-md`
+- 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`