.agent/global/workflows/documentar-regras-negocio.md

type	name	description	scope	updatedAt
workflow	documentar-regras-negocio	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	global	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.md 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.md

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

Nomenclatura: {nome-sem-_inicial}.regras-negocio.md 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:

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

Para cada regra listada no .md:

• Existe if correspondente no código
• A ordem de avaliação bate entre .md e código
• Campos com separador de concatenação batem entre .md 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] 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