forjajs 5.0.1 → 5.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (164) hide show
  1. package/CHANGELOG.md +38 -2
  2. package/README.md +4 -2
  3. package/README.pt-BR.md +4 -1
  4. package/boilerplates/02-saas-starter/README.md +58 -293
  5. package/boilerplates/02-saas-starter/backend/.env.example +13 -0
  6. package/boilerplates/02-saas-starter/backend/.oxlintrc.json +8 -0
  7. package/boilerplates/02-saas-starter/backend/nest-cli.json +6 -0
  8. package/boilerplates/02-saas-starter/backend/package.json +32 -73
  9. package/boilerplates/02-saas-starter/backend/src/app.module.ts +16 -16
  10. package/boilerplates/02-saas-starter/backend/src/billing/adapters/http/billing.controller.ts +55 -0
  11. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/orm-entities.ts +28 -0
  12. package/boilerplates/02-saas-starter/backend/src/billing/adapters/persistence/typeorm-billing.repository.ts +46 -0
  13. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.spec.ts +58 -0
  14. package/boilerplates/02-saas-starter/backend/src/billing/application/billing.service.ts +68 -0
  15. package/boilerplates/02-saas-starter/backend/src/billing/billing.module.ts +11 -0
  16. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.spec.ts +23 -0
  17. package/boilerplates/02-saas-starter/backend/src/billing/domain/plan.ts +36 -0
  18. package/boilerplates/02-saas-starter/backend/src/billing/domain/ports.ts +27 -0
  19. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.spec.ts +28 -0
  20. package/boilerplates/02-saas-starter/backend/src/billing/domain/subscription.ts +47 -0
  21. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/auth.dto.ts +22 -0
  22. package/boilerplates/02-saas-starter/backend/src/identity/adapters/http/identity.controller.ts +59 -0
  23. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/orm-entities.ts +25 -0
  24. package/boilerplates/02-saas-starter/backend/src/identity/adapters/persistence/typeorm-identity.repository.ts +47 -0
  25. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.spec.ts +72 -0
  26. package/boilerplates/02-saas-starter/backend/src/identity/application/auth.service.ts +63 -0
  27. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.spec.ts +19 -0
  28. package/boilerplates/02-saas-starter/backend/src/identity/domain/model.ts +42 -0
  29. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.spec.ts +17 -0
  30. package/boilerplates/02-saas-starter/backend/src/identity/domain/password.ts +26 -0
  31. package/boilerplates/02-saas-starter/backend/src/identity/identity.module.ts +12 -0
  32. package/boilerplates/02-saas-starter/backend/src/main.ts +19 -19
  33. package/boilerplates/02-saas-starter/backend/src/platform/auth/jwt-auth.guard.ts +17 -0
  34. package/boilerplates/02-saas-starter/backend/src/platform/auth/principal.ts +22 -0
  35. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.spec.ts +23 -0
  36. package/boilerplates/02-saas-starter/backend/src/platform/auth/roles.guard.ts +20 -0
  37. package/boilerplates/02-saas-starter/backend/src/platform/auth/token.service.ts +54 -0
  38. package/boilerplates/02-saas-starter/backend/src/platform/config.spec.ts +18 -0
  39. package/boilerplates/02-saas-starter/backend/src/platform/config.ts +33 -0
  40. package/boilerplates/02-saas-starter/backend/src/platform/platform.module.ts +14 -0
  41. package/boilerplates/02-saas-starter/backend/tsconfig.build.json +6 -0
  42. package/boilerplates/02-saas-starter/backend/tsconfig.json +16 -21
  43. package/boilerplates/02-saas-starter/backend/vitest.config.ts +7 -0
  44. package/boilerplates/02-saas-starter/boilerplate.manifest.json +19 -14
  45. package/boilerplates/02-saas-starter/docker-compose.yml +10 -24
  46. package/boilerplates/02-saas-starter/memory/30-domains/billing/context.md +15 -132
  47. package/boilerplates/02-saas-starter/memory/30-domains/identity/context.md +20 -0
  48. package/boilerplates/README.md +9 -10
  49. package/dist/bin/init-project.js +1 -0
  50. package/dist/lib/core/journey.js +10 -0
  51. package/dist/lib/generators/memory-generator.d.ts +0 -11
  52. package/dist/lib/generators/memory-generator.js +5 -161
  53. package/dist/lib/generators/readme-generator.js +1 -1
  54. package/dist/lib/llm/json-output.d.ts +14 -0
  55. package/dist/lib/llm/json-output.js +77 -0
  56. package/dist/lib/project-wiring.d.ts +8 -0
  57. package/dist/lib/project-wiring.js +74 -2
  58. package/dist/lib/validators/structure-validator.js +0 -1
  59. package/dist/packages/llm/src/index.js +12 -2
  60. package/dist/scripts/llm-fit.js +23 -1
  61. package/docs/llm-fit-loop.md +16 -0
  62. package/memory/90-decisions/0088-templates-validados.md +3 -0
  63. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  64. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  65. package/package.json +1 -1
  66. package/specs/skills-do-projeto/plan.md +40 -0
  67. package/specs/skills-do-projeto/spec.md +63 -0
  68. package/specs/skills-do-projeto/tasks.md +27 -0
  69. package/templates/project/AGENTS.md +9 -0
  70. package/templates/project/agents/context-engineer.md +3 -0
  71. package/templates/project/agents/governance.md +3 -0
  72. package/templates/project/agents/marketing.md +3 -0
  73. package/templates/project/agents/orchestrator.md +3 -0
  74. package/templates/project/agents/product.md +3 -0
  75. package/templates/project/agents/sdd-architect.md +3 -0
  76. package/templates/project/skills/README.md +14 -0
  77. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  78. package/templates/project/skills/api-design/SKILL.md +77 -0
  79. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  80. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  81. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  82. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  83. package/templates/project/skills/commit-message/SKILL.md +143 -0
  84. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  85. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  86. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  87. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  88. package/templates/project/skills/event-storming/SKILL.md +95 -0
  89. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  90. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  91. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  92. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  93. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  94. package/templates/project/skills/observability/SKILL.md +93 -0
  95. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  96. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  97. package/templates/project/skills/pull-request/SKILL.md +101 -0
  98. package/templates/project/skills/query-performance/SKILL.md +83 -0
  99. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  100. package/templates/project/skills/release-notes/SKILL.md +87 -0
  101. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  102. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  103. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  104. package/templates/project/skills/testing/SKILL.md +109 -0
  105. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  106. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  107. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  108. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  109. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  110. package/templates/project/skills/web-performance/SKILL.md +72 -0
  111. package/boilerplates/02-saas-starter/.env.example +0 -25
  112. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  113. package/boilerplates/02-saas-starter/INFO.md +0 -252
  114. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  115. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  116. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  117. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  118. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  119. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  120. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  121. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  122. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  123. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  124. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  125. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  126. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  127. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  128. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  129. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  130. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  131. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  132. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  133. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  134. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  135. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  136. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  137. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  138. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  139. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  140. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  141. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  142. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  143. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  144. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  145. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  146. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  147. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  148. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  149. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  150. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  151. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  152. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  153. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  154. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  155. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  156. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  157. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  158. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  159. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  160. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  161. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  162. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  163. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  164. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -0,0 +1,88 @@
1
+ ---
2
+ name: data-migrations
3
+ description: Use quando desenhar um esquema relacional ou alterá-lo em produção: mapeia agregados para tabelas, garante invariantes com constraints, deriva índices dos padrões de consulta e planeja migrações sem downtime com um rollback por passo.
4
+ ---
5
+
6
+ # Migrações de Dados
7
+
8
+ O esquema é a parte mais longeva de um sistema: o código é substituído, os dados ficam. Esta skill desenha o esquema a partir do modelo de domínio e planeja as mudanças para que a aplicação em execução nunca encontre um banco com que não consiga lidar.
9
+
10
+ A saída padrão é um **esquema e um plano de migração ordenado**. Escreva arquivos de migração só quando o usuário pedir, usando a ferramenta de migração do projeto.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: agregados, objetos de valor e invariantes de `domain-modeling`; padrões de consulta de `api-design`; retenção e classificação de `lgpd-compliance`.
15
+ - Siga o código existente: o banco, a ferramenta de migração (Prisma Migrate, Drizzle Kit, TypeORM, Knex, `node-pg-migrate`, Flyway…), o estilo de nomes e a organização dos arquivos. Nunca misture ferramentas.
16
+ - O dialeto padrão é PostgreSQL. Diga quando um recurso é específico do dialeto.
17
+ - Volumes de dados ou tráfego desconhecidos vão para **Perguntas em aberto**: eles decidem se um passo precisa de lotes.
18
+
19
+ ## Do modelo de domínio às tabelas
20
+
21
+ - **Agregado** → uma tabela raiz mais tabelas para as entidades internas, com chave estrangeira para a raiz e `ON DELETE CASCADE` só dentro do agregado. Um agregado é salvo numa transação.
22
+ - **Entre agregados**: referência por ID. Uma chave estrangeira serve dentro do mesmo banco; nunca faça cascata entre agregados.
23
+ - **Objeto de valor** → colunas na tabela do dono (`period_start`, `period_end`), ou uma coluna JSON só quando ele nunca é consultado pelas partes.
24
+ - **Invariantes** que o banco consegue garantir viram constraints: `NOT NULL`, `CHECK (period_end >= period_start)`, `UNIQUE`, chaves estrangeiras, exclusion constraints. O domínio também as verifica; a constraint é a última linha de defesa.
25
+ - **Concorrência otimista** (`ETag` em `api-design`) → uma coluna `version` incrementada a cada atualização.
26
+ - **Dinheiro**: `numeric(19,4)` mais uma coluna de moeda. **Tempo**: `timestamptz` em UTC.
27
+ - **Dados pessoais**: marque as colunas classificadas por `lgpd-compliance`; planeje como a retenção as exclui ou anonimiza.
28
+
29
+ ## Índices
30
+
31
+ - Derive dos padrões de consulta reais (cada lista, filtro e ordenação em `api-design`), não de palpites.
32
+ - Chaves primárias e constraints únicas já são indexadas. Chaves estrangeiras não são no PostgreSQL: indexe-as quando você faz join ou exclusão por elas.
33
+ - Ordem das colunas num índice composto: colunas de igualdade primeiro, depois as de intervalo/ordenação.
34
+ - Todo índice deixa as escritas mais lentas. Cada um nomeia a consulta que atende.
35
+
36
+ ## Mudanças sem downtime: expandir → migrar → contrair
37
+
38
+ As versões antiga e nova da aplicação rodam juntas durante um deploy. Todo passo precisa funcionar com as duas.
39
+
40
+ 1. **Expandir**: adicione o que o código novo precisa, de forma retrocompatível (coluna nova anulável, tabela nova, índice novo criado de forma concorrente).
41
+ 2. **Migrar**: implante código que escreve no antigo e no novo; preencha as linhas existentes em lotes; depois passe as leituras para a estrutura nova.
42
+ 3. **Contrair**: depois que o código antigo sumir, remova a coluna ou tabela antiga numa release posterior.
43
+
44
+ Receitas:
45
+
46
+ | Mudança | Sequência segura |
47
+ |---|---|
48
+ | Adicionar uma coluna obrigatória | Adicionar anulável (ou com default constante) → preencher → `CHECK (col IS NOT NULL) NOT VALID` → `VALIDATE` → `SET NOT NULL` (o PostgreSQL 12+ pula a varredura completa) |
49
+ | Renomear uma coluna | Adicionar a nova → escrita dupla → preencher → ler a nova → remover a antiga. Nunca `RENAME` com tráfego ativo. |
50
+ | Mudar um tipo | Igual ao renomear, com uma coluna convertida |
51
+ | Adicionar um índice | `CREATE INDEX CONCURRENTLY` (fora de uma transação) |
52
+ | Adicionar uma chave estrangeira | `NOT VALID`, depois `VALIDATE CONSTRAINT` |
53
+ | Remover uma coluna | Parar de ler → parar de escrever → remover numa release posterior |
54
+
55
+ - Os preenchimentos rodam em lotes de tamanho limitado, são idempotentes e retomáveis, e nunca rodam dentro da transação da migração de esquema.
56
+ - Defina `lock_timeout` nas migrações para que um `ALTER` bloqueado falhe rápido em vez de enfileirar todo o tráfego atrás dele.
57
+
58
+ ## Rollback
59
+
60
+ Cada passo declara o seu rollback. Passos de expansão se revertem removendo o que adicionaram. Passos de contração destroem dados: **não têm rollback** além de uma restauração, então só rodam depois que a versão nova estiver estável, e o plano diz isso.
61
+
62
+ ## Formato
63
+
64
+ ```
65
+ ## Esquema
66
+ <DDL ou lista de tabelas: colunas, tipos, constraints, índices (cada um com a consulta que atende)>
67
+
68
+ ## Plano de migração
69
+ | # | Release | Passo | Tipo (expandir/migrar/contrair) | Locks / risco de duração | Rollback |
70
+ |---|---|---|---|---|---|
71
+
72
+ ## Perguntas em aberto
73
+ ```
74
+
75
+ ## Próximo
76
+
77
+ - `testing`: os testes de integração rodam as migrações contra um banco real e testam as constraints que espelham invariantes.
78
+ - `architecture-decision-record` para escolhas de banco ou de ferramenta de migração.
79
+
80
+ ## Evite
81
+
82
+ - Uma migração que muda esquema e código no mesmo deploy de forma incompatível.
83
+ - Editar uma migração que já rodou em algum lugar. Escreva uma nova.
84
+ - Preencher milhões de linhas numa transação só.
85
+ - Floats para dinheiro; timestamps sem fuso horário.
86
+ - Índices sem uma consulta que precise deles.
87
+ - Exclusões em cascata entre agregados.
88
+ - Remover colunas na mesma release que deixa de usá-las.
@@ -0,0 +1,75 @@
1
+ ---
2
+ name: dependency-upgrade
3
+ description: Use quando atualizar dependências de um projeto (pacotes npm, runtime, frameworks): inventaria o que está desatualizado e vulnerável, separa atualizações compatíveis das incompatíveis, lê os changelogs, aplica um major por vez com os testes como gate, resolve conflitos de peer sem forçar, e registra o que ficou para trás e por quê.
4
+ ---
5
+
6
+ # Atualização de Dependências
7
+
8
+ Atualizar dependências é trocar código que você não escreveu por outro código que você não escreveu. Feito de uma vez, um erro no meio de vinte atualizações não tem culpado. Feito um major por vez, com os testes rodando entre cada um, toda quebra tem endereço.
9
+
10
+ A saída padrão é um **plano de atualização**. Instale e altere arquivos só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: `package.json`, o lockfile, `engines`, o CI e a suíte de testes (`testing`).
15
+ - O gerenciador de pacotes do projeto (npm, pnpm, yarn) e o lockfile dele. Nunca misture gerenciadores.
16
+ - Toda atualização incompatível tem o changelog ou o guia de migração lido antes, não depois de quebrar.
17
+
18
+ ## Inventarie
19
+
20
+ 1. `npm outdated` (ou `pnpm outdated`): atual, desejada (dentro do intervalo) e mais recente.
21
+ 2. `npm audit` (ou `osv-scanner`): vulnerabilidades, com severidade e se há correção.
22
+ 3. Para cada major disponível: o changelog ou guia de migração, e as dependências que exigem uma versão específica (peer dependencies).
23
+ 4. O runtime: a versão de Node em `engines`, no CI e nos ambientes; as versões que o framework exige.
24
+
25
+ ## Classifique
26
+
27
+ | Tipo | Exemplo | Como tratar |
28
+ |---|---|---|
29
+ | Patch/minor dentro do intervalo | `5.90.5 → 5.104.1` | Em lote, com a suíte completa |
30
+ | Correção de segurança | `npm audit fix` | Prioridade; sem `--force` |
31
+ | Major isolado | `typescript 6 → 7` | Um por vez: ler o guia, atualizar, corrigir, testar, commitar |
32
+ | Major em cadeia | framework que exige outro major (`@nestjs/* 11 → 12` junto com `rxjs`, `typeorm`) | Juntos, na ordem que o guia indicar, num commit |
33
+ | Mudança de paradigma | pacote que virou ESM-only, troca de executor de testes | Tratar como migração planejada, com spike se necessário (`technical-spike`) |
34
+
35
+ ## Aplique
36
+
37
+ 1. **Linha de base verde**: rode build, testes e lint antes de mexer. Uma suíte vermelha antes da atualização esconde o que a atualização quebrou.
38
+ 2. **Compatíveis em lote**: atualize os patches e minors, rode a suíte, commit.
39
+ 3. **Majors um a um**, cada um com o próprio commit: leia o guia, atualize, corrija o que o compilador e os testes apontarem, rode a suíte completa (inclusive os testes de integração e o build de produção).
40
+ 4. **Conflitos de peer**: entenda quem exige o quê (`npm ls <pacote>`, `npm explain <pacote>`). Prefira esperar a versão compatível, ou declarar um `overrides` explícito e comentado, a usar `--force` ou `--legacy-peer-deps`, que escondem o conflito.
41
+ 5. **Ferramentas que não acompanharam**: quando um ecossistema ainda não suporta o major novo (por exemplo, um executor de testes que exige o compilador anterior), fique na última versão suportada e registre o motivo e o gatilho para revisitar.
42
+ 6. **Scripts de instalação**: verifique se pacotes nativos ainda instalam onde scripts de instalação estão bloqueados (npm 11+), e se trazem binários prontos.
43
+ 7. **Teste o que o usuário roda**: além da suíte, o build de produção, a aplicação subindo e o fluxo principal funcionando. Para bibliotecas, instale o pacote empacotado num projeto limpo.
44
+
45
+ ## Formato
46
+
47
+ ```
48
+ ## Inventário
49
+ | Pacote | Atual | Alvo | Tipo | Notas (changelog, peer, segurança) |
50
+
51
+ ## Plano
52
+ | # | Passo | Pacotes | Verificação | Commit |
53
+
54
+ ## Ficou para trás
55
+ | Pacote | Versão mantida | Motivo | Gatilho para revisitar |
56
+ ```
57
+
58
+ ## Próximo
59
+
60
+ - `testing`: a suíte completa é o gate de cada passo.
61
+ - `commit-message`: um commit `build(deps)` por passo; `!` quando a atualização muda o contrato do projeto.
62
+ - `release-notes`: atualizações que os usuários percebem (runtime mínimo, comportamento) entram nas notas.
63
+
64
+ ## No Forja
65
+
66
+ No Forja, depois de cada passo rode também `forja tools:doctor` e `forja project:wire --check` (atualizações podem mudar o runtime que os hooks e o MCP usam). Uma mudança de paradigma (pacote que virou ESM-only, troca do executor de testes) vira ADR em `memory/90-decisions/`, e o que ficou para trás entra na seção "Evidências e estado real" da spec da atualização.
67
+
68
+ ## Evite
69
+
70
+ - Atualizar tudo de uma vez e depurar o resultado.
71
+ - `npm audit fix --force` ou `--legacy-peer-deps` para calar um conflito.
72
+ - Atualizar major sem ler o guia de migração.
73
+ - Partir de uma suíte que já estava vermelha.
74
+ - Considerar pronto porque o `npm install` terminou sem erro.
75
+ - Deixar uma dependência para trás sem registrar o motivo.
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: docker-compose-review
3
+ description: Use quando escrever ou revisar arquivos do Docker Compose e Dockerfiles: verifica healthchecks e ordem de inicialização, redes e portas expostas, volumes, segredos, limites de recursos, higiene das imagens e paridade entre desenvolvimento e produção.
4
+ ---
5
+
6
+ # Revisão de Docker Compose
7
+
8
+ Arquivos Compose costumam começar como conveniência do desenvolvedor e, sem alarde, viram o mais próximo que existe de uma especificação de produção. A revisão verifica se os serviços sobem na ordem certa, expõem só o que devem, guardam os dados onde é seu lugar e se comportam em desenvolvimento como vão se comportar em produção.
9
+
10
+ A saída padrão é uma **tabela de achados e uma matriz de paridade**. Edite arquivos só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Escopo: `compose.yaml` / `docker-compose*.yml`, arquivos de override, os Dockerfiles que eles constroem, `.env.example`, e o que descreve a produção (manifests Kubernetes, um compose de produção, a documentação de deploy).
15
+ - Sintaxe da Compose Specification (sem `version:` no topo).
16
+ - Todo achado cita `arquivo:linha` e um motivo.
17
+ - Configuração de produção desconhecida vai para **Perguntas em aberto**; sem ela, a paridade não pode ser avaliada.
18
+
19
+ ## Checklist
20
+
21
+ **Inicialização e saúde**
22
+ - Cada serviço de longa duração tem um `healthcheck` que testa a prontidão (por exemplo, `pg_isready`, um `/healthz` HTTP), com `interval`, `timeout`, `retries` e `start_period`.
23
+ - `depends_on` usa `condition: service_healthy` (ou `service_completed_successfully` para jobs de migração). `depends_on` simples só ordena a subida, não espera.
24
+ - As migrações rodam como um serviço ou passo de execução única, não dentro do entrypoint da aplicação em toda réplica.
25
+ - A aplicação continua tentando reconectar: healthchecks não substituem resiliência.
26
+ - Política de `restart:` declarada.
27
+
28
+ **Redes e portas**
29
+ - Só os pontos de entrada publicam portas. Bancos e caches ficam em redes internas.
30
+ - Portas publicadas ligadas a `127.0.0.1` em desenvolvimento quando a exposição não é necessária.
31
+ - Redes separadas quando grupos de serviços não devem se falar.
32
+
33
+ **Volumes e dados**
34
+ - Volumes nomeados para dados (bancos); bind mounts só para código-fonte em desenvolvimento.
35
+ - Nenhum dado gravado na camada do container.
36
+ - Scripts de inicialização e dados de seed são idempotentes.
37
+
38
+ **Configuração e segredos**
39
+ - Configuração por ambiente, com `.env.example` documentando cada variável. O `.env` real fica fora do git.
40
+ - Segredos via `secrets:` ou o cofre de segredos da plataforma, nunca embutidos em imagens, `ARG`s ou arquivos versionados.
41
+ - Nada de credenciais de produção em arquivos de desenvolvimento.
42
+
43
+ **Imagens**
44
+ - Imagens base fixadas numa versão (e num digest em produção). Nada de `latest`.
45
+ - Builds multi-stage; imagem final mínima (distroless ou slim); para Node, só o build gerado e as dependências de produção (`npm ci --omit=dev`), nunca o toolchain de desenvolvimento nem source maps que você não distribui.
46
+ - Roda como um `USER` não root. Sistema de arquivos raiz somente leitura onde for possível.
47
+ - `.dockerignore` exclui `.git`, arquivos de ambiente locais e saídas de build.
48
+ - Ordem das camadas maximiza o cache: `package.json` + lockfile e o passo de instalação antes do código-fonte.
49
+
50
+ **Recursos**
51
+ - Limites de memória e CPU nos serviços que podem disparar. Rotação de logs configurada no driver de log.
52
+
53
+ ## Paridade dev/prod
54
+
55
+ A mesma imagem (construída uma vez) roda em todo lugar; só a configuração muda. Os acréscimos de desenvolvimento (hot reload, depuradores, bind mounts, painéis de administração) ficam em `compose.override.yaml` ou em profiles, não no arquivo base. Os serviços de apoio usam a mesma versão principal da produção (Postgres 16 localmente se a produção roda 16).
56
+
57
+ ## Formato
58
+
59
+ ```
60
+ ## Achados
61
+ | # | Arquivo:linha | Categoria | Severidade | Problema | Correção |
62
+ |---|---|---|---|---|---|
63
+
64
+ ## Matriz de paridade
65
+ | Serviço | Dev (imagem/versão, config) | Prod | Diferença | Risco |
66
+
67
+ ## Perguntas em aberto
68
+ ```
69
+
70
+ Severidade: Bloqueador (exposição de segredo, perda de dados, falha só em produção) · Maior · Menor · Detalhe.
71
+
72
+ ## Próximo
73
+
74
+ - `ci-pipeline-review` quando o CI constrói essas imagens ou sobe o stack.
75
+ - `release-checklist` para diferenças de configuração e versão antes de um deploy.
76
+ - `threat-modeling` para serviços expostos.
77
+
78
+ ## Evite
79
+
80
+ - Tags `latest`.
81
+ - Publicar portas de banco em `0.0.0.0`.
82
+ - Segredos em `environment:` versionados no repositório.
83
+ - `sleep` em entrypoints para esperar dependências.
84
+ - Rodar como root por padrão.
85
+ - Um stack de desenvolvimento em versões principais diferentes da produção.
@@ -0,0 +1,120 @@
1
+ ---
2
+ name: domain-modeling
3
+ description: Use quando modelar um domínio a partir de dados e funcionalidades propostos: sugere agregados, entidades e objetos de valor com propriedades tipadas, métodos derivados e invariantes.
4
+ ---
5
+
6
+ # Modelagem de Domínio
7
+
8
+ Transforma dados e funcionalidades propostos num modelo tático de domínio: agregados, entidades, objetos de valor, propriedades tipadas, comportamentos e regras de consistência.
9
+
10
+ A saída é uma **especificação do modelo**, não uma implementação. Não gere código além de assinaturas de tipos, a menos que o usuário peça.
11
+
12
+ ## Convenções
13
+
14
+ - Sempre escreva os termos de modelagem em pt-BR seguidos do en-US: Agregado (Aggregate), Raiz do Agregado (Aggregate Root), Entidade (Entity), Objeto de Valor (Value Object), Invariante (Invariant), Política (Policy), Evento de Domínio (Domain Event), Contexto Delimitado (Bounded Context), Linguagem Ubíqua (Ubiquitous Language).
15
+ - Nomeie tipos, propriedades e métodos na linguagem ubíqua do usuário (no idioma em que o domínio do usuário fala).
16
+ - Use os tipos da linguagem do código existente por padrão, a menos que o usuário indique outra linguagem. Os mapeamentos abaixo são para TypeScript.
17
+
18
+ ## Princípio central
19
+
20
+ Não dá para modelar o que você não entende. Uma regra de negócio errada não é salva por padrão nenhum. Antes de classificar qualquer coisa, entenda o domínio; o que não foi dito precisa ser marcado como **suposição** ou **pergunta**, nunca inventado como fato.
21
+
22
+ ## Processo
23
+
24
+ ### 1. Extrair a linguagem ubíqua
25
+ A partir dos dados e funcionalidades informados, liste os substantivos (candidatos a conceitos), os verbos (candidatos a comportamentos) e as regras explícitas ou implícitas. Identifique termos ambíguos (por exemplo, um "usuário" que é ao mesmo tempo credencial, cliente e funcionário) e separe-os.
26
+
27
+ ### 2. Delimitar contextos
28
+ Agrupe conceitos em Contextos Delimitados quando o mesmo termo carrega significados ou regras diferentes. Um contexto é uma fronteira de **modelo**, não de implantação: pode viver num monólito como pasta/módulo. Não proponha microsserviços por causa disso.
29
+ Quando o domínio ainda não estiver claro, rode `event-storming` antes. Para mapear como os contextos se relacionam (Kernel Compartilhado, Camada Anticorrupção, Cliente–Fornecedor…), use `bounded-context-mapping`.
30
+
31
+ ### 3. Classificar cada conceito
32
+
33
+ | Conceito | Critério |
34
+ |---|---|
35
+ | Entidade | Tem uma identidade que persiste através das mudanças; tem ciclo de vida. |
36
+ | Objeto de Valor | Definido só pelos seus atributos; imutável; igualdade por valor; carrega a própria validação e comportamento. |
37
+ | Agregado | Fronteira de consistência transacional. A raiz é o único ponto de entrada para mudanças. |
38
+
39
+ Heurísticas:
40
+ - Mantenha os agregados pequenos. Se duas coisas não precisam estar consistentes na mesma transação, são agregados separados.
41
+ - Agregados referenciam outros agregados **por ID**, nunca pelo objeto.
42
+ - Promova um primitivo a Objeto de Valor quando houver uma regra, formato ou comportamento associado (por exemplo, CPF/CNPJ, Email, Dinheiro, Período). Sem regra, mantenha o primitivo; não crie objetos de valor por ritual.
43
+ - Pares de campos que só fazem sentido juntos (início/fim, valor/moeda, latitude/longitude) são fortes candidatos a Objeto de Valor.
44
+
45
+ ### 4. Tipar as propriedades
46
+ Para cada propriedade, defina nome, tipo, se é obrigatória e sua origem (informada, derivada, gerada pelo sistema).
47
+
48
+ Mapeamentos padrão em TypeScript:
49
+ - Identificador: tipo com marca (branded) sobre `string` (por exemplo, `type ProjectId = string & { readonly __brand: 'ProjectId' }`), para que um `ProjectId` não seja aceito onde se espera um `CustomerId`.
50
+ - Data/hora: `Date` tratado como instante em UTC (ou `Temporal` onde o projeto já o usa); data sem horário, quando relevante, como objeto de valor próprio.
51
+ - Duração: objeto de valor ou número em milissegundos com a unidade no nome (`durationMs`).
52
+ - Dinheiro: objeto de valor `Money` com o valor em unidades menores (centavos) como `bigint` ou inteiro seguro, mais a moeda. Nunca número de ponto flutuante.
53
+ - Enumerações/estados: união de literais de string (`'open' | 'closed'`), ou o padrão que o código já usa.
54
+ - Opcional: `?`/`undefined` só quando a ausência tem significado no domínio.
55
+
56
+ ### 5. Definir comportamentos
57
+ - **Métodos derivados**: calculados a partir das propriedades, nunca armazenados (por exemplo, `Period.durationMs(): number` = fim − início; `Period.contains(at: Date): boolean`).
58
+ - **Comportamentos de domínio**: verbos da linguagem ubíqua que mudam o estado (por exemplo, `Project.close(at: Date): Result<void, ProjectError>`, ou lançando um erro de domínio tipado, conforme o padrão do código), em vez de setters genéricos. Evite modelos anêmicos.
59
+ - Transições de estado: descreva a máquina de estados sempre que houver um status.
60
+
61
+ ### 6. Definir invariantes
62
+ Para cada regra de consistência, enuncie:
63
+ - a regra em linguagem de negócio;
64
+ - onde ela é garantida (construtor do Objeto de Valor, método da Raiz do Agregado);
65
+ - quando é verificada (na criação, numa transição específica, sempre).
66
+
67
+ Exemplo: "O fim não pode ser antes do início" → garantida na criação de `Period`; um `Period` inválido não pode existir.
68
+
69
+ Prefira tornar os estados inválidos irrepresentáveis com Objetos de Valor a espalhar validações.
70
+
71
+ ### 7. Extrair políticas
72
+ Regras de negócio que variam, são configuráveis ou tendem a mudar (percentuais, limites, critérios de elegibilidade) viram uma Política explícita e nomeada, em vez de condicionais enterradas nos métodos. Quem procurar "onde esse limite está definido" deve encontrá-lo pelo nome.
73
+
74
+ ### 8. Eventos de domínio (opcional)
75
+ Sugira Eventos de Domínio só quando outra parte do sistema precisar reagir a um fato. Nomeie-os no passado (`ProjectClosed`). Não proponha Event Sourcing ou CQRS sem uma necessidade concreta.
76
+
77
+ ## Formato de saída
78
+
79
+ ```
80
+ ## Contexto: <Nome>
81
+
82
+ ### Agregado: <Nome> (raiz: <Entidade>)
83
+ Responsabilidade: <uma frase>
84
+
85
+ **Propriedades**
86
+ | Propriedade | Tipo | Obrigatória | Origem | Notas |
87
+
88
+ **Métodos derivados**
89
+ - `nome(): Tipo` — <cálculo>
90
+
91
+ **Comportamentos**
92
+ - `verbo(params): Result<…>` — <efeito e transição>
93
+
94
+ **Invariantes**
95
+ - <regra> — garantida em <onde>, verificada <quando>
96
+
97
+ #### Entidades internas / Objetos de Valor
98
+ <mesma estrutura, enxuta>
99
+
100
+ ### Políticas
101
+ - <Nome>: <regra, parâmetros>
102
+
103
+ ### Suposições e perguntas em aberto
104
+ - <o que foi suposto e precisa ser validado com o negócio>
105
+ ```
106
+
107
+ Sempre feche com **Suposições e perguntas em aberto**. Elas fazem parte do modelo, não são um apêndice: mostram onde ainda falta conhecimento do domínio.
108
+
109
+ ## No Forja
110
+
111
+ No Forja, o modelo de cada contexto fica em `memory/30-domains/<contexto>/context.md` (agregados, invariantes, políticas e o mapa de onde cada um vive no código). Depois de gravar, rode `forja sync:universal`; `forja memory:audit` verifica se o mapa aponta para código que existe.
112
+
113
+ ## Evite
114
+
115
+ - Inventar regras de negócio e apresentá-las como fato.
116
+ - Um agregado gigante que guarda tudo.
117
+ - Um Objeto de Valor para cada primitivo, sem regra que o justifique.
118
+ - Setters genéricos em vez de comportamentos nomeados.
119
+ - Padrões aplicados por obrigação. Saber onde usá-los importa mais do que saber como.
120
+ - Gerar uma implementação completa sem que peçam.
@@ -0,0 +1,95 @@
1
+ ---
2
+ name: event-storming
3
+ description: Use quando um domínio ainda não está claro antes de modelá-lo: conduz uma sessão de Event Storming com o usuário como especialista do domínio, descobrindo eventos de domínio, comandos, atores, políticas, modelos de leitura e pontos críticos, e propõe agregados e fronteiras de contexto candidatos.
4
+ ---
5
+
6
+ # Event Storming
7
+
8
+ Descobre como um negócio funciona contando a sua história como uma sequência de fatos que aconteceram. Eventos são mais fáceis de enunciar para os especialistas do domínio do que entidades ou tabelas, e as lacunas entre eles revelam as regras que ninguém escreveu.
9
+
10
+ O usuário é o especialista do domínio. Pergunte, não suponha. A saída é uma **linha do tempo de eventos estruturada**, não um modelo; os agregados vêm por último e são só candidatos.
11
+
12
+ ## Convenções
13
+
14
+ - Termos de modelagem em pt-BR seguidos do en-US, como em `domain-modeling`: Evento de Domínio (Domain Event), Comando (Command), Ator (Actor), Política (Policy), Modelo de Leitura (Read Model), Sistema Externo (External System), Ponto Crítico (Hotspot), Agregado (Aggregate).
15
+ - Nomes na linguagem ubíqua do usuário. Eventos no passado ("Pedido Confirmado", "Order Confirmed"); comandos no imperativo ("Confirmar Pedido", "Confirm Order").
16
+ - Entradas: achados brutos de `requirements-elicitation`, documentos ou as próprias palavras do usuário.
17
+ - Tudo o que o usuário não confirmou é um **ponto crítico**, nunca um fato.
18
+
19
+ ## Níveis
20
+
21
+ | Nível | Pergunta | Use quando |
22
+ |---|---|---|
23
+ | Visão geral (big picture) | O que acontece no fluxo inteiro do negócio? | Iniciar um produto ou uma área grande; encontrar fronteiras de contexto |
24
+ | Processo | Como este processo funciona, regra a regra? | Desenhar uma funcionalidade ou um caso de uso |
25
+ | Design | Qual agregado aceita cada comando e garante qual regra? | Logo antes de `domain-modeling` |
26
+
27
+ Diga qual nível você está conduzindo. Não pule para o nível de design antes de a linha do tempo estar estável.
28
+
29
+ ## Processo
30
+
31
+ Conduza em rodadas de perguntas com o usuário. Mostre a linha do tempo após cada rodada.
32
+
33
+ ### 1. Exploração caótica
34
+ Peça todos os eventos que o usuário conseguir lembrar no escopo, em qualquer ordem. Estimule com: "O que acontece antes disso?", "O que acontece depois?", "O que pode dar errado?", "O que acontece no fim do dia / do mês?". Colete, não julgue.
35
+
36
+ ### 2. Impor a linha do tempo
37
+ Ordene os eventos no tempo. Funda duplicados; separe eventos que escondem dois fatos. Marque os eventos pivô, onde o fluxo muda de fase ou de dono (por exemplo, "Pagamento Capturado"). Eles costumam marcar fronteiras de contexto.
38
+
39
+ ### 3. Comandos e atores
40
+ Para cada evento: quem ou o que o causou? Um comando emitido por um **ator** (pessoa/papel), um **sistema externo**, uma **política** ou o tempo ("Fim do Mês Atingido").
41
+
42
+ ### 4. Políticas
43
+ Reações que ligam eventos a comandos: "Sempre que <evento>, então <comando>". Pergunte se cada uma é automática, manual ou condicional. As políticas são onde moram as regras de negócio escondidas.
44
+
45
+ ### 5. Modelos de leitura
46
+ De que informação o ator precisa para decidir emitir o comando? Esses são os modelos de leitura (telas, relatórios, consultas).
47
+
48
+ ### 6. Pontos críticos
49
+ Marque cada conflito, incógnita, discordância, exceção ou dor. Cada um vira uma pergunta para o usuário ou um candidato a `RN-NN` para `requirements-gathering`.
50
+
51
+ ### 7. Agregados e fronteiras candidatos (só no nível de design)
52
+ Agrupe comandos e eventos em torno da coisa que precisa estar consistente para aceitar o comando. Essa coisa é um agregado candidato. Agrupe a linha do tempo em áreas onde a linguagem e a propriedade permanecem as mesmas. Esses são os contextos delimitados candidatos.
53
+
54
+ ## Formato
55
+
56
+ ```
57
+ ## Escopo e nível
58
+ <processo ou área> — <visão geral | processo | design>
59
+
60
+ ## Linha do tempo
61
+ | # | Evento | Disparado por (comando) | Ator / sistema / política / tempo | Modelo de leitura necessário | Notas |
62
+ |---|---|---|---|---|---|
63
+
64
+ ## Políticas
65
+ - Sempre que <evento>, então <comando> (<automática | manual | condicional: …>)
66
+
67
+ ## Pontos críticos
68
+ | # | Onde | Pergunta / conflito | Quem responde |
69
+
70
+ ## Agregados candidatos (nível de design)
71
+ | Agregado | Comandos aceitos | Eventos emitidos | Regras que protege |
72
+
73
+ ## Contextos candidatos
74
+ <eventos pivô e mudanças de linguagem que sugerem fronteiras>
75
+ ```
76
+
77
+ Um `flowchart LR` em Mermaid da linha do tempo é opcional, para fluxos com muitas ramificações.
78
+
79
+ ## Próximo
80
+
81
+ - `bounded-context-mapping` com os contextos candidatos.
82
+ - `domain-modeling` com os agregados, regras e eventos candidatos.
83
+ - `requirements-gathering` com os pontos críticos e as políticas como regras a confirmar.
84
+
85
+ ## No Forja
86
+
87
+ No Forja, grave a linha do tempo e os pontos críticos em `memory/30-domains/<contexto>/event-storming.md` e rode `forja sync:universal`. Os pontos críticos viram perguntas na spec (`specs/<slug>/spec.md`, §7) até serem respondidos.
88
+
89
+ ## Evite
90
+
91
+ - Começar por entidades ou tabelas.
92
+ - Eventos no presente ou como CRUD ("Pedido Atualizado"). Pergunte o que de fato aconteceu.
93
+ - Preencher lacunas com regras plausíveis. Marque um ponto crítico.
94
+ - Desenhar agregados antes de a linha do tempo estar acordada.
95
+ - Eventos técnicos ("Linha Inserida", "Mensagem Enviada ao Kafka") nos níveis de visão geral ou de processo.
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: executive-writing
3
+ description: Use quando uma análise consolidada precisa virar comunicação orientada à decisão para gestores, conselhos ou times: resumos executivos, pareceres, memorandos, apresentações e comunicados de decisão, com fatos, alternativas, recomendação, plano de ação e limitações.
4
+ ---
5
+
6
+ # Redação Executiva
7
+
8
+ Transforma análises complexas em comunicação clara, curta e orientada à decisão. Entrada: análises, diagnósticos e recomendações consolidados (de `requirements-gathering`, `architecture-decision-record`, `technical-spike`, `lgpd-compliance` ou do usuário). Saída: a versão final para gestores, o conselho ou os times operacionais.
9
+
10
+ O texto serve a uma decisão. Se o leitor termina e não sabe o que decidir ou o que fazer em seguida, o texto falhou.
11
+
12
+ ## Convenções
13
+
14
+ - Termos em pt-BR seguidos do en-US: Resumo Executivo (Executive Summary), Parecer (Opinion), Memorando (Memo), Comunicado de Decisão (Decision Announcement), Pirâmide de Minto (Minto Pyramid), Sumário Decisório (Decision Brief), Plano de Ação (Action Plan), Trade-off.
15
+ - Toda afirmação é marcada pela natureza quando isso importa: **fato** (com fonte), **hipótese**, **inferência**, **lacuna**.
16
+ - Escreva no vocabulário do leitor: executivo (impacto, custo, risco, prazo) ou operacional (quem faz o quê, quando, como).
17
+
18
+ ## Princípio central
19
+
20
+ Resposta primeiro, sustentação depois (Pirâmide de Minto). Comece pela decisão ou recomendação, depois os poucos argumentos que a sustentam, depois a evidência. Sintetize, não resuma: corte redundância e jargão, mas nunca precisão ou rastreabilidade.
21
+
22
+ ## Processo
23
+
24
+ ### 1. Contexto e leitor
25
+ Qual é a situação, o que precisa ser decidido, quem decide e do que precisa para decidir. Leitores executivos e operacionais recebem textos diferentes.
26
+
27
+ ### 2. Inventariar o material
28
+ Dados, documentos, regras e restrições disponíveis. Separe fatos, hipóteses, inferências e lacunas. Nada é acrescentado que o material não sustente.
29
+
30
+ ### 3. Enquadrar a decisão
31
+ Uma frase: o que precisa ser decidido ou analisado. Se não há decisão, declare a finalidade (informar, alinhar, registrar).
32
+
33
+ ### 4. Analisar
34
+ Diagnóstico estruturado: causas, impactos, relações. Distinga correlação de causalidade. Questione práticas mantidas só por hábito.
35
+
36
+ ### 5. Comparar alternativas
37
+ Opções viáveis lado a lado, cada uma com benefícios, desvantagens, custo, risco e dependências. Explicite os trade-offs. Não fazer nada é uma alternativa quando é viável. Tecnologia nunca é a resposta automática.
38
+
39
+ ### 6. Recomendar
40
+ Específica, priorizada, justificada. Ligue cada recomendação a um resultado mensurável.
41
+
42
+ ### 7. Plano de ação e limitações
43
+ Ações com responsáveis sugeridos, prazos, prioridades, dependências e indicadores de sucesso. Depois: dados faltantes, incertezas e pontos que precisam de validação, e quem precisa validá-los.
44
+
45
+ ### 8. Moldar para o entregável
46
+ Escolha o formato e enxugue para ele (veja abaixo). Linha narrativa: o título de cada seção enuncia a sua conclusão, de modo que ler só os títulos conte a história.
47
+
48
+ ## Entregáveis
49
+
50
+ - **Resumo executivo**: uma página ou menos; recomendação, impacto, risco, próximos passos.
51
+ - **Parecer**: estrutura completa; raciocínio e limitações explícitos.
52
+ - **Memorando**: uma página; contexto, decisão necessária, recomendação, ações.
53
+ - **Apresentação**: linha narrativa, uma mensagem por slide, o título enuncia a conclusão.
54
+ - **Comunicado de decisão**: o que foi decidido, por quê, o que muda para quem, a partir de quando.
55
+
56
+ ## Formato de saída
57
+
58
+ ```
59
+ # <Título que enuncia a conclusão>
60
+
61
+ ## Resumo
62
+ <Recomendação em 2–3 frases: decisão, impacto, risco, próximo passo.>
63
+
64
+ ## Contexto
65
+ <Situação em poucas linhas.>
66
+
67
+ ## Problema ou decisão
68
+ <O que precisa ser decidido.>
69
+
70
+ ## Evidências
71
+ - <fato> — <fonte>
72
+
73
+ ## Análise
74
+ <Causas, impactos, relações. Hipóteses marcadas como tal.>
75
+
76
+ ## Alternativas
77
+ | Opção | Benefícios | Desvantagens | Custo | Risco | Dependências |
78
+
79
+ ## Recomendação
80
+ <Específica, priorizada, justificada.>
81
+
82
+ ## Plano de ação
83
+ | Ação | Responsável sugerido | Prazo | Prioridade | Depende de | Indicador |
84
+
85
+ ## Limitações
86
+ - <dado faltante / incerteza> — validar com <quem>
87
+ ```
88
+
89
+ ## Evite
90
+
91
+ - Inventar dados, fatos, números ou evidências.
92
+ - Apresentar uma hipótese como conclusão.
93
+ - Recomendações genéricas ("melhorar a comunicação", "investir em tecnologia").
94
+ - Propor tecnologia como solução automática.
95
+ - Omitir custos, riscos, restrições ou efeitos colaterais.
96
+ - Tratar correlação como causalidade.
97
+ - Enterrar a recomendação no fim.
98
+ - Redundância, jargão e rodeios que escondem a mensagem.
99
+ - Listar várias alternativas sem compará-las.