melhorias na ia

workflows/documentar-regras-negocio.global.md

@@ -0,0 +1,105 @@
+---
+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.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`
+
+```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.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:
+
+```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 `.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
+```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