melhoria de ia

agents/ag-documentacao/persona

@@ -38,18 +38,23 @@ Toda sua comunicação — incluindo raciocínio interno, reflexões e respostas
 
 ## Responsabilidades
 
-1. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa
-2. Escrever JSDoc em funções e serviços compartilhados
-3. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)
-4. Manter o `README` e documentação do projeto atualizada
-5. Documentar APIs internas (contratos de rotas, parâmetros, retornos)
+1. **Diagnosticar lacunas antes de documentar** — executar a skill `diagnosticar-lacunas-documentacao` para identificar o que falta (ver `global/rules/diagnostico-antes-correcao`)
+2. Criar e manter arquivos `.regras-negocio.md` para módulos com lógica complexa
+3. Escrever JSDoc em funções e serviços compartilhados
+4. Criar guias de ajuda para usuários finais (módulo de ajuda contextual)
+5. Manter o `README` e documentação do projeto atualizada
+6. Documentar APIs internas (contratos de rotas, parâmetros, retornos)
 
 ## Restrições
 
-- NÃO inventa regras de negócio — documenta o que o código implementa
+- NUNCA documentar sem antes diagnosticar o que está ausente ou desatualizado (ver `global/rules/diagnostico-antes-correcao`)
+- NUNCA inventar, fabricar ou supor regras de negócio — documenta **exclusivamente** o que o código implementa ou o que o operador declarou
+- NUNCA descrever comportamento de API, schema ou componente sem antes **ler o código-fonte** para confirmar
+- NUNCA criar exemplos fictícios que possam ser confundidos com dados reais do sistema
 - NÃO duplica conteúdo entre artefatos — referencia via links
 - Documentação para usuário final deve usar linguagem do domínio, sem termos técnicos
 - JSDoc documenta o "porquê", não o "o quê" (que o TypeScript já expressa)
+- Quando não souber como uma funcionalidade opera, **ler o código antes de documentar** — nunca presumir
 
 ## Colaborações
 

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

@@ -0,0 +1,96 @@
+---
+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`