otimização do agent para docuemntação

skills/documentar-regras-negocio/SKILL.md

@@ -1,15 +1,13 @@
 ---
-type: workflow
 name: documentar-regras-negocio
-description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md co-localizado com um módulo TypeScript e garantir consistência entre código e documentação
+description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (../../wiki/dev/<modulo>/) e garantir consistência com o código TypeScript.
 scope: global
-updatedAt: "2026-06-01"
+updatedAt: "2026-09-01"
 ---
 
-# Workflow: Documentar Regras de Negócio de um Módulo
+# Workflow / Skill: Documentar Regras de Negócio de um Módulo
 
-Use este workflow com `/documentar-regras-negocio.global` para criar ou atualizar o arquivo
-`{modulo}.regras-negocio` de qualquer módulo TypeScript com lógica de negócio não-trivial.
+Use este workflow para criar ou atualizar o arquivo de regras de negócio de qualquer módulo TypeScript com lógica não-trivial, armazenado na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
 
 ---
 
@@ -17,20 +15,20 @@ Use este workflow com `/documentar-regras-negocio.global` para criar ou atualiza
 
 Identificar e anotar:
 
-- Nome do arquivo e localização exata
+- Nome do arquivo e localização exata no código
 - Funções exportadas e suas responsabilidades
 - Todos os `if` que representam critérios de decisão
 - Campos lidos e gravados (especialmente JSONB e campos de status)
 - Queries de banco: tabelas acessadas, filtros aplicados, joins
 - Caminhos alternativos (revisão manual, erros, skips)
-- Dependências externas (filas, e-mails, serviços)
+- Dependências externas (filas BullMQ, e-mails, serviços)
 
 ---
 
-[2] Verificar se já existe um `.regras-negocio`
+[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento
 
 ```bash
-ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
+ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null
 ```
 
 - **Existe** → ler e identificar o que está desatualizado → ir para o passo [4]
@@ -38,17 +36,17 @@ ls $(dirname <arquivo>)/*.regras-negocio.md 2>/dev/null
 
 ---
 
-[3] Criar o arquivo `.regras-negocio`
+[3] Criar o arquivo de regras na Wiki de Desenvolvimento
 
-Nomenclatura: `{nome-sem-_inicial}.regras-negocio` na mesma pasta do módulo.
+**Localização:** `../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md` (ou `../../wiki/dev/<modulo>/regras-negocio/`).
 
-Preencher com o template da skill `documentar-regras-negocio.global`:
-- Contexto
+Preencher com a estrutura padrão:
+- Contexto operacional
 - Critérios de Entrada
-- Regras de Processamento (numeradas)
+- Regras de Processamento (numeradas em ordem estrita)
 - Casos de Revisão Manual
-- Estratégia de Saída / Fusão de Campos
-- Dependências Externas
+- Estratégia de Saída / Persistência de Campos
+- Dependências Externas (tabelas, filas, CRONs)
 
 ---
 
@@ -57,30 +55,31 @@ Preencher com o template da skill `documentar-regras-negocio.global`:
 Garantir que a primeira linha útil do arquivo TypeScript seja:
 
 ```typescript
-// Regras de negócio: ver {modulo}.regras-negocio.md
+// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md
 ```
 
 Se já existia e está correto → sem mudança necessária.
 
 ---
 
-[5] Simplificar JSDoc que duplicam as regras
+[5] Estruturar JSDoc com aplicação prática e referência ao `.regras-negocio.md`
 
 Percorrer cada função do módulo:
 
-- JSDoc com lista de regras de negócio → substituir por referência ao ``
-- Manter apenas `@param` e `@returns` com informação técnica precisa
-- Comentários inline (`//`) explicando lógica pontual são aceitos → manter
+- Inserir JSDoc explicando a aplicação prática da função no sistema (rule `rules/jsdoc-padrao.md`).
+- Referenciar o arquivo `.regras-negocio.md` para a lista detalhada de regras e critérios de decisão.
+- Manter `@param` com contexto do domínio, `@returns` e `@throws`.
+- Manter comentários inline (`//`) explicando cálculos pontuais ou regras de exceção.
 
 ---
 
-[6] Verificar consistência — código ↔ ``
+[6] Verificar consistência — código ↔ `.regras-negocio.md`
 
-Para cada regra listada no ``:
+Para cada regra listada no `.regras-negocio.md`:
 
 - [ ] Existe `if` correspondente no código
-- [ ] A ordem de avaliação bate entre `` e código
-- [ ] Campos com separador de concatenação batem entre `` e código
+- [ ] A ordem de avaliação bate entre `.regras-negocio.md` e código
+- [ ] Campos com separador de concatenação batem entre documentação e código
 - [ ] `null` como neutro está implementado corretamente (`!= null`)
 - [ ] Queries têm `orderBy` quando a posição dos resultados importa
 
@@ -97,9 +96,10 @@ Zero erros = concluído.
 
 ---
 
-[8] Registrar no sistema de conhecimento (se regras novas)
+[8] Sincronizar com a Wiki de Desenvolvimento e Memórias
 
-Se o workflow revelou novos padrões de negócio relevantes ao projeto:
+Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:
 
-- Criar ou atualizar ADR via skill `documentar-decisao-tecnica`
-- Verificar se alguma rule precisa ser atualizada
+- Atualizar a especificação técnica na **Wiki de Desenvolvimento** em `../../wiki/dev/<modulo>/`.
+- Criar ou atualizar ADR em `../../wiki/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
+- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.