.agent/global/skills/documentar-regras-negocio/SKILL.md

name	description	scope	updatedAt
documentar-regras-negocio	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.	global	2026-09-01

Workflow / Skill: Documentar Regras de Negócio de um Módulo

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>/.

---

[1] Ler o módulo TypeScript completamente

Identificar e anotar:

• 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 BullMQ, e-mails, serviços)

---

[2] Verificar se já existe a documentação de regras na Wiki de Desenvolvimento

ls ../../wiki/dev/<modulo>/*regras-negocio*.md 2>/dev/null

• Existe → ler e identificar o que está desatualizado → ir para o passo [4]
• Não existe → ir para o passo [3]

---

[3] Criar o arquivo de regras na Wiki de Desenvolvimento

Localização: ../../wiki/dev/<modulo>/{nome-do-modulo}.regras-negocio.md (ou ../../wiki/dev/<modulo>/regras-negocio/).

Preencher com a estrutura padrão:

• Contexto operacional
• Critérios de Entrada
• Regras de Processamento (numeradas em ordem estrita)
• Casos de Revisão Manual
• Estratégia de Saída / Persistência de Campos
• Dependências Externas (tabelas, filas, CRONs)

---

[4] Adicionar ou verificar a referência no .ts

Garantir que a primeira linha útil do arquivo TypeScript seja:

// Regras de negócio: ver ../../wiki/dev/<modulo>/{modulo}.regras-negocio.md

Se já existia e está correto → sem mudança necessária.

---

[5] Estruturar JSDoc com aplicação prática e referência ao .regras-negocio.md

Percorrer cada função do módulo:

• 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 ↔ .regras-negocio.md

Para cada regra listada no .regras-negocio.md:

• Existe if correspondente no 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

---

[7] Validar tipagem

// turbo

npx tsc --noEmit

Zero erros = concluído.

---

[8] Sincronizar com a Wiki de Desenvolvimento e Memórias

Se o módulo introduziu ou alterou arquitetura ou regras consolidadas do módulo:

• 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/.