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

name	scope	updatedAt	description
documentar-regras-negocio	global	2026-06-01	Guia operacional para criar, preencher e manter arquivos {modulo}.regras-negocio.md co-localizados com módulos TypeScript de lógica de negócio complexa.

Skill: Documentar Regras de Negócio em Módulos

Use esta skill sempre que um módulo TypeScript contiver lógica de decisão não-trivial que precise ser rastreável por produto, suporte e desenvolvimento sem exigir leitura de código.

---

Quando usar esta skill

• Módulo com 3+ critérios de decisão distintos
• Lógica de eleição/priorização entre registros
• Processamento que pode resultar em revisão manual
• Worker/CRON consumindo dados com estratégias diferenciadas por tipo
• Importador automático com regras de aceite/rejeição

---

PASSO 1 — Identificar o escopo das regras

Antes de escrever o .md, percorrer o módulo e identificar:

Categoria	O que procurar
Critérios de entrada	Filtros de query (excluido, vencimento, etc.)
Critérios de bloqueio	Condições que bloqueiam o fluxo automático
Estratégia por tipo de dado	Concatenação vs. primeiro-não-nulo vs. outros
Eleição de principal	Regras de prioridade entre registros
Estado contraditório	Combinações de campos mutuamente exclusivas
Dependências externas	Tabelas, filas, serviços tocados

---

PASSO 2 — Criar o arquivo

Nomenclatura: {nome-do-modulo-sem-underline-inicial}.regras-negocio.md

Localizar na mesma pasta do arquivo TypeScript:

modulo/
  _meuModulo.ts
  meu-modulo.regras-negocio.md   ← co-localizado

Se o módulo for arquivo isolado (não pasta):

CRONS/
  _cron_nome.ts
  _cron_nome.regras-negocio.md   ← mesmo diretório

---

PASSO 3 — Preencher com o template

# Regras de Negócio — [Nome Legível do Módulo]

Módulo: `_arquivo.ts`
Localização: `caminho/relativo/ao/workspace`

---

## Contexto

[Por que este módulo existe. Qual problema de negócio resolve.
Inclua o cenário que levou à sua criação — ex: "O sistema pode gerar duplicatas
por importações simultâneas..."]

---

## Critérios de Entrada

[O que aciona o módulo. Filtros aplicados na query de identificação.
Ex: `excluido = false`, mesmo `(codigo_origem, vencimento)`, etc.]

---

## Regras de Processamento

[Numeradas em ordem de avaliação. Cada regra deve incluir:
- Condição de ativação
- O que acontece quando ativada
- Se bloqueia ou direciona]

### Regra 1 — [Nome]
...

### Regra 2 — [Nome]
...

---

## Casos de Revisão Manual

[Quando o fluxo automático não pode prosseguir.
Liste as condições que enviam para revisão manual.
Se aplicável: como o caso é reportado (e-mail, log, fila de revisão).]

> **`null` é neutro** quando aplicável: descrever aqui se a lógica usa null como ausência neutra.

---

## Estratégia de Saída / Fusão de Campos

[Como os dados são combinados ou qual resultado é produzido.
Usar tabela para clareza:]

| Campo | Estratégia |
|---|---|
| `campo_textual` | Concatenação sem repetição |
| `campo_data` | Primeiro valor não-nulo vence |
| `campo_booleano` | Primeiro valor não-nulo vence |

---

## Dependências Externas

[Tabelas lidas/escritas, filas disparadas, serviços externos.
Incluir colunas de relacionamento quando relevante.]

- Tabelas de negócio: `tabela_a`, `tabela_b`
- Relacionamentos re-apontados: `tabela_c` via `(codigo_origem, tabela_origem)`
- Filas: nenhuma / `nome-da-fila`
- E-mails: nenhum / destinatários e gatilho

---

PASSO 4 — Adicionar referência no módulo TypeScript

Na primeira linha útil do arquivo .ts (após shebang ou licença, se houver):

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

import { ... } from "..."

---

PASSO 5 — Limpar JSDoc duplicados

Percorrer os JSDoc do módulo e:

Se encontrar	Ação
JSDoc listando as regras de negócio	Substituir por referência ao .md
JSDoc descrevendo critérios de bloqueio	Simplificar para "ver .md"
JSDoc com listas de condições	Manter apenas @param e @returns
Comentário inline explicando uma regra	Manter — comentários de linha são aceitáveis

Exemplo de simplificação:

// ❌ Antes — JSDoc duplicando as regras
/**
 * Retorna false quando:
 * - vencimentos divergentes
 * - executada com datas distintas e não-nulas
 * - vencimento_prorrogado distintos
 * - estado contraditório: nao_executada=true + executada!=null
 */

// ✅ Depois — referência ao .md
/**
 * Verifica se o grupo pode ser fundido e elege o registro principal.
 * Critérios de bloqueio e regras de eleição: ver regras-negocio.md
 *
 * @param execs - Registros do grupo, ordenados do mais antigo para o mais recente
 * @returns Código do eleito, ou `undefined` quando o grupo vai para revisão manual
 */

---

PASSO 6 — Verificar consistência código ↔ .md

Percorrer cada regra listada no .md e verificar que há código correspondente:

• Cada critério de bloqueio tem um if (...) return undefined / return retornoVazio
• Cada estratégia de campo tem implementação em fundirCampos ou equivalente
• A ordem de avaliação no código bate com a ordem no .md
• Campos exclusivos de certas tabelas estão guardados pelo if (tabela === ...)
• queries têm orderBy quando a posição dos resultados tem significado (ver skill consultar-banco-knex)

---

Checklist Final

• Arquivo .md criado co-localizado com o módulo
• Referência // Regras de negócio: ver ... na primeira linha do .ts
• JSDoc simplificados — sem duplicar conteúdo do .md
• Todas as regras do .md têm implementação correspondente no código
• Código e .md estão consistentes (separadores, campos, condições)
• tsc --noEmit passa sem erros após qualquer mudança de código

---

Referências

• Rule: global/rules/regras-negocio-md.md
• Workflow: global/workflows/documentar-regras-negocio.md