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,99 @@
1
+ ---
2
+ name: executive-writing
3
+ description: Use quando uma análise consolidada precisa virar comunicação orientada à decisão para gestores, conselhos ou times: resumos executivos, pareceres, memorandos, apresentações e comunicados de decisão, com fatos, alternativas, recomendação, plano de ação e limitações.
4
+ ---
5
+
6
+ # Redação Executiva
7
+
8
+ Transforma análises complexas em comunicação clara, curta e orientada à decisão. Entrada: análises, diagnósticos e recomendações consolidados (de `requirements-gathering`, `architecture-decision-record`, `technical-spike`, `lgpd-compliance` ou do usuário). Saída: a versão final para gestores, o conselho ou os times operacionais.
9
+
10
+ O texto serve a uma decisão. Se o leitor termina e não sabe o que decidir ou o que fazer em seguida, o texto falhou.
11
+
12
+ ## Convenções
13
+
14
+ - Termos em pt-BR seguidos do en-US: Resumo Executivo (Executive Summary), Parecer (Opinion), Memorando (Memo), Comunicado de Decisão (Decision Announcement), Pirâmide de Minto (Minto Pyramid), Sumário Decisório (Decision Brief), Plano de Ação (Action Plan), Trade-off.
15
+ - Toda afirmação é marcada pela natureza quando isso importa: **fato** (com fonte), **hipótese**, **inferência**, **lacuna**.
16
+ - Escreva no vocabulário do leitor: executivo (impacto, custo, risco, prazo) ou operacional (quem faz o quê, quando, como).
17
+
18
+ ## Princípio central
19
+
20
+ Resposta primeiro, sustentação depois (Pirâmide de Minto). Comece pela decisão ou recomendação, depois os poucos argumentos que a sustentam, depois a evidência. Sintetize, não resuma: corte redundância e jargão, mas nunca precisão ou rastreabilidade.
21
+
22
+ ## Processo
23
+
24
+ ### 1. Contexto e leitor
25
+ Qual é a situação, o que precisa ser decidido, quem decide e do que precisa para decidir. Leitores executivos e operacionais recebem textos diferentes.
26
+
27
+ ### 2. Inventariar o material
28
+ Dados, documentos, regras e restrições disponíveis. Separe fatos, hipóteses, inferências e lacunas. Nada é acrescentado que o material não sustente.
29
+
30
+ ### 3. Enquadrar a decisão
31
+ Uma frase: o que precisa ser decidido ou analisado. Se não há decisão, declare a finalidade (informar, alinhar, registrar).
32
+
33
+ ### 4. Analisar
34
+ Diagnóstico estruturado: causas, impactos, relações. Distinga correlação de causalidade. Questione práticas mantidas só por hábito.
35
+
36
+ ### 5. Comparar alternativas
37
+ Opções viáveis lado a lado, cada uma com benefícios, desvantagens, custo, risco e dependências. Explicite os trade-offs. Não fazer nada é uma alternativa quando é viável. Tecnologia nunca é a resposta automática.
38
+
39
+ ### 6. Recomendar
40
+ Específica, priorizada, justificada. Ligue cada recomendação a um resultado mensurável.
41
+
42
+ ### 7. Plano de ação e limitações
43
+ Ações com responsáveis sugeridos, prazos, prioridades, dependências e indicadores de sucesso. Depois: dados faltantes, incertezas e pontos que precisam de validação, e quem precisa validá-los.
44
+
45
+ ### 8. Moldar para o entregável
46
+ Escolha o formato e enxugue para ele (veja abaixo). Linha narrativa: o título de cada seção enuncia a sua conclusão, de modo que ler só os títulos conte a história.
47
+
48
+ ## Entregáveis
49
+
50
+ - **Resumo executivo**: uma página ou menos; recomendação, impacto, risco, próximos passos.
51
+ - **Parecer**: estrutura completa; raciocínio e limitações explícitos.
52
+ - **Memorando**: uma página; contexto, decisão necessária, recomendação, ações.
53
+ - **Apresentação**: linha narrativa, uma mensagem por slide, o título enuncia a conclusão.
54
+ - **Comunicado de decisão**: o que foi decidido, por quê, o que muda para quem, a partir de quando.
55
+
56
+ ## Formato de saída
57
+
58
+ ```
59
+ # <Título que enuncia a conclusão>
60
+
61
+ ## Resumo
62
+ <Recomendação em 2–3 frases: decisão, impacto, risco, próximo passo.>
63
+
64
+ ## Contexto
65
+ <Situação em poucas linhas.>
66
+
67
+ ## Problema ou decisão
68
+ <O que precisa ser decidido.>
69
+
70
+ ## Evidências
71
+ - <fato> — <fonte>
72
+
73
+ ## Análise
74
+ <Causas, impactos, relações. Hipóteses marcadas como tal.>
75
+
76
+ ## Alternativas
77
+ | Opção | Benefícios | Desvantagens | Custo | Risco | Dependências |
78
+
79
+ ## Recomendação
80
+ <Específica, priorizada, justificada.>
81
+
82
+ ## Plano de ação
83
+ | Ação | Responsável sugerido | Prazo | Prioridade | Depende de | Indicador |
84
+
85
+ ## Limitações
86
+ - <dado faltante / incerteza> — validar com <quem>
87
+ ```
88
+
89
+ ## Evite
90
+
91
+ - Inventar dados, fatos, números ou evidências.
92
+ - Apresentar uma hipótese como conclusão.
93
+ - Recomendações genéricas ("melhorar a comunicação", "investir em tecnologia").
94
+ - Propor tecnologia como solução automática.
95
+ - Omitir custos, riscos, restrições ou efeitos colaterais.
96
+ - Tratar correlação como causalidade.
97
+ - Enterrar a recomendação no fim.
98
+ - Redundância, jargão e rodeios que escondem a mensagem.
99
+ - Listar várias alternativas sem compará-las.
@@ -0,0 +1,97 @@
1
+ ---
2
+ name: frontend-architecture
3
+ description: Use quando organizar ou revisar um front-end React ou Next.js: estrutura por funcionalidade, fronteira entre Server e Client Components, estado do servidor vs. estado do cliente, busca de dados e cache, formulários com validação, fronteiras de erro e de carregamento, e um plano de mudança incremental.
4
+ ---
5
+
6
+ # Arquitetura de Front-end
7
+
8
+ Um front-end apodrece de dois jeitos: tudo vira estado global, ou cada tela reimplementa a busca de dados do seu jeito. A primeira pergunta para qualquer dado é **de quem ele é**: do servidor (vem de uma API e tem uma cópia mais nova em outro lugar) ou do cliente (existe só nesta tela, nesta sessão). Errar essa pergunta é a origem da maior parte dos bugs de sincronia.
9
+
10
+ A saída padrão é uma **avaliação e uma estrutura alvo com um plano de mudança**. Escreva componentes só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: as histórias de `backlog-slicing`, o contrato de `api-design`, a estrutura atual e o `package.json`.
15
+ - O framework e as bibliotecas que o projeto já usa prevalecem (Next.js App Router ou Pages Router, Vite, React Query, Zustand, Redux, React Hook Form…). Proponha trocar só por um problema concreto.
16
+ - Os nomes de pastas e componentes seguem a linguagem ubíqua do domínio, não os nomes técnicos.
17
+
18
+ ## Avalie primeiro
19
+
20
+ Somente leitura:
21
+
22
+ 1. Rotas e páginas: quais existem, o que cada uma carrega e de onde.
23
+ 2. Onde os dados são buscados: em componentes, em hooks, num cliente central. `fetch` espalhado em `useEffect` é um mau sinal.
24
+ 3. Estado global: o que está nele. Dados do servidor copiados para uma store global são o problema mais comum.
25
+ 4. Pastas genéricas (`components/` com tudo, `utils/`, `hooks/` sem dono).
26
+ 5. Ciclos e acoplamento: `npx madge --circular --extensions ts,tsx src` (veja `ts-module-layout`).
27
+ 6. No Next.js: quais componentes são `'use client'` e por quê. Um `'use client'` no topo de uma árvore grande puxa tudo para o bundle do cliente.
28
+
29
+ ## Estrutura alvo
30
+
31
+ ```
32
+ src/
33
+ app/ (ou pages/) # roteamento do framework; páginas finas que compõem funcionalidades
34
+ features/<contexto>/ # uma por contexto ou funcionalidade do domínio
35
+ components/ # componentes desta funcionalidade
36
+ api.ts # chamadas à API e chaves de cache desta funcionalidade
37
+ hooks.ts # hooks de dados e de comportamento
38
+ schema.ts # schemas de validação (formulários, respostas)
39
+ shared/ui/ # componentes de design system sem regra de negócio (Button, Dialog)
40
+ shared/lib/ # infraestrutura com comportamento real: cliente HTTP, i18n, telemetria
41
+ ```
42
+
43
+ Regras:
44
+
45
+ - **Organize por funcionalidade.** Uma página compõe funcionalidades; uma funcionalidade não importa os arquivos internos de outra (use o que ela exporta).
46
+ - **Estado do servidor fica num cache de servidor** (React Query/TanStack Query, SWR, ou o cache do framework), não numa store global. Cada consulta tem uma chave estável e uma política de invalidação depois das mutações.
47
+ - **Estado do cliente o mais local possível**: no componente, depois na URL (filtros, paginação, abas), depois num contexto, e só então numa store global.
48
+ - **Server Components por padrão no Next.js App Router**; `'use client'` só nas folhas que precisam de interatividade, de estado ou de APIs do navegador. Dados sensíveis e segredos nunca chegam a um Client Component.
49
+ - **Valide nas fronteiras**: respostas da API e entradas de formulário passam por um schema (`zod`, `valibot`), não por uma anotação de tipo.
50
+ - **Formulários**: uma biblioteca de formulário quando há validação ou muitos campos; mensagens de erro ligadas aos campos; o servidor revalida sempre.
51
+ - **Carregamento e erro são estados de primeira classe**: cada tela define o que mostra carregando, vazia, com erro e com sucesso. No Next.js, `loading.tsx` e `error.tsx`; no React, `Suspense` e fronteiras de erro.
52
+ - **Sem regra de negócio em componente de UI.** Cálculos e decisões vão para funções puras testáveis (`ts-testing`).
53
+
54
+ ## Plano de mudança
55
+
56
+ Cada passo funciona sozinho e pode ser um commit:
57
+
58
+ 1. Introduza o cache de servidor numa funcionalidade e migre a busca de dados dela.
59
+ 2. Tire da store global os dados de servidor que agora estão no cache.
60
+ 3. Mova os componentes da funcionalidade para `features/<contexto>/`.
61
+ 4. Empurre `'use client'` para as folhas.
62
+ 5. Repita por funcionalidade; apague as pastas genéricas que esvaziaram.
63
+
64
+ ## Formato
65
+
66
+ ```
67
+ ## Estado atual
68
+ | Problema | Onde | Efeito |
69
+
70
+ ## Estrutura alvo
71
+ <árvore>
72
+
73
+ ## Dados
74
+ | Dado | Dono (servidor/cliente) | Onde vive | Invalidação |
75
+
76
+ ## Plano de mudança
77
+ | # | Passo | Arquivos | Commit |
78
+ ```
79
+
80
+ ## Próximo
81
+
82
+ - `accessibility-review` para cada tela nova ou alterada.
83
+ - `web-performance` quando houver metas de Core Web Vitals.
84
+ - `ts-code-review` revisa as mudanças; `ts-testing` para hooks e funções puras.
85
+
86
+ ## No Forja
87
+
88
+ No Forja, a estrutura alvo e as regras de dados ficam em `memory/20-architecture/frontend.md`; trocas de biblioteca ou de estratégia de renderização viram ADR em `memory/90-decisions/`. Rode `forja sync:universal` depois de gravar.
89
+
90
+ ## Evite
91
+
92
+ - Dados do servidor duplicados numa store global.
93
+ - `fetch` em `useEffect` espalhado pelos componentes.
94
+ - `'use client'` no topo de árvores grandes.
95
+ - Uma pasta `components/` com todos os componentes do app.
96
+ - Regra de negócio dentro de componentes.
97
+ - Reescrever o front-end inteiro de uma vez.
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: incident-postmortem
3
+ description: Use depois de um incidente em produção: escreve um postmortem sem culpados, com o impacto em números, uma linha do tempo em UTC, fatores contribuintes encontrados com os 5 Porquês, o que deu certo e ações com dono para prevenir, detectar e mitigar uma recorrência.
4
+ ---
5
+
6
+ # Postmortem de Incidente
7
+
8
+ Um postmortem transforma um incidente em aprendizado. Ele é **sem culpados**: as pessoas agiram de forma razoável com a informação e as ferramentas que tinham, então a pergunta é o que no sistema deixou a falha acontecer e se espalhar, não quem errou.
9
+
10
+ A saída padrão é um **documento de postmortem**. Ele é escrito a partir das evidências que o usuário fornece; o que não tem evidência é marcado como não confirmado.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: alertas, dashboards e logs de `observability`; transcrições do chat e do canal do incidente; histórico de deploys e mudanças (`git log`, execuções do CI); as pessoas envolvidas, por meio do usuário.
15
+ - Horários em UTC, com a fonte de cada entrada.
16
+ - Refira-se às pessoas pelo papel ("a pessoa de plantão"), não pelo nome.
17
+ - Idioma: o do usuário. Termos técnicos como o time os usa.
18
+ - Incógnitas vão para **Perguntas em aberto**. Nunca invente uma entrada na linha do tempo ou uma causa.
19
+
20
+ ## Linguagem sem culpados
21
+
22
+ - Descreva ações e decisões, e o contexto que as tornou razoáveis: "O deploy rodou sem canary porque o pipeline não tinha etapa de canary."
23
+ - Não "X esqueceu", "X deveria ter", "erro humano". Erro humano é um sintoma; pergunte o que tornou o erro fácil e o efeito dele grande.
24
+ - Contrafactuais ("se ao menos tivessem…") vão para as ações, não para a narrativa.
25
+
26
+ ## Processo
27
+
28
+ ### 1. Impacto
29
+ Em números: duração (início → mitigado → resolvido), usuários ou requisições afetados, taxa de erro, dados perdidos ou corrompidos, dinheiro, orçamento de erro do SLO consumido, implicações contratuais ou de LGPD (um incidente com dados pessoais pode exigir comunicação à ANPD: verifique com `lgpd-compliance`).
30
+
31
+ ### 2. Linha do tempo
32
+ Do primeiro gatilho (muitas vezes uma mudança dias antes) até a resolução. Marque os momentos-chave: **gatilho**, **detecção** (como: alerta, cliente, acaso), **início da resposta**, **mitigação**, **resolução**. Calcule o tempo até a detecção e o tempo até a mitigação.
33
+
34
+ ### 3. Fatores contribuintes
35
+ Sistemas complexos raramente falham por uma causa só. Liste os fatores que se combinaram: o gatilho, as condições latentes que permitiram que ele quebrasse as coisas, o que atrasou a detecção e o que desacelerou a mitigação. Para cada um, pergunte "por quê?" até chegar a algo que o time consiga mudar (5 Porquês), e pare aí.
36
+
37
+ ### 4. O que deu certo, o que deu errado, onde tivemos sorte
38
+ Sorte é um achado: ela marca uma defesa que ainda não existe.
39
+
40
+ ### 5. Ações
41
+ - Cada uma trata de um fator contribuinte e é de um destes tipos: **prevenir** (impedir o gatilho ou a condição latente), **detectar** (alertar mais cedo), **mitigar** (impacto menor, recuperação mais rápida).
42
+ - Específicas, com dono (um papel ou time), com ticket e com data. "Ter mais cuidado" não é uma ação.
43
+ - Prefira mudanças no sistema (testes, proteções, automação, alertas) a lembretes de processo.
44
+ - Poucas ações concluídas valem mais que uma lista longa que apodrece.
45
+
46
+ ## Formato
47
+
48
+ ```
49
+ # Postmortem: <título> — <data>
50
+ Status: <rascunho | revisado> · Severidade: <SEV-n> · Autores: <papéis>
51
+
52
+ ## Resumo
53
+ <3–4 frases: o que aconteceu, impacto, causa em resumo, estado atual>
54
+
55
+ ## Impacto
56
+ | Métrica | Valor |
57
+
58
+ ## Linha do tempo (UTC)
59
+ | Horário | Evento | Fonte |
60
+ Tempo até detectar: … · Tempo até mitigar: … · Tempo até resolver: …
61
+
62
+ ## Fatores contribuintes
63
+ ### <fator>
64
+ <descrição> — Cadeia de porquês: … → …
65
+
66
+ ## O que deu certo / errado / onde tivemos sorte
67
+
68
+ ## Ações
69
+ | # | Ação | Tipo (prevenir/detectar/mitigar) | Fator | Dono | Ticket | Prazo |
70
+
71
+ ## Perguntas em aberto
72
+ ```
73
+
74
+ ## Próximo
75
+
76
+ - `requirements-gathering`: `RNF-NN` novos a partir das ações.
77
+ - `testing`: um teste de regressão para o modo de falha.
78
+ - `observability`: alertas novos ou mudanças de SLO para as lacunas de detecção.
79
+ - `architecture-decision-record` quando a correção for uma mudança de design.
80
+ - `executive-writing` para um resumo curto à liderança ou aos clientes.
81
+
82
+ ## No Forja
83
+
84
+ No Forja, registre o incidente no grafo de engenharia com `forja incident:record --title "<título>" --description "<resumo>"`; incidentes parecidos aparecem em `forja incident:similar`. O documento do postmortem fica em `memory/60-runs/postmortems/<data>-<slug>.md`.
85
+
86
+ ## Evite
87
+
88
+ - Nomes e culpa, inclusive culpa implícita ("apesar do runbook…").
89
+ - Uma única causa raiz quando vários fatores se combinaram.
90
+ - Ações sem dono ou sem data.
91
+ - "Monitorar mais de perto" ou "ter mais cuidado" como ações.
92
+ - Linhas do tempo reconstruídas de memória, sem fontes.
93
+ - Publicar antes de as pessoas envolvidas revisarem.
@@ -0,0 +1,108 @@
1
+ ---
2
+ name: lgpd-compliance
3
+ description: Use quando desenhar ou revisar um sistema, funcionalidade ou modelo de dados que trata dados pessoais sob a LGPD: classifica os dados, atribui bases legais, retenção e direitos dos titulares, e deriva os controles técnicos.
4
+ ---
5
+
6
+ # Conformidade com a LGPD
7
+
8
+ Aplica a LGPD (Lei nº 13.709/2018) a um sistema, funcionalidade ou modelo de domínio, pelo lado da engenharia: que dados existem, por que são tratados, com qual base legal, por quanto tempo, quem pode acessá-los e quais controles técnicos decorrem disso.
9
+
10
+ Isto é **conformidade desde a concepção** (privacy by design), não aconselhamento jurídico. Toda saída termina com os pontos que precisam ser validados pelo Encarregado ou pelo jurídico.
11
+
12
+ ## Convenções
13
+
14
+ - Termos jurídicos em pt-BR seguidos do en-US: Titular (Data Subject), Controlador (Controller), Operador (Processor), Encarregado (DPO), Tratamento (Processing), Base Legal (Legal Basis), Dado Pessoal Sensível (Sensitive Personal Data), Anonimização (Anonymization), Pseudonimização (Pseudonymization), RIPD (Data Protection Impact Assessment), ANPD (National Data Protection Authority).
15
+ - Cite os artigos da LGPD ao enunciar uma obrigação, para que possa ser verificada.
16
+ - Não invente bases legais nem prazos de retenção. Itens desconhecidos vão para **Perguntas em aberto**.
17
+ - As regulamentações da ANPD mudam. Quando um prazo ou procedimento depender de regulamento da ANPD, sinalize-o para verificação contra o texto vigente.
18
+
19
+ ## Princípio central
20
+
21
+ A conformidade começa pela **finalidade**. Todo dado pessoal precisa responder: para quê, com qual base, por quanto tempo. Um dado que não consegue responder é um dado que não deveria ser coletado (princípio da necessidade, Art. 6º, III).
22
+
23
+ ## Processo
24
+
25
+ ### 1. Inventariar os dados
26
+ Liste cada dado pessoal que o sistema coleta, deriva ou recebe de outros sistemas. Inclua os não óbvios: endereços IP, IDs de dispositivo, logs, geolocalização, campos de texto livre, uploads de arquivos, dados dentro de eventos e filas, backups.
27
+
28
+ ### 2. Classificar cada dado
29
+ | Classe | Definição | Artigo |
30
+ |---|---|---|
31
+ | Dado pessoal | Identifica ou pode identificar uma pessoa natural. | Art. 5º, I |
32
+ | Dado pessoal sensível | Origem racial ou étnica, convicção religiosa, opinião política, filiação a sindicato ou a organização de caráter religioso, filosófico ou político, dado referente à saúde ou à vida sexual, dado genético ou biométrico. | Art. 5º, II |
33
+ | Dados de crianças e adolescentes | Exigem tratamento no seu melhor interesse; dados de crianças seguem regras específicas. | Art. 14 |
34
+ | Dado anonimizado | Não pode ser reidentificado por meios razoáveis. Fora do escopo enquanto permanecer anônimo. | Art. 5º, III; Art. 12 |
35
+ | Dado pseudonimizado | Continua sendo dado pessoal: a reidentificação é possível com a chave mantida separada. | Art. 13, §4º |
36
+
37
+ ### 3. Ligar o tratamento à finalidade e à base legal
38
+ Para cada finalidade (não para cada campo), declare a finalidade em uma frase, os dados usados e a base legal.
39
+
40
+ - **Dados pessoais** (Art. 7º): consentimento; cumprimento de obrigação legal ou regulatória; administração pública; estudos por órgão de pesquisa; execução de contrato; exercício regular de direitos; proteção da vida; tutela da saúde por profissionais ou serviços de saúde; interesse legítimo; proteção do crédito.
41
+ - **Dados sensíveis** (Art. 11): lista mais restrita. Interesse legítimo, execução de contrato e proteção do crédito **não** estão disponíveis. Tutela da saúde, obrigação legal ou regulatória, proteção da vida, exercício regular de direitos e prevenção à fraude e à segurança do titular são os candidatos habituais.
42
+ - O **consentimento** precisa ser livre, informado, inequívoco e para uma finalidade determinada, e pode ser revogado (Art. 8º). Prefira outra base quando uma de fato se aplicar; um sistema construído sobre consentimento precisa suportar a revogação.
43
+ - O **interesse legítimo** exige um teste de balanceamento e só os dados estritamente necessários (Art. 10).
44
+
45
+ ### 4. Definir a retenção e o término do tratamento
46
+ Para cada finalidade: por quanto tempo o dado é mantido, o que dispara o término (Art. 15) e o que acontece depois: exclusão, anonimização ou conservação sob uma exceção do Art. 16 (por exemplo, obrigação legal). Um prazo legal de retenção precisa ser nomeado, não suposto.
47
+
48
+ ### 5. Atender aos direitos dos titulares (Art. 18)
49
+ Para cada direito, declare como o sistema o atende ou por que não se aplica:
50
+ confirmação da existência de tratamento; acesso; correção; anonimização, bloqueio ou eliminação de dados desnecessários ou excessivos; portabilidade; eliminação dos dados tratados com consentimento; informação sobre compartilhamento; informação sobre a possibilidade de não consentir; revogação do consentimento. E também a revisão de decisões automatizadas (Art. 20), quando o sistema as toma.
51
+
52
+ Consequência para a engenharia: os dados pessoais precisam ser localizáveis por titular em tabelas, arquivos, eventos e backups. Se não podem ser encontrados, não podem ser devolvidos nem excluídos.
53
+
54
+ ### 6. Mapear compartilhamentos e transferências
55
+ Liste cada destinatário: operadores (nuvem, e-mail, analytics, provedores de IA), outros controladores, órgãos públicos. Para transferências para fora do Brasil, identifique o mecanismo do Art. 33. Os operadores agem segundo as instruções do controlador (Art. 39).
56
+
57
+ ### 7. Derivar os controles técnicos (Art. 46)
58
+ Escolha de forma proporcional ao risco:
59
+ - **Minimização**: não colete o que não tem finalidade; evite campos de texto livre que atraem dados sensíveis.
60
+ - **Segregação**: dados sensíveis em tabelas ou schema próprios, com acesso restrito.
61
+ - **Criptografia**: em trânsito, sempre; em repouso para dados sensíveis (no nível da coluna ou da aplicação quando o nível do banco não for suficiente).
62
+ - **Pseudonimização**: para analytics, BI e réplicas que não precisam da identidade.
63
+ - **Controle de acesso**: privilégio mínimo, por papel e por finalidade; segurança por linha (row-level security) onde uma tabela atende vários contextos.
64
+ - **Trilha de auditoria**: registro somente de acréscimo de quem acessou ou alterou dados pessoais, quando e por quê. Na prática, exigido para responder a direitos e incidentes.
65
+ - **Logs e observabilidade**: nada de dados pessoais em logs, traces, labels de métricas ou mensagens de erro. Mascare por padrão.
66
+ - **Exclusão de verdade**: soft delete não é exclusão. Defina como a exclusão ou a anonimização chega a réplicas, caches, índices de busca, filas e backups.
67
+ - **Ambientes fora de produção**: nada de dados pessoais reais em desenvolvimento ou teste sem anonimização.
68
+
69
+ ### 8. Avaliar a necessidade de um relatório de impacto
70
+ Recomende um RIPD (Art. 38) quando o tratamento envolver dados sensíveis em escala, tratamento em larga escala, monitoramento sistemático, tecnologias novas, decisões automatizadas com efeito significativo, ou interesse legítimo como base para um tratamento de alto risco.
71
+
72
+ ### 9. Preparar-se para incidentes
73
+ Declare como um incidente de segurança seria detectado e dimensionado (quais titulares, quais dados). A comunicação à ANPD e aos titulares é obrigatória quando o incidente puder acarretar risco ou dano relevante (Art. 48); verifique o prazo no regulamento vigente da ANPD.
74
+
75
+ ## Formato de saída
76
+
77
+ ```
78
+ ## Inventário de dados
79
+ | Dado | Classe | Origem | Onde é armazenado | Finalidades |
80
+
81
+ ## Mapa de tratamento
82
+ | Finalidade | Dados | Base legal (artigo) | Retenção / gatilho de término | Destinatários |
83
+
84
+ ## Direitos dos titulares
85
+ | Direito | Como é atendido | Lacunas |
86
+
87
+ ## Controles técnicos
88
+ - <controle> — aplica-se a <dado/fluxo> — motivo
89
+
90
+ ## Relatório de impacto
91
+ <necessário / não necessário, e por quê>
92
+
93
+ ## Perguntas em aberto
94
+ - <base legal, prazo de retenção, contratos, transferências a validar com o Encarregado/jurídico>
95
+ ```
96
+
97
+ ## No Forja
98
+
99
+ No Forja, decisões de base legal, retenção e transferência viram ADR em `memory/90-decisions/`, e os requisitos derivados entram em §6 da spec (`specs/<slug>/spec.md`).
100
+
101
+ ## Evite
102
+
103
+ - Tratar o consentimento como base padrão para tudo.
104
+ - Supor que dados pseudonimizados estão fora da LGPD.
105
+ - Guardar dados "por via das dúvidas", sem finalidade nem prazo.
106
+ - Dados pessoais em logs, URLs, eventos de analytics ou fixtures de teste.
107
+ - Soft delete apresentado como exclusão.
108
+ - Apresentar conclusões como aconselhamento jurídico.
@@ -0,0 +1,18 @@
1
+ ---
2
+ name: llm-provider-routing
3
+ description: Use quando uma tarefa exige trocar de provedor ou modelo de LLM no Forja: seleciona, configura e verifica perfis, executa com contexto pela CLI, retoma sessões do Codex e valida as respostas com evidências.
4
+ ---
5
+
6
+ # Roteamento de LLMs
7
+
8
+ Siga o `AGENTS.md` do projeto. Para sintaxe e limites de cada comando, use `forja help <comando>`; não carregue catálogos de provedores sem necessidade.
9
+
10
+ 1. Identifique papel, tarefa, privacidade e restrições de custo/latência. Respeite a escolha autorizada pelo usuário; não troque modelo silenciosamente.
11
+ 2. Use `forja llm:profiles:init` e revise `.context/llm-profiles.json` no workspace. Configure um executável em `command`, argumentos em `commandArgs` e o identificador real do modelo. Não inclua credenciais nem comandos de shell.
12
+ 3. Execute `forja llm:probe <perfil>`. Registre versão e recursos detectados. Probe bem-sucedido não comprova autenticação nem acesso ao modelo.
13
+ 4. Consulte `forja llm:recommend --role <papel> --task <tipo>` como evidência auxiliar, sem tratar ranking como garantia de qualidade.
14
+ 5. Execute `forja llm:run --profile <perfil> --task <arquivo>`. Se necessário, use `--context <arquivo>` repetido. Confira o conteúdo antes de enviá-lo ao provedor.
15
+ 6. Para Codex compatível, use `--resume <session-id>` apenas com sessão conhecida no mesmo projeto/perfil. Use `--output-schema <arquivo>` e `--validation <manifest>` para formato e checks independentes. Revise os executáveis do manifest: eles rodam com permissões do Forja.
16
+ 7. Informe execução, validação, origem do uso de tokens e custo separadamente. Schema sozinho não comprova qualidade. Não afirme custo zero quando ele é desconhecido.
17
+
18
+ Se não houver adapter ou CLI compatível, explique a lacuna e configure um wrapper revisável somente dentro do escopo autorizado. Não invente suporte a API, MCP ou recursos de sessão. Não recomende um provedor por reputação sem evidência atual da tarefa.
@@ -0,0 +1,93 @@
1
+ ---
2
+ name: observability
3
+ description: Use quando preparar um serviço ou funcionalidade para produção: deriva SLIs e SLOs dos requisitos não funcionais, planeja métricas, logs estruturados e traces, e define alertas baseados em sintomas, cada um com um esboço de runbook.
4
+ ---
5
+
6
+ # Observabilidade
7
+
8
+ Um sistema é observável quando você consegue responder a uma pergunta nova sobre o comportamento dele em produção sem publicar código novo. O objetivo não são dashboards: é saber que os usuários estão sofrendo antes que eles avisem, e descobrir o porquê rápido.
9
+
10
+ A saída padrão é um **plano de observabilidade**: SLOs, sinais e alertas. Escreva código de instrumentação só quando o usuário pedir.
11
+
12
+ ## Convenções
13
+
14
+ - Entradas: `RNF-NN` mensuráveis de `requirements-gathering`; endpoints de `api-design`; classificação de dados pessoais de `lgpd-compliance`; eventos de segurança de `threat-modeling`.
15
+ - Siga o código existente: a biblioteca de log, o backend de métricas e a configuração de tracing. Use [OpenTelemetry](https://opentelemetry.io/) e suas convenções semânticas como padrão quando não houver nada.
16
+ - Tráfego, metas ou escalas de plantão desconhecidos vão para **Perguntas em aberto**. Não invente metas de SLO; derive-as ou pergunte.
17
+
18
+ ## SLIs e SLOs
19
+
20
+ - Um **SLI** mede o que o usuário experimenta, como a razão entre eventos bons e eventos válidos: disponibilidade (respostas não-5xx / todas as respostas), latência (requisições abaixo de X ms / todas as requisições), atualidade, correção.
21
+ - Um **SLO** é a meta de um SLI numa janela: "99,5% dos `POST /orders` abaixo de 300 ms em 28 dias".
22
+ - Derive cada SLO de um `RNF-NN`. Quando o requisito não for mensurável, devolva-o para `requirements-gathering`.
23
+ - O **orçamento de erro** (100% − SLO) é o que os alertas e as decisões de release consomem.
24
+ - Poucos SLOs, nas jornadas de usuário que importam. Não um por endpoint.
25
+
26
+ ## Métricas
27
+
28
+ - **RED** para serviços guiados por requisições: Taxa (Rate), Erros, Duração (como histograma, nunca média).
29
+ - **USE** para recursos: Utilização, Saturação, Erros (pools, filas, CPU, memória).
30
+ - **Métricas de negócio** que dizem se a funcionalidade funciona: pedidos criados, pagamentos que falharam.
31
+ - Só labels com cardinalidade limitada: template da rota, método, classe do status. Nunca IDs de usuário, e-mails ou URLs cruas.
32
+
33
+ ## Logs
34
+
35
+ - Estruturados (JSON), um evento por linha, com `timestamp`, `level`, `message`, `service`, `trace_id` e os identificadores de domínio necessários para investigar (ID do pedido, não o nome do cliente).
36
+ - Os níveis significam algo: `error` exige ação; `warn` é inesperado mas tratado; `info` é um evento de negócio ou de ciclo de vida; `debug` fica desligado em produção.
37
+ - **Nada de dados pessoais, segredos ou tokens** nos logs (conforme `lgpd-compliance`). Quando for preciso um identificador, use um ID pseudônimo.
38
+ - Registre nas fronteiras e nas decisões, não em toda linha. Registre cada erro uma vez, onde ele é tratado.
39
+ - Os eventos de segurança de `threat-modeling` (falhas de autenticação, permissões negadas, acionamentos do limite de taxa) são registrados com o ator e o objeto.
40
+
41
+ ## Traces
42
+
43
+ - Propague o contexto em toda fronteira: HTTP, filas, jobs (W3C Trace Context).
44
+ - Spans para requisições de entrada, chamadas de saída, consultas ao banco e operações de fila, com atributos semânticos.
45
+ - Amostre por taxa, mas mantenha todos os traces de erro e os lentos quando o backend suportar amostragem na cauda (tail sampling).
46
+
47
+ ## Alertas
48
+
49
+ - Alerte sobre **sintomas** que os usuários sentem (taxa de consumo do SLO), não sobre causas (CPU em 80%).
50
+ - Use alertas de taxa de consumo com múltiplas janelas: consumo rápido aciona plantão (por exemplo, 2% do orçamento em 1 h), consumo lento abre um ticket (por exemplo, 10% em 3 dias).
51
+ - Todo acionamento de plantão é acionável, urgente e precisa de um humano. O resto é ticket ou dashboard.
52
+ - Todo alerta aponta para um esboço de runbook: o que significa, primeiras verificações, mitigação, escalonamento.
53
+
54
+ ## Formato
55
+
56
+ ```
57
+ ## SLOs
58
+ | SLO | SLI (bons / válidos) | Meta | Janela | Origem |
59
+ |---|---|---|---|---|
60
+ | Latência de criação de pedido | POST /orders < 300 ms / todos os POST /orders | 99,5% | 28d | RNF-03 |
61
+
62
+ ## Métricas
63
+ | Nome | Tipo | Labels | Finalidade |
64
+
65
+ ## Logs
66
+ <eventos por caso de uso: nível, mensagem, campos>
67
+
68
+ ## Traces
69
+ <fronteiras instrumentadas, amostragem>
70
+
71
+ ## Alertas
72
+ | Alerta | Condição | Severidade (plantão/ticket) | Runbook |
73
+
74
+ ## Esboços de runbook
75
+ ### <Alerta>
76
+ Significado: … Primeiras verificações: … Mitigação: … Escalonamento: …
77
+
78
+ ## Perguntas em aberto
79
+ ```
80
+
81
+ ## Próximo
82
+
83
+ - `testing`: verifique que os eventos de negócio críticos e os erros são registrados e medidos.
84
+ - `pull-request`: liste os sinais e alertas novos em "O quê".
85
+
86
+ ## Evite
87
+
88
+ - Alertar sobre toda métrica de causa.
89
+ - Médias para latência.
90
+ - Labels de alta cardinalidade.
91
+ - Dados pessoais, segredos ou corpos inteiros de requisição em logs ou atributos de span.
92
+ - SLOs em 100%, ou metas tiradas do nada.
93
+ - Dashboards que ninguém olha em vez de alertas que importam.
@@ -0,0 +1,130 @@
1
+ ---
2
+ name: product-evaluation
3
+ description: Use quando uma ideia de produto, startup, app, SaaS ou modelo de negócio precisa de uma avaliação crítica de viabilidade: põe à prova problema, mercado, escopo, concorrência, go-to-market e economia unitária, e devolve um veredito GO / WEAK GO / NO-GO com riscos e recomendações.
4
+ ---
5
+
6
+ # Avaliação de Produto
7
+
8
+ Põe um conceito de produto à prova contra a realidade do mercado antes que alguém gaste dinheiro para construí-lo. Entrada: um conceito (app, SaaS, plataforma, ferramenta ou serviço) com o que se sabe sobre público, funcionalidades, monetização e mercado. Saída: um veredito com a evidência por trás dele. Não é para dúvidas de implementação nem para redação de negócios em geral.
9
+
10
+ A avaliação não existe para encorajar. Existe para revelar os problemas enquanto ainda são baratos.
11
+
12
+ ## Convenções
13
+
14
+ - Termos em pt-BR seguidos do en-US: Proposta de Valor (Value Proposition), Adequação Produto-Mercado (Product-Market Fit), Custo de Aquisição de Cliente (Customer Acquisition Cost, CAC), Valor do Tempo de Vida do Cliente (Customer Lifetime Value, LTV), Custo de Troca (Switching Cost), Partida a Frio (Cold Start), Canal de Aquisição (Acquisition Channel).
15
+ - Toda afirmação traz sua natureza: **confirmada** (evidência fornecida ou encontrada), **suposta** (afirmada sem evidência), **desconhecida** (ninguém sabe ainda).
16
+ - Nomeie segmentos de forma concreta: não "PMEs", mas "uma agência de 3 pessoas que fatura 5+ clientes à mão, sem ninguém de operações".
17
+
18
+ ## Princípio central
19
+
20
+ O ceticismo é o padrão; o otimismo se conquista com evidência. Avalie o produto como descrito, não o pitch no melhor cenário: "vai viralizar" é uma suposição não validada, não uma estratégia de crescimento. Mas a falsa negatividade é tão prejudicial quanto a falsa positividade: se o produto é sólido, diga isso com clareza.
21
+
22
+ Seja específico. "Pode ser difícil de vender" é inútil; "a aquisição depende de SEO num espaço dominado por domínios de 10 anos" é útil.
23
+
24
+ ## Processo
25
+
26
+ ### 1. Problema e mercado
27
+ Interrogue o problema antes da solução.
28
+ - É real e recorrente, ou episódico e de nicho?
29
+ - Quem exatamente o tem?
30
+ - Qual o contorno atual? Se é uma planilha, por que ninguém construiu isso, ou por que as ferramentas existentes falharam?
31
+ - É analgésico (precisa resolver agora) ou vitamina (bom de ter)?
32
+ - O mercado cresce, está estável ou encolhe, e por quê? Há forças regulatórias, sazonais ou estruturais?
33
+
34
+ ### 2. Produto e escopo
35
+ Julgue as funcionalidades contra o problema e o usuário real, não contra o roadmap.
36
+ - A **ação de valor central**: a única coisa que o usuário precisa conseguir fazer para o produto ter entregado valor. Ela está priorizada?
37
+ - Quais funcionalidades a servem, e quais são especulativas ou exageradas antes de o núcleo ser validado?
38
+ - Que capacidade crítica um usuário sentiria falta de imediato?
39
+ - Superfície de risco técnico: APIs externas, qualidade dos dados, custo de infraestrutura em escala.
40
+ - O fluxo é realista para o usuário de verdade: atrito de onboarding, curva de aprendizado, comportamento inesperado?
41
+
42
+ ### 3. Concorrência e posicionamento
43
+ - Concorrentes diretos e indiretos, incluindo processos manuais, ferramentas estabelecidas e soluções adjacentes.
44
+ - Diferenciação estrutural (abordagem, modelo, execução), não "fazemos melhor".
45
+ - É defensável por 18 meses, ou será copiado assim que um player maior vir o nicho comprovado?
46
+ - Custos de troca criados. Sem eles, a retenção é uma luta constante.
47
+ - Risco de comoditização: está construído sobre uma camada que pode se tornar irrelevante (por exemplo, um invólucro fino sobre uma API de LLM que muda rápido)?
48
+
49
+ ### 4. Go-to-market e distribuição
50
+ Falha de distribuição mata mais produtos do que falha de produto.
51
+ - **Canal zero**: os 10 primeiros clientes, conquistados como, por quem?
52
+ - É executável pelos fundadores agora, ou exige recursos que eles não têm?
53
+ - Há um ciclo viral ou de indicação embutido, ou o crescimento vem só de mídia paga ou SEO?
54
+ - Ciclo de venda: autosserviço B2C vs. B2B com várias partes interessadas.
55
+ - Porteiros: lojas de apps, compras, jurídico, revisões de segurança de TI.
56
+ - A mensagem é específica o bastante para ressoar com alguém?
57
+
58
+ ### 5. Monetização e economia unitária
59
+ Verifique se o modelo é internamente consistente, não só plausível.
60
+ - O modelo de preço está alinhado a como os usuários percebem o valor?
61
+ - Há evidência de disposição a pagar (benchmarks, produtos análogos, pesquisa), ou é suposição?
62
+ - CAC:LTV com conversão e churn realistas, não otimistas.
63
+ - Vetores de custo em escala: computação, suporte, licenciamento de dados, compliance.
64
+ - Caminho até a economia unitária positiva, e em que escala?
65
+ - E se o principal canal de aquisição ficar 2× mais caro?
66
+
67
+ ### 6. Testes transversais
68
+ Aplique a todas as áreas acima:
69
+ - **Partida a frio**: o valor exige massa crítica? Como ela é formada?
70
+ - **Cadeias de dependência**: quais sistemas, APIs, plataformas ou regulações precisam se manter? O que quebra se mudarem?
71
+ - **Execução**: o time descrito consegue construir? O que está subestimado?
72
+ - **Momento**: cedo demais, agora, ou já passou do pico?
73
+ - **Uso real**: o que acontece quando os usuários fazem o inesperado?
74
+ - **Efeitos de segunda ordem**: o sucesso cria problemas novos (carga de suporte, custo de infraestrutura, atenção regulatória)?
75
+
76
+ ### 7. Veredito
77
+ - **GO**: o problema é real, existe um canal até os primeiros clientes, a conta fecha; os riscos restantes são conhecidos.
78
+ - **WEAK GO**: viável só se incógnitas específicas forem resolvidas antes; nomeie-as.
79
+ - **NO-GO**: uma falha estrutural que nenhum esforço razoável corrige.
80
+
81
+ Nomeie o único fator mais decisivo.
82
+
83
+ ### 8. Encaminhamento
84
+ Incógnitas a investigar → `requirements-elicitation`; escopo de um GO → `requirements-gathering`; riscos técnicos → `technical-spike`; dados pessoais → `lgpd-compliance`; veredito para as partes interessadas → `executive-writing`.
85
+
86
+ ## Formato de saída
87
+
88
+ ```
89
+ # Avaliação de produto: <produto>
90
+
91
+ ## Veredito
92
+ <GO | WEAK GO | NO-GO> — <um parágrafo nomeando o fator mais decisivo>
93
+
94
+ ## Pontos fortes
95
+ - <ponto forte específico> (ou: nenhum ponto forte claro)
96
+
97
+ ## Pontos fracos
98
+ 1. <problema estrutural ou de execução, do mais grave ao menos grave>
99
+
100
+ ## Riscos e incógnitas
101
+ - Conhecidos: <visíveis, gerenciáveis com esforço>
102
+ - Desconhecidos: <pontos cegos que exigem descoberta antes de seguir>
103
+ - Dependências externas: <fora do controle do time>
104
+
105
+ ## Recomendações
106
+ 1. <ação específica> — impacto: <...> — dificuldade/custo: <...>
107
+
108
+ ## Uso realista vs. idealizado
109
+ | Projetado para | Provavelmente usado para | Diferença |
110
+
111
+ ## Dependências e restrições
112
+ - Técnicas: ...
113
+ - Regulatórias: ...
114
+ - Momento de mercado: ...
115
+ - Time: ...
116
+ - Capital: ...
117
+
118
+ ## Encaminhamento
119
+ - <skill>: <o que vai para lá>
120
+ ```
121
+
122
+ ## Evite
123
+
124
+ - Consolo, rodeios ou enchimento.
125
+ - Feedback genérico que serviria para qualquer produto.
126
+ - Tratar as projeções do fundador ("viral", "todo mundo precisa disso") como evidência.
127
+ - Apresentar suposições como confirmadas.
128
+ - Negatividade sem razão estrutural; um produto sólido recebe um GO claro.
129
+ - Recomendações sem ordem, custo ou dificuldade.
130
+ - Desenhar a solução: telas, stack, arquitetura.