---
name: documentar-regras-negocio
description: Criar ou atualizar o arquivo {modulo}.regras-negocio.md na Wiki de Desenvolvimento (<base_projeto>/../wiki/dev/<modulo-id>/) e garantir consistência com o código TypeScript.
scope: global
updatedAt: "2026-09-02"
---

# 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 `<modulo-wiki>/dev/<modulo-id>/`.

---

[1] Obter a identidade do módulo e ler o código TypeScript

1. Ler `modulo-id` e `modulo-wiki` em `<base_projeto>/memorias-ia/modulo.yml` (fallback de wiki: `../wiki/`).
2. Identificar e anotar no código:
- 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

```bash
ls <modulo-wiki>/dev/<modulo-id>/*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:** `<modulo-wiki>/dev/<modulo-id>/{nome-do-modulo}.regras-negocio.md` (ou `<modulo-wiki>/dev/<modulo-id>/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:

```typescript
// Regras de negócio: ver <modulo-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
```bash
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 `<modulo-wiki>/dev/<modulo>/`.
- Criar ou atualizar ADR em `<modulo-wiki>/dev/<modulo>/adrs/` via skill `documentar-decisao-tecnica`.
- Registrar decisões e ações na memória em `<base_projeto>/memorias-ia/`.
- **Sincronização Git:** Executar commit e push exclusivamente na Wiki (`git -C <modulo-wiki> add -A && git -C <modulo-wiki> commit -m "docs(<modulo-id>): regras de negócio" && git -C <modulo-wiki> push`). Na aplicação (`<base_projeto>`), nunca comitar em master.