forjajs 5.0.0 → 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 (171) hide show
  1. package/CHANGELOG.md +68 -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/create-memory-nest-kit.js +0 -0
  50. package/dist/bin/forja.js +0 -0
  51. package/dist/bin/init-project.js +1 -0
  52. package/dist/lib/core/journey.js +10 -0
  53. package/dist/lib/generators/memory-generator.d.ts +0 -11
  54. package/dist/lib/generators/memory-generator.js +5 -161
  55. package/dist/lib/generators/readme-generator.js +1 -1
  56. package/dist/lib/llm/json-output.d.ts +14 -0
  57. package/dist/lib/llm/json-output.js +77 -0
  58. package/dist/lib/project-upgrade.d.ts +0 -4
  59. package/dist/lib/project-upgrade.js +19 -1
  60. package/dist/lib/project-wiring.d.ts +8 -0
  61. package/dist/lib/project-wiring.js +74 -2
  62. package/dist/lib/validators/structure-validator.js +0 -1
  63. package/dist/packages/llm/src/index.js +12 -2
  64. package/dist/scripts/llm-fit.js +23 -1
  65. package/dist/scripts/project-upgrade.js +9 -6
  66. package/docs/init-project.md +1 -1
  67. package/docs/llm-fit-loop.md +16 -0
  68. package/memory/90-decisions/0086-projeto-conectado-e-jornada-como-gate.md +1 -1
  69. package/memory/90-decisions/0088-templates-validados.md +3 -0
  70. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  71. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  72. package/package.json +2 -2
  73. package/specs/skills-do-projeto/plan.md +40 -0
  74. package/specs/skills-do-projeto/spec.md +63 -0
  75. package/specs/skills-do-projeto/tasks.md +27 -0
  76. package/templates/project/AGENTS.md +9 -0
  77. package/templates/project/agents/context-engineer.md +3 -0
  78. package/templates/project/agents/governance.md +3 -0
  79. package/templates/project/agents/marketing.md +3 -0
  80. package/templates/project/agents/orchestrator.md +3 -0
  81. package/templates/project/agents/product.md +3 -0
  82. package/templates/project/agents/sdd-architect.md +3 -0
  83. package/templates/project/skills/README.md +14 -0
  84. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  85. package/templates/project/skills/api-design/SKILL.md +77 -0
  86. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  87. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  88. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  89. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  90. package/templates/project/skills/commit-message/SKILL.md +143 -0
  91. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  92. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  93. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  94. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  95. package/templates/project/skills/event-storming/SKILL.md +95 -0
  96. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  97. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  98. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  99. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  100. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  101. package/templates/project/skills/observability/SKILL.md +93 -0
  102. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  103. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  104. package/templates/project/skills/pull-request/SKILL.md +101 -0
  105. package/templates/project/skills/query-performance/SKILL.md +83 -0
  106. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  107. package/templates/project/skills/release-notes/SKILL.md +87 -0
  108. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  109. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  110. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  111. package/templates/project/skills/testing/SKILL.md +109 -0
  112. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  113. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  114. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  115. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  116. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  117. package/templates/project/skills/web-performance/SKILL.md +72 -0
  118. package/boilerplates/02-saas-starter/.env.example +0 -25
  119. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  120. package/boilerplates/02-saas-starter/INFO.md +0 -252
  121. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  122. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  123. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  124. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  125. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  126. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  127. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  128. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  129. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  130. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  131. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  132. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  133. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  134. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  135. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  136. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  137. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  138. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  139. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  140. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  141. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  142. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  143. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  144. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  145. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  146. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  147. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  148. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  149. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  150. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  151. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  152. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  153. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  154. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  155. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  156. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  157. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  158. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  159. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  160. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  161. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  162. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  163. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  164. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  165. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  166. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  167. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  168. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  169. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  170. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  171. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: prompt-spec
3
+ description: Use quando passar trabalho de implementação para um agente de IA de código: transforma uma história ou requisito em prompts diretivos, prontos para colar, separados para backend e frontend, que exigem que o agente analise o código existente antes de mudar qualquer coisa e definem escopo, restrições e critérios de pronto.
4
+ ---
5
+
6
+ # Especificação de Prompt
7
+
8
+ Um agente de código faz o que o prompt torna fácil. Um prompt vago recebe uma implementação plausível que ignora os padrões do código, adiciona dependências e mexe em arquivos não relacionados. Um prompt diretivo declara o objetivo, obriga o agente a aprender o código antes, cerca o escopo e define "pronto" como comandos que passam.
9
+
10
+ A saída padrão é **um prompt por lado (backend, frontend), pronto para colar**, mais a ordem de execução. Esta skill escreve prompts; não executa o agente.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: uma história com critérios de aceite de `backlog-slicing`; o contrato de `api-design`; o modelo de `domain-modeling`; o próprio repositório (leia o README, o CLAUDE.md/AGENTS.md e a estrutura antes de escrever).
15
+ - Idioma do prompt: o do usuário, a menos que a documentação do código e os arquivos de agente estejam em outro.
16
+ - Frases imperativas e específicas. Sem gentilezas de enchimento, sem texto motivacional.
17
+ - Referencie caminhos, tipos e comandos reais do repositório. Leia-os antes; nunca invente um arquivo ou script.
18
+ - Um prompt = uma história ou fatia. Um prompt que precisa de "e também…" são dois prompts.
19
+
20
+ ## Por que separar backend e frontend
21
+
22
+ Eles têm bases de código ou pastas, convenções, testes e revisores diferentes. O **contrato da API é a costura**: o prompt de backend o implementa, o prompt de frontend o consome. Os dois citam o mesmo contrato, então podem rodar em paralelo ou em sequência sem divergir. Rode o backend primeiro quando o contrato é novo; em paralelo quando ele já existe.
23
+
24
+ ## Estrutura do prompt
25
+
26
+ Todo prompt tem estas seções, nesta ordem:
27
+
28
+ 1. **Objetivo**: uma ou duas frases, o resultado visível ao usuário. Referencie o ID da história.
29
+ 2. **Passo 0, analisar antes de implementar** (obrigatório): liste o que ler e o que relatar **antes de escrever código**:
30
+ - os arquivos e módulos que tratam de funcionalidades parecidas (nomeie-os);
31
+ - os padrões a copiar (tratamento de erro, validação, testes, nomes);
32
+ - os arquivos de agente (CLAUDE.md, AGENTS.md) e as configurações dos linters;
33
+ - um plano curto: arquivos a criar ou alterar, e por quê.
34
+ Instrua o agente a parar depois do relatório se algo contradisser o prompt.
35
+ 3. **Contexto**: as regras do domínio (`RN-NN`), o contrato (especificação do endpoint ou tipos), os ADRs relevantes. Cite-os; não parafraseie regras.
36
+ 4. **Requisitos**: os critérios de aceite em Dado/Quando/Então, literalmente.
37
+ 5. **Restrições**:
38
+ - seguir as convenções encontradas no passo 0;
39
+ - nenhuma dependência nova sem perguntar;
40
+ - os testes vão junto com a mudança (conforme `testing` / `ts-testing`);
41
+ - nada de refatorações, renomeações ou formatação não relacionadas;
42
+ - nenhuma mudança no contrato (o outro lado depende dele).
43
+ 6. **Fora do escopo**: o que não fazer, explicitamente (o outro lado, histórias futuras, migrações que são de outra pessoa).
44
+ 7. **Pronto quando**: comandos que precisam passar (`tsc --noEmit`, `npm test`, linters, build, como o repositório os define), e os critérios de aceite demonstrados.
45
+ 8. **Pare e pergunte se**: o contrato for impossível como escrito, uma regra for ambígua, a mudança precisar de uma migração ou de uma dependência nova, ou o passo 0 encontrar uma implementação existente.
46
+ 9. **Entregue**: um resumo dos arquivos alterados, como foi testado e uma mensagem de commit proposta (`commit-message`).
47
+
48
+ ## Formato
49
+
50
+ ````
51
+ ## Ordem de execução
52
+ <backend → frontend | paralelo>, porque <motivo>
53
+
54
+ ## Prompt de backend
55
+ ```text
56
+ <seções 1–9>
57
+ ```
58
+
59
+ ## Prompt de frontend
60
+ ```text
61
+ <seções 1–9>
62
+ ```
63
+ ````
64
+
65
+ Omita um lado quando a história só mexe no outro, e diga isso.
66
+
67
+ ## Próximo
68
+
69
+ - Depois que o agente rodar: `ts-code-review` (ou a revisão da linguagem), depois `commit-message` e `pull-request`.
70
+ - Se o passo 0 revelar uma questão de design: `architecture-decision-record` ou `technical-spike` antes de continuar.
71
+
72
+ ## No Forja
73
+
74
+ No Forja, além de colar o prompt, registre a entrega como handoff (ADR-0005), com os 7 campos: `forja hermes:handoff '<json>'`, mapeando *context* ← Contexto, *acceptance* ← Requisitos + Pronto quando, *constraints* ← Restrições + Fora do escopo, *return* ← Entregue. Quem recebe lista os seus com `forja agent:route list --open --mine` e fecha com `forja agent:route done <id>`.
75
+
76
+ ## Evite
77
+
78
+ - "Implemente a funcionalidade X" sem contexto.
79
+ - Pular o passo 0, ou deixar o agente codificar antes de relatar a análise.
80
+ - Um prompt só para backend e frontend juntos.
81
+ - Caminhos, scripts ou tipos que não existem no repositório.
82
+ - Deixar o agente mudar o contrato ou adicionar dependências em silêncio.
83
+ - "Pronto" sem comandos que o provem.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: pull-request
3
+ description: Use quando abrir um pull request ou escrever a descrição dele: lê os commits e o diff do branch, escreve um título e um corpo com o porquê, o quê, como testar, riscos e rollback, e cria o PR só depois da aprovação.
4
+ ---
5
+
6
+ # Pull Request
7
+
8
+ Um pull request pede a um revisor que confie numa mudança. A descrição dá a ele o que o diff não consegue: por que a mudança existe, onde olhar, como verificá-la e o que acontece se der errado.
9
+
10
+ A saída padrão é um **título e um corpo propostos**. Crie o PR só depois que o usuário aprovar.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: os commits do branch (escritos com `commit-message`), os resultados de teste de `testing`, os IDs de requisito (`RF-NN`, `RN-NN`) de `requirements-gathering`, ADRs quando houve uma decisão.
15
+ - Idioma: o usado nos PRs ou commits recentes. Inglês quando não houver histórico.
16
+ - As regras do repositório prevalecem: `.github/pull_request_template.md`, `CONTRIBUTING.md`. Se houver um template, preencha-o em vez de usar o formato abaixo.
17
+
18
+ ## Reúna o contexto
19
+
20
+ Somente leitura, antes de redigir:
21
+
22
+ 1. `git branch --show-current` e o branch base (normalmente `main`).
23
+ 2. `git log <base>..HEAD --oneline`: a história do branch.
24
+ 3. `git diff <base>...HEAD --stat`, e depois o diff dos arquivos que carregam a mudança.
25
+ 4. `git status`: trabalho sem commit significa que o branch não está pronto. Diga isso; não abra o PR.
26
+ 5. Se o branch já foi enviado (`git rev-parse --abbrev-ref @{u}`).
27
+ 6. PRs mesclados recentes (`gh pr list --state merged -L 5`), para o tom e o estilo de título.
28
+
29
+ ## Título
30
+
31
+ - No formato Conventional Commits, como o assunto de um commit: `feat(reports): add CSV export`.
32
+ - Um branch com um commit só reutiliza o assunto desse commit.
33
+ - Um branch com vários commits recebe um assunto para o resultado inteiro, não para o último commit.
34
+ - `!` quando qualquer commit do branch for incompatível.
35
+
36
+ ## Regras do corpo
37
+
38
+ - **Porquê primeiro.** Uma ou duas frases sobre o problema. Ligue o ticket e os IDs de requisito.
39
+ - **O quê**, no nível que o revisor precisa: a abordagem e os arquivos que a carregam. Não uma lista arquivo por arquivo.
40
+ - **Como testar**: passos que o revisor consegue rodar, com comandos e resultados esperados. Declare o que foi rodado e o resultado. Nunca afirme que os testes passaram sem rodá-los.
41
+ - **Riscos e rollback**: o que pode quebrar, quem é afetado, como desfazer (revert, feature flag, rollback de migração de `data-migrations`).
42
+ - **Mudanças incompatíveis**: o que quebra e como os consumidores migram.
43
+ - **Capturas de tela ou gravações** quando a interface muda.
44
+ - **Orientação de revisão** para PRs grandes: por onde começar, o que pode ser lido por cima.
45
+ - Mantenha fácil de varrer com os olhos: títulos e marcadores curtos. Apague as seções vazias.
46
+
47
+ ## Tamanho
48
+
49
+ Um PR que não pode ser revisado de uma vez (cerca de 400 linhas alteradas de código real) deve ser dividido. Proponha a divisão por grupos de commits ou por fatia vertical de `backlog-slicing`. Arquivos gerados, lockfiles e movimentações não contam, mas mencione-os.
50
+
51
+ ## Formato
52
+
53
+ ```markdown
54
+ ## Por quê
55
+ <problema, em uma ou duas frases>. Refs: <ticket>, <RF-NN>
56
+
57
+ ## O quê
58
+ - <abordagem e mudança principal>
59
+ - <mudança secundária>
60
+
61
+ ## Como testar
62
+ 1. <comando ou passo> → <resultado esperado>
63
+
64
+ Rodado: <comando de teste> — <resultado>
65
+
66
+ ## Riscos e rollback
67
+ - Risco: <o que pode quebrar, para quem>
68
+ - Rollback: <revert / flag / passo de migração>
69
+
70
+ ## Mudanças incompatíveis
71
+ <o que quebra e como migrar>
72
+ ```
73
+
74
+ ## Fluxo
75
+
76
+ 1. Reúna o contexto.
77
+ 2. Redija título e corpo; sinalize uma divisão se o PR for grande demais.
78
+ 3. Mostre-os ao usuário.
79
+ 4. Com a aprovação: envie o branch se necessário (`git push -u origin <branch>`) e crie o PR com um heredoc:
80
+ ```sh
81
+ gh pr create --base <base> --title "<título>" --body-file - <<'EOF'
82
+ <corpo>
83
+ EOF
84
+ ```
85
+ 5. Mostre a URL do PR.
86
+
87
+ Crie como rascunho (`--draft`) quando o usuário disser que o trabalho não terminou. Nunca faça merge, force-push ou peça revisores, a menos que peçam.
88
+
89
+ ## Próximo
90
+
91
+ Depois do merge, `release-notes` transforma os commits mesclados numa versão e num changelog.
92
+
93
+ ## Evite
94
+
95
+ - Repetir a lista de commits como corpo.
96
+ - "Veja o código" ou uma descrição vazia.
97
+ - Afirmar que os testes passaram sem rodá-los.
98
+ - Esconder mudanças arriscadas num PR grande e não relacionado.
99
+ - Inventar IDs de ticket ou capturas de tela.
100
+ - Abrir o PR, enviar o branch ou pedir revisores sem aprovação.
101
+ - Ignorar o template de PR do repositório.
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: query-performance
3
+ description: Use quando uma consulta SQL está lenta ou um banco está sob carga: lê planos de EXPLAIN ANALYZE, encontra a causa (índices faltando, estimativas ruins, predicados não sargáveis, N+1, paginação por offset) e propõe índices e reescritas ordenados, com verificação.
4
+ ---
5
+
6
+ # Desempenho de Consultas
7
+
8
+ Uma consulta lenta é um problema de plano até prova em contrário. O plano mostra o que o banco de fato fez. Adivinhar índices sem lê-lo aumenta o custo de escrita e muitas vezes não ajuda.
9
+
10
+ A saída padrão é um **diagnóstico e correções ordenadas**. Crie índices ou altere código só quando o usuário pedir, e crie índices via `data-migrations`.
11
+
12
+ ## Convenções
13
+
14
+ - O dialeto padrão é PostgreSQL. Nomeie o dialeto quando o conselho for específico dele.
15
+ - Entradas: a consulta (com valores reais dos parâmetros), o plano, o esquema e os índices (de `data-migrations`), o tamanho das tabelas e com que frequência a consulta roda (de `observability` ou `pg_stat_statements`).
16
+ - Nunca rode `EXPLAIN ANALYZE` em escritas (`INSERT`/`UPDATE`/`DELETE`) em produção. Ele as executa. Use uma transação com `ROLLBACK`, ou uma cópia.
17
+
18
+ ## Reúna
19
+
20
+ 1. A consulta com parâmetros realistas, não placeholders.
21
+ 2. `EXPLAIN (ANALYZE, BUFFERS, VERBOSE)` sobre dados do tamanho da produção. Um plano de um banco de desenvolvimento com 100 linhas não diz nada.
22
+ 3. `\d+ <tabela>` para colunas e índices; quantidade de linhas.
23
+ 4. Frequência × duração do `pg_stat_statements`: uma consulta de 5 ms rodando 10.000 vezes por minuto importa mais do que um relatório mensal de 2 s.
24
+
25
+ ## Leia o plano
26
+
27
+ Leia de baixo para cima; encontre o nó onde vai a maior parte do tempo (`actual time` × `loops`).
28
+
29
+ | Sinal | Causa provável |
30
+ |---|---|
31
+ | Estimativa `rows=` diferente de `actual rows` em 10× ou mais | Estatísticas desatualizadas ou insuficientes; colunas correlacionadas |
32
+ | `Seq Scan` com filtro seletivo numa tabela grande | Índice faltando, ou um predicado que o índice não consegue usar |
33
+ | `Rows Removed by Filter` grande | Índice nas colunas erradas, ou nenhum índice |
34
+ | `Nested Loop` com muitos `loops` sobre um lado interno grande | Estimativa ruim; índice faltando na chave do join |
35
+ | `Sort` / `Hash` com `external merge` ou `Disk:` | `work_mem` pequeno demais, ou ordenando mais linhas que o necessário |
36
+ | `Buffers: read` alto vs. `hit` | Cache frio ou dados demais tocados |
37
+ | `Index Scan` seguido de muitas leituras do heap | Um índice de cobertura (`INCLUDE`) permitiria um `Index Only Scan` |
38
+ | Muito tempo em `Limit` sobre `Offset` | Paginação por offset varrendo as linhas puladas |
39
+
40
+ ## Causas comuns e correções
41
+
42
+ - **Índice faltando**: índice composto com as colunas de igualdade primeiro, depois as de intervalo/ordenação. Índice parcial (`WHERE status = 'open'`) quando as consultas miram um subconjunto pequeno.
43
+ - **Predicado não sargável**: funções ou casts sobre a coluna (`WHERE lower(email) = …`, `WHERE created_at::date = …`), curinga no início `LIKE '%x'`, divergência implícita de tipo. Reescreva, ou use um índice de expressão.
44
+ - **Estatísticas desatualizadas**: `ANALYZE <tabela>`; aumente o alvo de estatísticas em colunas assimétricas; estatísticas estendidas para colunas correlacionadas.
45
+ - **N+1**: uma consulta por linha vinda do código da aplicação. Agrupe com `IN`/`ANY($1)` ou um join. Aparece nos traces, não em planos isolados.
46
+ - **Paginação por offset**: troque por keyset (`WHERE (created_at, id) < ($1, $2) ORDER BY created_at DESC, id DESC LIMIT n`), alinhado à paginação por cursor de `api-design`.
47
+ - **Dados demais**: `SELECT *` em linhas largas, `LIMIT` faltando, agregações sobre o histórico inteiro. Selecione as colunas necessárias; pré-agregue se for um relatório.
48
+ - **`OR` entre colunas** impedindo o uso do índice: reescreva como `UNION ALL`.
49
+ - **Subconsultas correlacionadas**: reescreva como joins ou `LATERAL`.
50
+
51
+ ## Verifique
52
+
53
+ Rode de novo o mesmo `EXPLAIN (ANALYZE, BUFFERS)` depois da mudança, sobre os mesmos dados, e compare tempo e buffers. Verifique o custo de escrita de qualquer índice novo em tabelas quentes. Remova os índices que a mudança deixou sem uso (`pg_stat_user_indexes.idx_scan = 0` num período representativo).
54
+
55
+ ## Formato
56
+
57
+ ```
58
+ ## Consulta
59
+ <SQL, parâmetros, frequência, duração atual>
60
+
61
+ ## Diagnóstico
62
+ | Nó do plano | Observação (estimado vs. real, tempo, buffers) | Causa |
63
+
64
+ ## Correções (ordenadas por efeito esperado / custo)
65
+ | # | Correção | Efeito esperado | Custo (sobrecarga de escrita, migração, mudança de código) |
66
+
67
+ ## Verificação
68
+ <plano antes → depois; números>
69
+ ```
70
+
71
+ ## Próximo
72
+
73
+ - `data-migrations` para criar índices (`CONCURRENTLY`) ou mudar o esquema.
74
+ - `observability`: SLI de latência do endpoint afetado, para confirmar o efeito em produção.
75
+
76
+ ## Evite
77
+
78
+ - Adicionar índices sem ler o plano.
79
+ - Planos de dados pequenos ou não representativos.
80
+ - `EXPLAIN ANALYZE` sobre escritas em produção.
81
+ - Um índice por coluna em vez de um índice composto para a consulta.
82
+ - Hints de consulta ou ajustes do planejador como primeira correção.
83
+ - Afirmar uma melhora sem números de antes e depois.
@@ -0,0 +1,106 @@
1
+ ---
2
+ name: release-checklist
3
+ description: Use antes de implantar uma release em produção: verifica migrações, feature flags, plano de rollback, observabilidade, comunicação e momento, e dá uma recomendação de go/no-go com os bloqueadores.
4
+ ---
5
+
6
+ # Checklist de Release
7
+
8
+ Um deploy é seguro quando desfazê-lo é fácil e você vai saber rápido se precisa. Este checklist confirma as duas coisas antes de a mudança chegar aos usuários, para que os problemas apareçam numa revisão e não num incidente.
9
+
10
+ A saída padrão é um **checklist preenchido com uma recomendação de go/no-go**. A decisão é do usuário; implantar nunca faz parte desta skill.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: a release de `release-notes` (versão, mudanças incompatíveis); o plano de migração de `data-migrations`; SLOs e alertas de `observability`; riscos em aberto de `threat-modeling`; o status do CI de `ci-pipeline-review`.
15
+ - Cada item é ✅ (feito, com evidência), ⚠ (risco aceito, com motivo e dono), ❌ (bloqueador) ou N/A (com motivo).
16
+ - Evidência é um link, a saída de um comando ou uma pessoa nomeada. "Deve estar tudo bem" não é evidência.
17
+ - Dimensione pela mudança: uma correção de texto precisa dos itens centrais; uma mudança de esquema ou uma API incompatível precisa de todos.
18
+
19
+ ## Checklist
20
+
21
+ **Escopo**
22
+ - O que vai: versão, PRs e commits desde a última release. Nada sem revisão ou sem merge.
23
+ - Mudanças incompatíveis listadas, com os consumidores avisados.
24
+
25
+ **Build e testes**
26
+ - CI verde no commit ou artefato exato que será implantado.
27
+ - O artefato é o que foi testado (mesmo digest de imagem), não reconstruído.
28
+ - Staging (ou equivalente) rodou esta versão, com os smoke tests passando.
29
+
30
+ **Banco de dados**
31
+ - As migrações são retrocompatíveis com a versão que está rodando (só a fase de expansão; veja `data-migrations`).
32
+ - Risco de lock e de duração avaliado para tabelas grandes; `lock_timeout` definido.
33
+ - Preenchimentos rodam separados e são retomáveis.
34
+ - Passos de contração (remoções) **não** estão nesta release, a menos que o código antigo já tenha saído.
35
+ - Backup ou recuperação point-in-time confirmados recentes.
36
+
37
+ **Feature flags**
38
+ - Comportamento arriscado atrás de uma flag, desligada por padrão, com interruptor de emergência.
39
+ - Cada flag tem um dono e uma data de remoção.
40
+ - Os estados das flags para este rollout estão escritos (quem vê o quê, quando).
41
+
42
+ **Rollback**
43
+ - Como reverter: artefato anterior, flag desligada ou rollback da migração. Passos escritos e testados pelo menos uma vez.
44
+ - Quem decide, e o gatilho (por exemplo, taxa de erro acima do alerta de consumo do SLO por 10 minutos).
45
+ - O que não pode ser revertido (dados gravados num formato novo, e-mails enviados, chamadas externas) está nomeado.
46
+
47
+ **Observabilidade**
48
+ - Dashboards e alertas para os caminhos alterados existem e funcionam (veja `observability`).
49
+ - Uma janela de observação depois do deploy, com uma pessoa nomeada acompanhando.
50
+ - Sinais de sucesso conhecidos: como "funcionando" aparece nas métricas.
51
+
52
+ **Segurança e compliance**
53
+ - Os itens de `threat-modeling` em aberto para esta mudança estão mitigados ou aceitos com dono.
54
+ - Tratamento novo de dados pessoais revisado sob `lgpd-compliance`.
55
+ - Segredos e configuração presentes no ambiente de destino.
56
+
57
+ **Comunicação**
58
+ - Release notes prontas; suporte avisado das mudanças visíveis.
59
+ - Usuários ou consumidores da API avisados de mudanças incompatíveis e de janelas de manutenção.
60
+ - O time sabe o horário do deploy e o canal para reportar problemas.
61
+
62
+ **Momento**
63
+ - Fora de um congelamento ou de um pico de tráfego; não no fim do último dia útil antes de as pessoas ficarem indisponíveis.
64
+ - As pessoas que conseguem reverter estão disponíveis durante a janela de observação.
65
+
66
+ **Depois do deploy**
67
+ - Smoke tests em produção.
68
+ - Ponto de decisão no fim da janela de observação: manter, reverter ou corrigir para frente.
69
+
70
+ ## Recomendação
71
+
72
+ - **Go**: nenhum ❌; todo ⚠ tem dono.
73
+ - **Go com condições**: nenhum ❌, mas itens ⚠ exigem um passo antes (por exemplo, "implantar com a flag desligada").
74
+ - **No-go**: qualquer ❌. Liste o que libera cada um.
75
+
76
+ ## Formato
77
+
78
+ ```
79
+ # Release <versão> — <data/hora UTC>
80
+
81
+ | Área | Item | Status | Evidência / nota |
82
+ |---|---|---|---|
83
+
84
+ ## Bloqueadores
85
+ ## Riscos aceitos (dono)
86
+ ## Plano de rollback
87
+ ## Recomendação: <Go | Go com condições | No-go> — <motivo em uma linha>
88
+ ```
89
+
90
+ ## Próximo
91
+
92
+ - `executive-writing` para uma nota de go/no-go às partes interessadas.
93
+ - `incident-postmortem` se o rollout der errado.
94
+
95
+ ## No Forja
96
+
97
+ No Forja, inclua na verificação os gates do projeto: `forja project:check`, `forja spec:check`, `forja tools:doctor` e `forja project:wire --check`. Riscos aceitos com dono podem virar ADR.
98
+
99
+ ## Evite
100
+
101
+ - Marcar itens sem evidência.
102
+ - Publicar as migrações e o código que precisa delas como um par incompatível.
103
+ - Flags sem interruptor de emergência ou sem data de remoção.
104
+ - Um plano de rollback nunca testado.
105
+ - Implantar sem ninguém acompanhando.
106
+ - Implantar como parte desta skill.
@@ -0,0 +1,87 @@
1
+ ---
2
+ name: release-notes
3
+ description: Use quando gerar uma release ou escrever um changelog: coleta os commits desde a última tag, decide o incremento de versão semântica a partir do Conventional Commits, escreve as notas de release para os usuários e cria a tag só depois da aprovação.
4
+ ---
5
+
6
+ # Notas de Release
7
+
8
+ As notas de release dizem a quem usa o software o que mudou **para essas pessoas**: o que dá para fazer agora, o que foi corrigido e o que elas precisam mudar. Não são um log de commits.
9
+
10
+ A saída padrão é uma **versão e uma seção de changelog propostas**. Edite o changelog, crie a tag ou publique uma release só depois que o usuário aprovar.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: commits escritos com `commit-message` (Conventional Commits), PRs mesclados de `pull-request`.
15
+ - Versionamento: [Semantic Versioning](https://semver.org/). Changelog: [Keep a Changelog](https://keepachangelog.com/).
16
+ - Idioma: o usado no `CHANGELOG.md` existente. Inglês quando não houver um.
17
+ - As regras do repositório prevalecem: uma ferramenta de release existente (`release-please`, `semantic-release`, `changesets`) é dona do processo. Nesse caso, só redija o texto ou ajude a configurar a ferramenta.
18
+
19
+ ## Reúna o contexto
20
+
21
+ 1. `git describe --tags --abbrev=0`: a última tag de release. Nenhuma significa a primeira release.
22
+ 2. `git log <ultima-tag>..HEAD --format='%h %s%n%b'`: assuntos **e** corpos, para pegar os rodapés `BREAKING CHANGE:`.
23
+ 3. O `CHANGELOG.md`, se existir, para o formato e o tom.
24
+ 4. PRs mesclados desde a tag (`gh pr list --state merged --search "merged:>=<data da tag>"`), para o contexto voltado ao usuário que os commits não têm.
25
+
26
+ ## Incremento de versão
27
+
28
+ | Os commits desde a última tag contêm | Incremento |
29
+ |---|---|
30
+ | `!` ou um rodapé `BREAKING CHANGE:` | major |
31
+ | `feat` | minor |
32
+ | só `fix`, `perf` | patch |
33
+ | só `docs`, `test`, `ci`, `chore`, `build`, `style`, `refactor` | nenhuma release necessária; diga isso |
34
+
35
+ - Antes da `1.0.0`, uma mudança incompatível incrementa a versão minor e uma funcionalidade incrementa a patch. Pergunte se o projeto está pronto para a `1.0.0` em vez de decidir sozinho.
36
+ - Commits que não seguem Conventional Commits: leia o diff, classifique-os e liste-os como incertos.
37
+ - Pré-releases (`-rc.1`, `-beta.1`) só a pedido.
38
+
39
+ ## Escrevendo as notas
40
+
41
+ - **Mudanças incompatíveis primeiro**, cada uma com o passo de migração.
42
+ - Agrupe o resto nas seções do Keep a Changelog: Added (`feat`), Fixed (`fix`), Changed (`perf`, mudanças de comportamento), Deprecated, Removed, Security. Use os nomes de seção em português quando o changelog do projeto já os usa (Adicionado, Corrigido, Alterado…).
43
+ - Reescreva cada entrada para os usuários: o efeito, não a implementação. `feat(reports): add CSV export` → "Os relatórios podem ser exportados em CSV."
44
+ - Junte vários commits numa entrada quando eles entregam uma mudança só.
45
+ - Descarte `ci`, `test`, `chore`, `build`, `style` e `refactor` puro, a menos que os usuários os percebam (por exemplo, uma versão mínima de runtime mais alta).
46
+ - Ligue o PR ou o ticket de cada entrada quando houver.
47
+ - Correções de segurança: declare o impacto e as versões afetadas. Não inclua detalhes de exploração antes de os usuários poderem atualizar.
48
+
49
+ ## Formato
50
+
51
+ ```markdown
52
+ ## [<versão>] - <AAAA-MM-DD>
53
+
54
+ ### ⚠ Mudanças incompatíveis
55
+ - <o que mudou>. Migração: <o que fazer>.
56
+
57
+ ### Added
58
+ - <efeito visível ao usuário> (#<PR>)
59
+
60
+ ### Fixed
61
+ - <o que estava quebrado e agora funciona> (#<PR>)
62
+
63
+ ### Changed
64
+ - <mudança de comportamento ou de desempenho>
65
+ ```
66
+
67
+ A seção nova vai no topo do `CHANGELOG.md`, abaixo de `## [Unreleased]` se esse título existir.
68
+
69
+ ## Fluxo
70
+
71
+ 1. Reúna o contexto.
72
+ 2. Proponha a versão com os commits que a justificam, mais as notas.
73
+ 3. Com a aprovação: atualize o `CHANGELOG.md` e os arquivos de versão que o projeto usa (`package.json`, `pyproject.toml` etc.), e faça o commit com `commit-message` (`chore(release): <versão>`).
74
+ 4. Só se pedirem: `git tag -a v<versão> -m "<versão>"`, envie a tag, `gh release create v<versão> --notes-file -`.
75
+
76
+ ## No Forja
77
+
78
+ No Forja, a entrada de cada versão no `CHANGELOG.md` abre com a subseção `### O que melhorou` (o diff de produto em relação à versão anterior, em linguagem de usuário) e só depois as seções técnicas. Esse bloco é reaproveitado como nota da release no GitHub, e o README é reconciliado na mesma entrega.
79
+
80
+ ## Evite
81
+
82
+ - Colar o log de commits cru como notas de release.
83
+ - Detalhes de implementação com os quais os usuários não podem fazer nada.
84
+ - Esconder uma mudança incompatível dentro de "Changed".
85
+ - Incrementar a major numa mudança compatível, ou a patch numa funcionalidade nova.
86
+ - Criar tag, enviar ou publicar sem aprovação.
87
+ - Brigar com uma ferramenta de release existente usando passos manuais.
@@ -0,0 +1,127 @@
1
+ ---
2
+ name: requirements-elicitation
3
+ description: Use quando o conhecimento ainda precisa ser extraído das partes interessadas: prepara roteiros de entrevista, conduz rodadas de perguntas com o usuário como especialista do domínio e registra achados brutos com fonte, conflitos e lacunas.
4
+ ---
5
+
6
+ # Elicitação de Requisitos
7
+
8
+ Extrai o que as partes interessadas sabem, inclusive o que elas não percebem que sabem. O produto são **achados brutos, com fonte**, não um documento de requisitos. Estruturá-los é trabalho da skill `requirements-gathering`.
9
+
10
+ A elicitação trata do negócio, nunca da solução. Telas, tabelas e tecnologias vêm depois.
11
+
12
+ ## Convenções
13
+
14
+ - Termos em pt-BR seguidos do en-US: Parte Interessada (Stakeholder), Ator (Actor), Conhecimento Tácito (Tacit Knowledge), Regra de Negócio (Business Rule), Exceção (Exception), Contorno (Workaround), Linguagem Ubíqua (Ubiquitous Language).
15
+ - Registre as próprias palavras das partes interessadas para termos do domínio. Não as traduza para vocabulário técnico.
16
+ - Todo achado traz sua fonte e sua natureza: **declarado** (alguém disse), **observado** (visto num documento, planilha, formulário ou sistema legado), **inferido** (sua interpretação, pendente de confirmação).
17
+
18
+ ## Princípio central
19
+
20
+ As pessoas descrevem o fluxo normal e esquecem as exceções, porque é nas exceções que elas contornam o sistema sem pensar. O valor da elicitação está nas exceções, nos contornos e no "depende". Casos de borda também são requisitos: um retrato só do caminho feliz é incompleto por definição.
21
+
22
+ ## Modos
23
+
24
+ 1. **Preparar uma sessão**: o usuário vai conversar com as partes interessadas. Produza o mapa de partes interessadas e um roteiro de entrevista.
25
+ 2. **Elicitar diretamente**: o usuário é o especialista do domínio. Faça perguntas em rodadas e registre os achados.
26
+
27
+ Quando o modo não estiver claro, pergunte qual é.
28
+
29
+ ## Processo
30
+
31
+ ### 1. Mapear as partes interessadas
32
+ Quem usa, quem decide, quem paga, quem é afetado, quem audita, quem opera o processo atual. Para cada uma: o que sabe, o que quer, o que teme. Partes interessadas ausentes são um risco: nomeie-as.
33
+
34
+ ### 2. Escolher as técnicas
35
+ - **Entrevista**: padrão para entender objetivos e regras.
36
+ - **Observação (shadowing)**: quando o processo é manual ou habitual; as pessoas fazem mais do que descrevem.
37
+ - **Análise de artefatos**: formulários, planilhas, relatórios, telas e bancos legados. Cada coluna de uma planilha mantida à mão é um requisito que ninguém escreveu.
38
+ - **Percurso de cenário**: percorra um caso real e recente do início ao fim.
39
+ - **Exemplos concretos**: peça números e casos reais para fixar as regras ("me dê um exemplo em que o desconto não foi aplicado").
40
+ - **Workshop**: quando várias partes interessadas discordam ou são donas de partes diferentes do fluxo.
41
+
42
+ ### 3. Perguntar em camadas
43
+ Faça rodadas de no máximo 5–7 perguntas. Cada rodada aprofunda o que a anterior abriu.
44
+
45
+ - **Contexto**: qual é o objetivo? O que acontece hoje sem o sistema? O que mais dói?
46
+ - **Fluxo**: o que inicia o processo? Quem faz o quê, em que ordem? O que o encerra?
47
+ - **Regras**: o que decide cada passo? Quem pode fazer, e quando não pode? Há limites, prazos, aprovações?
48
+ - **Exceções**: o que acontece quando dá errado, atrasa, é cancelado, é feito duas vezes? Qual foi o caso mais chato do mês passado? Que entradas são inválidas, ausentes ou inesperadas? Que restrições nunca podem ser quebradas?
49
+ - **Contornos**: o que vocês fazem fora do sistema hoje? Qual planilha, mensagem, anotação?
50
+ - **Dados**: que informação é necessária em cada passo? De onde vem? Quem corrige quando está errada?
51
+ - **Volume e frequência**: quantos por dia, nos horários de pico? Quantos usuários ao mesmo tempo?
52
+ - **Resultado**: como vocês sabem que funcionou? O que faria este projeto ser um fracasso?
53
+
54
+ ### 4. Perguntar bem
55
+ - Perguntas abertas primeiro; fechadas só para confirmar.
56
+ - Uma pergunta por vez; nada de perguntas compostas.
57
+ - Nada de perguntas indutoras ("você ia querer um dashboard, né?").
58
+ - Pergunte "por quê" até o objetivo aparecer por trás do pedido. Uma funcionalidade pedida muitas vezes é a solução para um problema não dito.
59
+ - Peça exemplos sempre que uma resposta tiver "normalmente", "depende", "às vezes" ou "sempre".
60
+ - Devolva o que entendeu, nas palavras deles, e peça que corrijam.
61
+
62
+ ### 5. Registrar os achados
63
+ Capture fatos, não conclusões. Separe o que foi dito do que você acha que significa.
64
+
65
+ ### 6. Revelar conflitos e lacunas
66
+ Partes interessadas descrevendo a mesma coisa de formas diferentes é um achado, não ruído. Registre as duas versões e quem disse cada uma. Nunca resolva um conflito escolhendo uma por conta própria.
67
+
68
+ Perguntas são entregáveis. Cada lacuna vira uma pergunta precisa dirigida a uma pessoa nomeada; nunca a preencha com uma suposição.
69
+
70
+ ## Formato do roteiro (modo preparar)
71
+
72
+ ```
73
+ # Roteiro de elicitação: <tema>
74
+
75
+ ## Partes interessadas
76
+ | Parte interessada | Papel | Sabe sobre | Quer | Preocupações |
77
+
78
+ ## Objetivo da sessão
79
+ <O que precisa estar entendido ao final.>
80
+
81
+ ## Perguntas
82
+ ### Contexto
83
+ 1. ...
84
+ ### Fluxo
85
+ ### Regras
86
+ ### Exceções e contornos
87
+ ### Dados
88
+ ### Volume
89
+ ### Resultado
90
+
91
+ ## Artefatos a pedir
92
+ - <formulários, planilhas, relatórios, telas>
93
+ ```
94
+
95
+ ## Formato dos achados
96
+
97
+ ```
98
+ # Achados de elicitação: <tema>
99
+
100
+ ## Achados
101
+ | # | Achado | Fonte | Natureza (declarado / observado / inferido) |
102
+
103
+ ## Termos do domínio ouvidos
104
+ - <termo>: <significado nas palavras deles> — <quem usa>
105
+
106
+ ## Exceções e contornos
107
+ - <caso> — <como é tratado hoje>
108
+
109
+ ## Conflitos
110
+ - <tema>: <versão A, fonte> vs <versão B, fonte>
111
+
112
+ ## Lacunas e próximas perguntas
113
+ - <o que ainda não se sabe> — perguntar a <quem>
114
+ ```
115
+
116
+ ## No Forja
117
+
118
+ No Forja, grave os achados em `memory/10-product/elicitacao-<tema>.md` e rode `forja sync:universal`, para que `requirements-gathering` e as outras IAs os encontrem com `forja query:universal "<tema>"`.
119
+
120
+ ## Evite
121
+
122
+ - Falar de telas, tabelas, frameworks ou arquitetura.
123
+ - Aceitar uma solução pedida sem perguntar que problema ela resolve.
124
+ - Apresentar inferências como fatos declarados.
125
+ - Questionários com 30 perguntas de uma vez.
126
+ - Resolver conflitos entre partes interessadas por conta própria.
127
+ - Parar no caminho feliz.