---
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
scope: global
updatedAt: "2026-06-01"
---

# Workflow: 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.

---

[1] Ler o módulo TypeScript completamente

Identificar e anotar:

- Nome do arquivo e localização exata
- 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)

---

[2] Verificar se já existe um `.regras-negocio`

```bash
ls $(dirname <arquivo>)/*.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 `.regras-negocio`

Nomenclatura: `{nome-sem-_inicial}.regras-negocio` na mesma pasta do módulo.

Preencher com o template da skill `documentar-regras-negocio.global`:
- Contexto
- Critérios de Entrada
- Regras de Processamento (numeradas)
- Casos de Revisão Manual
- Estratégia de Saída / Fusão de Campos
- Dependências Externas

---

[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}.regras-negocio.md
```

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

---

[5] Simplificar JSDoc que duplicam as regras

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

---

[6] Verificar consistência — código ↔ ``

Para cada regra listada no ``:

- [ ] 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
- [ ] `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] Registrar no sistema de conhecimento (se regras novas)

Se o workflow revelou novos padrões de negócio relevantes ao projeto:

- Criar ou atualizar ADR em `.agent/memoria/` via skill `documentar-decisao-tecnica`
- Verificar se alguma rule precisa ser atualizada