forjajs 5.0.1 → 5.3.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 (268) hide show
  1. package/CHANGELOG.md +114 -2
  2. package/README.md +40 -5
  3. package/README.pt-BR.md +42 -4
  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/apps/cli/src/index.d.ts +0 -1
  50. package/dist/apps/cli/src/index.js +43 -32
  51. package/dist/apps/dashboard/app/api/forja/[...path]/route.js +34 -1
  52. package/dist/apps/dashboard/app/api/forja/capabilities.d.ts +26 -0
  53. package/dist/apps/dashboard/app/api/forja/capabilities.js +39 -0
  54. package/dist/apps/dashboard/app/dashboard-client.jsx +607 -42
  55. package/dist/apps/server/src/forja-nest.module.d.ts +6 -0
  56. package/dist/apps/server/src/forja-nest.module.js +55 -0
  57. package/dist/apps/server/src/main.d.ts +21 -4
  58. package/dist/apps/server/src/main.js +79 -57
  59. package/dist/apps/server/src/task-planning-service.d.ts +29 -0
  60. package/dist/apps/server/src/task-planning-service.js +195 -0
  61. package/dist/apps/server/src/task-runtime-coordinator.d.ts +57 -0
  62. package/dist/apps/server/src/task-runtime-coordinator.js +229 -0
  63. package/dist/bin/forja.js +3 -2
  64. package/dist/bin/init-project.js +1 -0
  65. package/dist/lib/agent-evals.d.ts +138 -0
  66. package/dist/lib/agent-evals.js +349 -0
  67. package/dist/lib/cli-output.js +14 -2
  68. package/dist/lib/code-context.d.ts +33 -5
  69. package/dist/lib/code-context.js +70 -5
  70. package/dist/lib/context-builder.d.ts +49 -4
  71. package/dist/lib/context-builder.js +114 -47
  72. package/dist/lib/core/coverage-gate.d.ts +59 -0
  73. package/dist/lib/core/coverage-gate.js +58 -0
  74. package/dist/lib/core/doc-graph.d.ts +38 -0
  75. package/dist/lib/core/doc-graph.js +83 -0
  76. package/dist/lib/core/health.js +286 -5
  77. package/dist/lib/core/journey.js +36 -0
  78. package/dist/lib/core/registry.js +81 -6
  79. package/dist/lib/docs-reference.d.ts +35 -0
  80. package/dist/lib/docs-reference.js +57 -0
  81. package/dist/lib/generators/memory-generator.d.ts +0 -11
  82. package/dist/lib/generators/memory-generator.js +5 -161
  83. package/dist/lib/generators/readme-generator.js +1 -1
  84. package/dist/lib/llm/json-output.d.ts +14 -0
  85. package/dist/lib/llm/json-output.js +77 -0
  86. package/dist/lib/project-wiring.d.ts +8 -0
  87. package/dist/lib/project-wiring.js +79 -3
  88. package/dist/lib/session-memory.d.ts +38 -0
  89. package/dist/lib/session-memory.js +206 -0
  90. package/dist/lib/spec-trace.d.ts +46 -0
  91. package/dist/lib/spec-trace.js +184 -0
  92. package/dist/lib/validators/structure-validator.js +0 -1
  93. package/dist/packages/adapter-nest/src/index.d.ts +2 -1
  94. package/dist/packages/adapter-nest/src/index.js +59 -1
  95. package/dist/packages/adapter-sqlite/src/index.d.ts +15 -1
  96. package/dist/packages/adapter-sqlite/src/index.js +61 -1
  97. package/dist/packages/context/src/index.d.ts +2 -0
  98. package/dist/packages/context/src/index.js +36 -15
  99. package/dist/packages/contracts/src/index.d.ts +64 -0
  100. package/dist/packages/core/src/index.d.ts +9 -1
  101. package/dist/packages/core/src/index.js +28 -3
  102. package/dist/packages/graph/src/index.js +14 -5
  103. package/dist/packages/llm/src/index.js +12 -2
  104. package/dist/packages/mcp/src/index.d.ts +8 -0
  105. package/dist/packages/mcp/src/index.js +12 -1
  106. package/dist/packages/observability/src/index.d.ts +11 -0
  107. package/dist/packages/observability/src/index.js +3 -0
  108. package/dist/packages/orchestration/src/index.d.ts +15 -1
  109. package/dist/packages/orchestration/src/index.js +127 -21
  110. package/dist/packages/planner/src/index.d.ts +7 -1
  111. package/dist/packages/planner/src/index.js +67 -10
  112. package/dist/packages/planner/src/proposal-store.d.ts +30 -0
  113. package/dist/packages/planner/src/proposal-store.js +109 -0
  114. package/dist/packages/policy/src/index.d.ts +9 -16
  115. package/dist/packages/policy/src/index.js +114 -31
  116. package/dist/packages/runtime/src/index.d.ts +16 -2
  117. package/dist/packages/runtime/src/index.js +176 -61
  118. package/dist/scripts/build-smart-context.d.ts +2 -0
  119. package/dist/scripts/build-smart-context.js +12 -3
  120. package/dist/scripts/code-context.d.ts +3 -1
  121. package/dist/scripts/code-context.js +13 -3
  122. package/dist/scripts/coverage-gate.d.ts +2 -0
  123. package/dist/scripts/coverage-gate.js +101 -0
  124. package/dist/scripts/eval-agents.d.ts +11 -0
  125. package/dist/scripts/eval-agents.js +96 -0
  126. package/dist/scripts/gen-commands-doc.d.ts +2 -0
  127. package/dist/scripts/gen-commands-doc.js +18 -0
  128. package/dist/scripts/hook-session-memory.d.ts +9 -0
  129. package/dist/scripts/hook-session-memory.js +20 -0
  130. package/dist/scripts/hook-session-start.js +34 -0
  131. package/dist/scripts/llm-fit.js +23 -1
  132. package/dist/scripts/spec-trace.d.ts +10 -0
  133. package/dist/scripts/spec-trace.js +73 -0
  134. package/dist/scripts/sync-universal-memory.js +69 -4
  135. package/dist/scripts/token-benchmark.d.ts +33 -1
  136. package/dist/scripts/token-benchmark.js +179 -5
  137. package/dist/scripts/token-economy.js +3 -1
  138. package/dist/scripts/tools-doctor.d.ts +16 -1
  139. package/dist/scripts/tools-doctor.js +58 -17
  140. package/docs/commands.md +155 -0
  141. package/docs/fluxo.md +11 -7
  142. package/docs/init-project.md +3 -1
  143. package/docs/llm-fit-loop.md +36 -0
  144. package/docs/manual-operacional-cli-sdd-gsd.md +3 -2
  145. package/docs/produto/factsheet-marketing.md +7 -5
  146. package/docs/produto/roteiro-demo.md +14 -5
  147. package/docs/quick-reference.md +3 -3
  148. package/docs/token-optimization.md +10 -6
  149. package/memory/90-decisions/0088-templates-validados.md +3 -0
  150. package/memory/90-decisions/0089-skills-do-projeto.md +51 -0
  151. package/memory/90-decisions/0090-adapters-de-agente-somente-leitura.md +47 -0
  152. package/memory/90-decisions/0091-memoria-de-sessao-por-hooks.md +40 -0
  153. package/memory/90-decisions/0092-criterios-de-aceite-ligados-a-testes.md +37 -0
  154. package/memory/90-decisions/0093-avaliacoes-com-agentes-reais.md +40 -0
  155. package/package.json +4 -2
  156. package/specs/avaliacoes-de-agentes/spec.md +52 -0
  157. package/specs/criterios-ligados-a-testes/spec.md +42 -0
  158. package/specs/memoria-de-sessao/spec.md +48 -0
  159. package/specs/skills-do-projeto/plan.md +40 -0
  160. package/specs/skills-do-projeto/spec.md +63 -0
  161. package/specs/skills-do-projeto/tasks.md +27 -0
  162. package/specs/v6-agent-runtime-portable/spec.md +83 -0
  163. package/specs/v6-core-consolidation/spec.md +70 -0
  164. package/specs/v6-docs-drift/spec.md +85 -0
  165. package/specs/v6-quality-gates/spec.md +99 -0
  166. package/specs/v6-token-economy/spec.md +84 -0
  167. package/templates/evals/agents/adr.json +25 -0
  168. package/templates/evals/agents/memoria.json +32 -0
  169. package/templates/evals/agents/proxima-acao.json +29 -0
  170. package/templates/evals/agents/spec-nova.json +26 -0
  171. package/templates/evals/agents/teste-do-criterio.json +29 -0
  172. package/templates/project/AGENTS.md +16 -0
  173. package/templates/project/CLAUDE.md +3 -2
  174. package/templates/project/agents/context-engineer.md +3 -0
  175. package/templates/project/agents/governance.md +3 -0
  176. package/templates/project/agents/marketing.md +3 -0
  177. package/templates/project/agents/orchestrator.md +3 -0
  178. package/templates/project/agents/product.md +3 -0
  179. package/templates/project/agents/sdd-architect.md +3 -0
  180. package/templates/project/skills/README.md +14 -0
  181. package/templates/project/skills/accessibility-review/SKILL.md +89 -0
  182. package/templates/project/skills/api-design/SKILL.md +77 -0
  183. package/templates/project/skills/architecture-decision-record/SKILL.md +92 -0
  184. package/templates/project/skills/backlog-slicing/SKILL.md +82 -0
  185. package/templates/project/skills/bounded-context-mapping/SKILL.md +88 -0
  186. package/templates/project/skills/ci-pipeline-review/SKILL.md +83 -0
  187. package/templates/project/skills/commit-message/SKILL.md +143 -0
  188. package/templates/project/skills/data-migrations/SKILL.md +88 -0
  189. package/templates/project/skills/dependency-upgrade/SKILL.md +75 -0
  190. package/templates/project/skills/docker-compose-review/SKILL.md +85 -0
  191. package/templates/project/skills/domain-modeling/SKILL.md +120 -0
  192. package/templates/project/skills/event-storming/SKILL.md +95 -0
  193. package/templates/project/skills/executive-writing/SKILL.md +99 -0
  194. package/templates/project/skills/frontend-architecture/SKILL.md +97 -0
  195. package/templates/project/skills/incident-postmortem/SKILL.md +93 -0
  196. package/templates/project/skills/lgpd-compliance/SKILL.md +108 -0
  197. package/templates/project/skills/llm-provider-routing/SKILL.md +18 -0
  198. package/templates/project/skills/observability/SKILL.md +93 -0
  199. package/templates/project/skills/product-evaluation/SKILL.md +130 -0
  200. package/templates/project/skills/prompt-spec/SKILL.md +83 -0
  201. package/templates/project/skills/pull-request/SKILL.md +101 -0
  202. package/templates/project/skills/query-performance/SKILL.md +83 -0
  203. package/templates/project/skills/release-checklist/SKILL.md +106 -0
  204. package/templates/project/skills/release-notes/SKILL.md +87 -0
  205. package/templates/project/skills/requirements-elicitation/SKILL.md +127 -0
  206. package/templates/project/skills/requirements-gathering/SKILL.md +134 -0
  207. package/templates/project/skills/technical-spike/SKILL.md +101 -0
  208. package/templates/project/skills/testing/SKILL.md +109 -0
  209. package/templates/project/skills/threat-modeling/SKILL.md +87 -0
  210. package/templates/project/skills/ts-async-patterns/SKILL.md +101 -0
  211. package/templates/project/skills/ts-code-review/SKILL.md +121 -0
  212. package/templates/project/skills/ts-module-layout/SKILL.md +104 -0
  213. package/templates/project/skills/ts-testing/SKILL.md +89 -0
  214. package/templates/project/skills/web-performance/SKILL.md +72 -0
  215. package/boilerplates/02-saas-starter/.env.example +0 -25
  216. package/boilerplates/02-saas-starter/CHECKLIST-CRIACAO.md +0 -190
  217. package/boilerplates/02-saas-starter/INFO.md +0 -252
  218. package/boilerplates/02-saas-starter/QUICK_START.md +0 -194
  219. package/boilerplates/02-saas-starter/START-HERE.md +0 -259
  220. package/boilerplates/02-saas-starter/backend/src/common/decorators/roles.decorator.ts +0 -3
  221. package/boilerplates/02-saas-starter/backend/src/common/decorators/tenant.decorator.ts +0 -6
  222. package/boilerplates/02-saas-starter/backend/src/common/middleware/roles.guard.ts +0 -23
  223. package/boilerplates/02-saas-starter/backend/src/config/database.ts +0 -26
  224. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.controller.ts +0 -46
  225. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.module.ts +0 -25
  226. package/boilerplates/02-saas-starter/backend/src/modules/auth/auth.service.ts +0 -145
  227. package/boilerplates/02-saas-starter/backend/src/modules/auth/dto/auth.dto.ts +0 -30
  228. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/jwt.strategy.ts +0 -24
  229. package/boilerplates/02-saas-starter/backend/src/modules/auth/strategies/local.strategy.ts +0 -19
  230. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.controller.ts +0 -42
  231. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.module.ts +0 -13
  232. package/boilerplates/02-saas-starter/backend/src/modules/billing/billing.service.ts +0 -67
  233. package/boilerplates/02-saas-starter/backend/src/modules/billing/entities/invoice.entity.ts +0 -52
  234. package/boilerplates/02-saas-starter/backend/src/modules/organizations/entities/organization.entity.ts +0 -36
  235. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.controller.ts +0 -16
  236. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.module.ts +0 -13
  237. package/boilerplates/02-saas-starter/backend/src/modules/organizations/organizations.service.ts +0 -34
  238. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/entities/subscription.entity.ts +0 -40
  239. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.controller.ts +0 -36
  240. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.module.ts +0 -13
  241. package/boilerplates/02-saas-starter/backend/src/modules/subscriptions/subscriptions.service.ts +0 -91
  242. package/boilerplates/02-saas-starter/backend/src/modules/users/entities/user.entity.ts +0 -42
  243. package/boilerplates/02-saas-starter/backend/src/modules/users/users.controller.ts +0 -14
  244. package/boilerplates/02-saas-starter/backend/src/modules/users/users.module.ts +0 -13
  245. package/boilerplates/02-saas-starter/backend/src/modules/users/users.service.ts +0 -48
  246. package/boilerplates/02-saas-starter/memory/00-global/agent-contract.md +0 -227
  247. package/boilerplates/02-saas-starter/memory/00-global/context-policy.md +0 -141
  248. package/boilerplates/02-saas-starter/memory/00-global/index.md +0 -133
  249. package/boilerplates/02-saas-starter/memory/00-global/mission.md +0 -45
  250. package/boilerplates/02-saas-starter/memory/00-global/patterns.md +0 -223
  251. package/boilerplates/02-saas-starter/memory/10-product/business-rules.md +0 -240
  252. package/boilerplates/02-saas-starter/memory/10-product/nfrs.md +0 -239
  253. package/boilerplates/02-saas-starter/memory/10-product/personas.md +0 -195
  254. package/boilerplates/02-saas-starter/memory/10-product/vision.md +0 -63
  255. package/boilerplates/02-saas-starter/memory/20-architecture/overview.md +0 -232
  256. package/boilerplates/02-saas-starter/memory/30-domains/auth/api.md +0 -186
  257. package/boilerplates/02-saas-starter/memory/30-domains/auth/context.md +0 -85
  258. package/boilerplates/02-saas-starter/memory/30-domains/billing/api.md +0 -262
  259. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/api.md +0 -176
  260. package/boilerplates/02-saas-starter/memory/30-domains/subscriptions/context.md +0 -100
  261. package/boilerplates/02-saas-starter/memory/40-delivery/backlog.md +0 -81
  262. package/boilerplates/02-saas-starter/memory/40-delivery/roadmap.md +0 -97
  263. package/boilerplates/02-saas-starter/memory/40-delivery/sprint-atual.md +0 -57
  264. package/boilerplates/02-saas-starter/memory/50-orchestration/topology.md +0 -90
  265. package/boilerplates/02-saas-starter/memory/60-runs/index.md +0 -54
  266. package/boilerplates/02-saas-starter/memory/70-summaries/global.md +0 -50
  267. package/boilerplates/02-saas-starter/memory/80-data/schema.md +0 -185
  268. package/boilerplates/02-saas-starter/memory/90-decisions/adr-template.md +0 -75
@@ -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.
@@ -0,0 +1,134 @@
1
+ ---
2
+ name: requirements-gathering
3
+ description: Use quando transformar ideias, achados de elicitação ou documentos numa especificação de requisitos estruturada: escopo, atores, requisitos funcionais com critérios de aceite, regras de negócio, requisitos não funcionais mensuráveis, glossário e prioridades.
4
+ ---
5
+
6
+ # Levantamento de Requisitos
7
+
8
+ Consolida o que se sabe sobre um sistema numa especificação de requisitos curta e verificável. Entrada: uma ideia, achados de elicitação (skill `requirements-elicitation`), documentos existentes ou um sistema legado. Saída: a especificação que `domain-modeling` consome.
9
+
10
+ A especificação é uma lista de trabalho, não literatura. Detalhe só o que é incerto e está perto de ser construído; o longo prazo fica como direção.
11
+
12
+ A especificação está pronta quando um desenvolvedor consegue implementá-la sem adivinhar e um testador consegue verificá-la sem interpretar.
13
+
14
+ ## Convenções
15
+
16
+ - Termos em pt-BR seguidos do en-US: Requisito Funcional (Functional Requirement), Regra de Negócio (Business Rule), Requisito Não Funcional (Non-Functional Requirement), Critério de Aceite (Acceptance Criterion), Ator (Actor), Parte Interessada (Stakeholder), Escopo (Scope), Linguagem Ubíqua (Ubiquitous Language).
17
+ - IDs: `RF-NN` (funcional), `RN-NN` (regra de negócio), `RNF-NN` (não funcional). Nunca reutilize um ID; marque itens removidos como removidos.
18
+ - Escreva no vocabulário das partes interessadas.
19
+
20
+ ## Princípio central
21
+
22
+ Um requisito descreve **o quê** e **por quê**, nunca **como**. "A enfermeira precisa ver a dieta do paciente antes de fazer o pedido" é um requisito; "mostrar um selo de dieta na tela de pedido" é uma solução. Se a entrada trouxer uma solução, registre o problema por trás dela e mantenha a solução como nota.
23
+
24
+ Especifique exatamente o necessário: nem acima (soluções, decisões de design) nem abaixo (lacunas que quem implementa terá de preencher adivinhando).
25
+
26
+ ## Qualidade de cada item
27
+
28
+ Todo requisito e regra precisa ser:
29
+ - **Atômico**: uma necessidade por item.
30
+ - **Verificável**: checável por um teste, uma métrica ou um comportamento observável; tem critérios de aceite ou um exemplo. Se não dá para checar, é um desejo, não um requisito: reescreva ou descarte.
31
+ - **Com fonte**: quem disse ou de onde veio.
32
+ - **Sem ambiguidade**: ambiguidade é defeito. Se dá para ler de duas formas, reescreva até sobrar uma leitura só. Nada de "rápido", "fácil", "flexível", "amigável", "etc.", "e/ou" sem definição.
33
+ - **Completo**: cobre os casos de borda, não só o caminho feliz.
34
+
35
+ Itens que falham nessas verificações vão para **Perguntas em aberto**, não para a lista.
36
+
37
+ ## Processo
38
+
39
+ ### 1. Objetivo e contexto
40
+ Um parágrafo: que problema é resolvido, para quem, e como o sucesso é reconhecido. Sem isso, nada pode ser priorizado.
41
+
42
+ ### 2. Atores e partes interessadas
43
+ Quem interage com o sistema (atores) e quem é afetado por ele (partes interessadas). Inclua sistemas externos como atores.
44
+
45
+ ### 3. Escopo
46
+ Escopo é um contrato. Listas explícitas de **dentro** e **fora**. O "fora" impede o crescimento silencioso do escopo e é tão importante quanto o "dentro".
47
+
48
+ ### 4. Requisitos funcionais
49
+ Frases curtas: `<Ator> precisa conseguir <ação> para <objetivo>`. Para cada um, 1–4 critérios de aceite em Dado/Quando/Então ou exemplos concretos. Os critérios cobrem modos de falha, entradas inválidas ou inesperadas e limites, não só o caminho feliz; um requisito só com critérios de caminho feliz está incompleto.
50
+
51
+ ### 5. Regras de negócio
52
+ Separadas dos requisitos funcionais: as regras que governam o domínio independentemente das telas (limites, elegibilidade, cálculos, prazos, estados, quem pode fazer o quê). Enuncie cada regra com um exemplo. Regras que variam ou podem mudar são marcadas como **variáveis**: virarão Políticas em `domain-modeling`.
53
+
54
+ ### 6. Requisitos não funcionais
55
+ Só os mensuráveis, e só os que importam aqui: desempenho (latência num volume declarado), disponibilidade, segurança, auditabilidade, retenção de dados, compliance (dados pessoais → sinalize para `lgpd-compliance`), integrações, acessibilidade. Um requisito não funcional sem número ou condição verificável vai para perguntas em aberto.
56
+
57
+ ### 7. Glossário
58
+ Termos do domínio com seu significado e o contexto em que se aplicam. É a semente da linguagem ubíqua. Quando um termo tem dois significados, registre os dois: isso sinaliza dois contextos delimitados.
59
+
60
+ ### 8. Prioridade
61
+ MoSCoW por requisito funcional: **Must** (sem ele o sistema não tem razão de existir), **Should**, **Could**, **Won't (agora)**. Poucos Musts. Se tudo é Must, pergunte o que seria cortado se o prazo caísse pela metade.
62
+
63
+ ### 9. Suposições e perguntas em aberto
64
+ O que foi suposto sem confirmação e o que ainda precisa ser perguntado, e a quem. Incógnitas são listadas, nunca preenchidas com palpites. Quando faltar informação-chave, uma lista precisa e direcionada de perguntas é o entregável; prefira-a a uma especificação construída sobre suposições.
65
+
66
+ ### 10. Encaminhamento
67
+ Anote o que vai para onde: regras de negócio e glossário → `domain-modeling`; critérios de aceite → `testing` (mais a skill da linguagem, por exemplo `ts-testing`); dados pessoais → `lgpd-compliance`; incertezas técnicas → `technical-spike`.
68
+
69
+ ## Formato de saída
70
+
71
+ ```
72
+ # Requisitos: <sistema ou funcionalidade>
73
+
74
+ ## Objetivo
75
+ <problema, para quem, critério de sucesso>
76
+
77
+ ## Atores
78
+ | Ator | Descrição |
79
+
80
+ ## Escopo
81
+ - Dentro: ...
82
+ - Fora: ...
83
+
84
+ ## Requisitos funcionais
85
+ ### RF-01 — <título curto> [Must]
86
+ <Ator> precisa conseguir <ação> para <objetivo>.
87
+ Fonte: <...>
88
+ Critérios de aceite:
89
+ - Dado ... Quando ... Então ...
90
+
91
+ ## Regras de negócio
92
+ | ID | Regra | Exemplo | Variável? | Fonte |
93
+
94
+ ## Requisitos não funcionais
95
+ | ID | Requisito | Medida / condição | Fonte |
96
+
97
+ ## Glossário
98
+ | Termo | Significado | Contexto |
99
+
100
+ ## Suposições e perguntas em aberto
101
+ - <item> — perguntar a <quem>
102
+
103
+ ## Encaminhamento
104
+ - domain-modeling: RN-..., glossário
105
+ - testing: critérios de aceite de RF-...
106
+ - lgpd-compliance: <dados pessoais envolvidos>
107
+ - technical-spike: <incertezas>
108
+ ```
109
+
110
+ ## No Forja
111
+
112
+ No Forja, a especificação vive em `specs/<slug>/spec.md`, criada com `forja spec:new <slug>`. Mapeie as seções:
113
+
114
+ | Esta skill | spec.md do Forja |
115
+ |---|---|
116
+ | Objetivo | §1 Problema e §2 Proposta de valor |
117
+ | Requisitos funcionais (`RF-NN`) | §3 User stories |
118
+ | Critérios de aceite | §4 Critérios de aceite, como `AC-n` (cite o `RF-NN` de origem) |
119
+ | Escopo | §5 Escopo (Dentro / Fora) |
120
+ | Requisitos não funcionais | §6 NFRs / restrições |
121
+ | Riscos e suposições | §7 Riscos e mitigação |
122
+
123
+ Regras de negócio e glossário também vão para `memory/30-domains/<contexto>/`. Ao terminar a revisão: `forja spec:set-status <slug> spec approved`; depois `forja spec:check <slug>`.
124
+
125
+ ## Evite
126
+
127
+ - Soluções escritas como requisitos (telas, tabelas, tecnologias).
128
+ - Documentos de casos de uso com dezenas de páginas.
129
+ - Detalhar o futuro distante.
130
+ - Requisitos não funcionais vagos ("o sistema precisa ser rápido").
131
+ - Manter desejos (afirmações não testáveis) como requisitos.
132
+ - Critérios de aceite só de caminho feliz.
133
+ - Regras de negócio escondidas dentro de requisitos funcionais.
134
+ - Preencher lacunas com regras inventadas.
@@ -0,0 +1,101 @@
1
+ ---
2
+ name: technical-spike
3
+ description: Use quando uma incerteza técnica é cara demais para assumir às cegas: planeja uma prova de conceito com tempo limitado, uma pergunta, critérios de sucesso e uma decisão, e registra o resultado.
4
+ ---
5
+
6
+ # Spike Técnico (Prova de Conceito)
7
+
8
+ Um spike é um experimento curto, com tempo limitado, que compra certeza antes de assumir algo caro. Seu produto é uma **decisão apoiada em evidência**, não código de produção.
9
+
10
+ Pagar alguns dias para descartar uma ideia ruim é um seguro contra gastar meses nela.
11
+
12
+ ## Quando fazer
13
+
14
+ - Uma escolha técnica com alto custo de reversão que ninguém do time já fez (banco de dados novo, framework, integração, estilo de arquitetura).
15
+ - Uma dúvida de desempenho, escala ou viabilidade que a discussão não resolve.
16
+ - Várias opções concorrentes e o time continua debatendo em vez de decidir.
17
+
18
+ Não faça spike do que o time já sabe fazer. Faça.
19
+
20
+ ## Regras
21
+
22
+ - **Uma pergunta por spike**, respondível com sim/não ou com a escolha entre opções.
23
+ - **Tempo fixo**: de 1–2 dias até uma semana no máximo. Quando acaba, o spike acaba, terminado ou não.
24
+ - **Critérios de sucesso e de fracasso definidos antes de começar.** Do contrário, o resultado é reinterpretado para caber no que foi construído.
25
+ - **Descartável por padrão**: um branch separado, nunca mesclado como está. O que for mantido é reescrito direito na linha principal, com testes.
26
+ - **Escopo mínimo**: só o necessário para responder à pergunta. Sem polimento de UI, sem tratamento de erro além do que a pergunta exige, sem generalização.
27
+ - **Evidência acima de impressão**: medições, um caminho funcionando, uma limitação reproduzida, código mostrando que a integração de fato funciona.
28
+ - **Um resultado inconclusivo é um resultado.** Registre o que se aprendeu e decida: descartar, ou fazer mais um spike com uma pergunta nova e mais estreita. Nunca estenda o tempo em silêncio.
29
+
30
+ ## Processo
31
+
32
+ 1. **Enquadre a pergunta.** O que exatamente precisa ser sabido para decidir? Que decisão depende disso?
33
+ 2. **Defina os critérios.** Que resultado significa "adotar" e qual significa "descartar". Inclua limites mensuráveis quando fizer sentido (latência, vazão, memória, linhas de código de cola, tempo de setup).
34
+ 3. **Defina o tempo e o escopo.** O que está dentro e o que está explicitamente fora.
35
+ 4. **Execute.** Construa só o caminho crítico. Anote as surpresas na hora em que acontecem.
36
+ 5. **Relate os achados** contra os critérios, com evidência.
37
+ 6. **Decida**: adotar, descartar, ou um spike novo e mais estreito. Se adotado ou rejeitado e a decisão for relevante, registre-a como ADR (skill `architecture-decision-record`).
38
+
39
+ ## Formato do plano
40
+
41
+ ```
42
+ # Spike: <título curto>
43
+
44
+ - Pergunta: <a pergunta única>
45
+ - Decisão que destrava: <o que será decidido com a resposta>
46
+ - Tempo: <N dias, início–fim>
47
+ - Branch: spike/<slug>
48
+
49
+ ## Hipótese
50
+ <O que esperamos encontrar.>
51
+
52
+ ## Critérios de sucesso
53
+ - <condição mensurável ou observável>
54
+
55
+ ## Critérios de fracasso
56
+ - <condição que significa descartar>
57
+
58
+ ## Escopo
59
+ - Dentro: <...>
60
+ - Fora: <...>
61
+
62
+ ## Riscos / suposições
63
+ - <...>
64
+ ```
65
+
66
+ ## Formato do relatório
67
+
68
+ ```
69
+ # Resultado do spike: <título curto>
70
+
71
+ - Resultado: <Adotar | Descartar | Inconclusivo → novo spike>
72
+ - Tempo gasto: <real vs. previsto>
73
+
74
+ ## Achados
75
+ - <achado> — evidência: <medição, link, reprodução>
76
+
77
+ ## Contra os critérios
78
+ | Critério | Resultado | Atendido? |
79
+
80
+ ## Surpresas
81
+ - <o que não era esperado>
82
+
83
+ ## Recomendação
84
+ <O que fazer em seguida. Se for adotar: o que precisa ser reconstruído direito e para que o código do spike não deve ser reaproveitado.>
85
+
86
+ ## ADR
87
+ <NNNN, ou "não necessário" e por quê>
88
+ ```
89
+
90
+ ## No Forja
91
+
92
+ No Forja, o plano e o resultado do spike ficam em `memory/40-delivery/spikes/<slug>.md`; a decisão, quando relevante, vira ADR em `memory/90-decisions/` (`architecture-decision-record`). Rode `forja sync:universal` depois.
93
+
94
+ ## Evite
95
+
96
+ - Spikes sem pergunta ("vamos brincar com X").
97
+ - Critérios definidos depois de ver os resultados.
98
+ - Mesclar código de spike no branch principal.
99
+ - Estender o tempo em vez de reformular a pergunta.
100
+ - Generalizar ou polir dentro do spike.
101
+ - Fazer várias perguntas num spike e não responder nenhuma com clareza.