nexus-core-v3 3.0.0

package/tasks/verify-subtask.md

@@ -0,0 +1,52 @@
+---
+id: verify-subtask
+agent: dev
+title: Verificar uma subtask pela verificação configurada
+inputs: [subtask-id, implementation.yaml]
+outputs: [veredito da verificação: pass/fail, evidência]
+elicit: false
+modes: [yolo, interactive]
+---
+
+# Verificar uma subtask pela verificação configurada
+
+**Objetivo:** provar objetivamente que uma subtask implementada atende ao seu critério, rodando o
+método de verificação que o plano definiu — e emitir um veredito com evidência.
+
+**Pré-condições:**
+- A subtask está `done` (foi implementada via `execute-subtask`). Se ainda está aberta, **pare**:
+  não há o que verificar.
+- A subtask tem um bloco `verify` no `implementation.yaml` com um dos tipos: `command`, `api`,
+  `browser` ou `e2e`. Sem método de verificação definido, **pare** e devolvo ao @architect.
+
+## Passos
+
+1. **Leio o bloco `verify`** da subtask e identifico o tipo de verificação configurado.
+2. **Executo a verificação conforme o tipo:**
+   - `command` → rodo o comando declarado (ex.: teste, lint, build) e checo exit code 0 + saída
+     esperada.
+   - `api` → faço a chamada ao endpoint declarado e confiro status/payload contra o esperado.
+   - `browser` → navego à URL declarada e checo o estado/elemento esperado (consumidor de browser,
+     não administrador de MCP).
+   - `e2e` → rodo o fluxo end-to-end declarado e confiro o resultado final.
+3. **Comparo o resultado com o esperado** definido no `verify`. Igual → `pass`. Diferente → `fail`.
+4. **Registro a evidência** (saída do comando, status da resposta, screenshot/estado) junto ao
+   veredito — quem vem depois confia nesse rastro.
+5. **Emito o veredito:**
+   - `pass` → marco a subtask como verificada e libero a próxima na cadeia.
+   - `fail` → devolvo a subtask ao loop de implementação (`execute-subtask`) com o diff esperado×obtido.
+
+## Critério de pronto (DoD)
+
+- [ ] A verificação do tipo configurado foi executada de fato (não presumida)
+- [ ] Resultado comparado contra o esperado, com evidência registrada
+- [ ] Veredito `pass`/`fail` emitido e a subtask roteada conforme o veredito
+
+## Falha / recuperação
+
+- **A verificação falha (`fail`)** → devolvo ao `execute-subtask` com o delta esperado×obtido; não
+  marco verificada uma subtask que não passou.
+- **O método de verificação está quebrado/indisponível** (comando inexistente, endpoint fora do ar)
+  → HALT e reporto; o `verify` precisa ser corrigido no plano, não ignorado.
+- **A subtask passa mas quebra regressão em outra área** → reporto a regressão; não dou por verde
+  algo que verde-localmente mas vermelho-no-conjunto.

package/tasks/version-management.md

@@ -0,0 +1,45 @@
+---
+id: version-management
+agent: devops
+title: Analisar e recomendar o bump semântico
+inputs: [diff desde a última tag]
+outputs: [bump recomendado (MAJOR/MINOR/PATCH), próxima versão]
+elicit: false
+modes: [interactive, yolo]
+---
+
+# Analisar e recomendar o bump semântico
+
+**Objetivo:** analisar o diff desde a última tag e recomendar o próximo incremento semântico (MAJOR,
+MINOR ou PATCH), com a próxima versão calculada — base para a `release-management`.
+
+**Pré-condições:**
+- O repositório tem histórico git e ao menos uma referência de versão (tag ou versão em manifesto). Se
+  não há nenhuma, **pare** e proponha `v0.1.0` como ponto de partida.
+
+## Passos
+
+1. **Detecte o contexto do repositório** — remoto, branch base e a última tag (`git describe --tags
+   --abbrev=0`). Nunca assuma repo fixo.
+2. **Colete o diff desde a última tag** (`git log {ultima-tag}..HEAD --oneline`) — os commits que
+   entrarão na próxima versão. Sem commits novos → não há bump a recomendar; reporte.
+3. **Classifique os commits** pelos prefixos conventional: `feat!`/`BREAKING CHANGE` → MAJOR; `feat`
+   → MINOR; `fix`/`perf` → PATCH; `chore`/`docs`/`refactor` sem efeito externo → sem bump por si.
+4. **Determine o maior bump presente.** Um breaking change manda MAJOR; sem breaking, qualquer feature
+   manda MINOR; só fixes mandam PATCH. Aplique sobre a última versão para obter a próxima.
+5. **Reporte a recomendação** — bump, próxima versão e os commits que justificam cada nível, para que o
+   usuário confirme antes de uma release.
+
+## Critério de pronto (DoD)
+
+- [ ] Última versão detectada dinamicamente
+- [ ] Diff desde a última tag coletado e classificado por tipo
+- [ ] Bump recomendado coerente com SemVer (maior nível presente vence)
+- [ ] Próxima versão calculada e justificada pelos commits reais
+
+## Falha / recuperação
+
+- **Sem tag base** → proponho `v0.1.0` e sigo a partir daí; não invento histórico.
+- **Commits sem padrão conventional** → não infiro escopo; sinalizo a ambiguidade e recomendo bump
+  conservador (PATCH) até o usuário esclarecer.
+- **Sem commits novos desde a tag** → reporto "nada a versionar"; não recomendo bump vazio.

package/templates/README.md

@@ -0,0 +1,47 @@
+# NEXUS Templates — os esqueletos dos documentos
+
+Um template é o **esqueleto** de um documento que uma task preenche: a estrutura que captura o que
+importa, com placeholders `{assim}`. Se a task é o *como fazer*, o template é o *no que despejar*.
+Padronizar o esqueleto é o que faz dois PRDs (ou duas stories) terem a mesma forma, revisáveis pelo
+mesmo checklist.
+
+## Formato canônico
+
+Frontmatter YAML (metadados) + corpo Markdown com placeholders.
+
+```markdown
+---
+id: story-tmpl
+kind: template
+agent: sm                     # agente que tipicamente preenche
+produces: docs/stories/{epicNum}.{storyNum}.story.md   # onde o artefato preenchido mora
+---
+
+# {título do documento}
+
+## {Seção}
+{placeholder explicando o que vai aqui}
+```
+
+## Regras
+
+- **Placeholders são `{kebab-ou-livre}`** — o que a task substitui. Toda seção tem um placeholder ou
+  uma instrução curta do que entra.
+- **Sem invenção embutida.** O template estrutura; ele não inventa conteúdo. O conteúdo vem da task,
+  que rastreia a story/spec/objetivo.
+- **NEXUS-nativo.** `produces:` aponta para `docs/{tipo}/` (artefato produzido). Nada de frameworks
+  externos.
+- **Revisável.** A estrutura do template casa com o checklist que o valida (ex.: `story-tmpl` ↔
+  `story-draft-checklist`).
+
+## Onde os artefatos preenchidos moram
+
+| Template | Produz em |
+|---|---|
+| `story-tmpl` | `docs/stories/` |
+| `prd-tmpl` / `epic-tmpl` | `docs/prd/` |
+| `spec-tmpl` | `docs/specs/` |
+| `architecture-tmpl` | `docs/architecture/` |
+| `front-end-spec-tmpl` | `docs/design/` |
+| `project-brief-tmpl` / `competitor-analysis-tmpl` / `market-research-tmpl` | `docs/research/` |
+| `schema-design-tmpl` / `migration-plan-tmpl` / `rls-policies-tmpl` | `docs/data-models/` |

package/templates/architecture-tmpl.md

@@ -0,0 +1,115 @@
+---
+id: architecture-tmpl
+kind: template
+agent: architect
+produces: docs/architecture/{slug}-architecture.md
+---
+
+# Arquitetura: {nome do sistema/feature}
+
+**Status:** Draft
+**Classe de complexidade:** {SIMPLE / STANDARD / COMPLEX}
+**Camada:** {fullstack / backend / frontend / brownfield}
+**Rastreio:** {FRs/NFRs/CONs e achados de pesquisa que esta arquitetura serve}
+
+## Contexto e Objetivo
+
+> O quadro completo antes do desenho. Necessidade do usuário, restrição de negócio, capacidade do time.
+> Pensar do usuário pra trás. Sem invenção: cada linha rastreia a um FR/NFR/CON ou achado.
+
+- **Problema:** {o que o sistema precisa resolver}
+- **Usuário/jornada:** {quem usa e como — do usuário pra trás}
+- **Restrições de negócio:** {orçamento, prazo, conformidade}
+- **Fonte:** {docs/prd/..., docs/specs/..., docs/research/...}
+
+## Requisitos Não-Funcionais (NFRs)
+
+> NFR não declarado é a causa nº 1 de arquitetura que parece certa e quebra em produção. Declarar números.
+
+| NFR | Alvo | Fonte |
+|---|---|---|
+| Escala (RPS / usuários / volume) | {número} | {FR/NFR/CON} |
+| Latência (p50 / p95 / p99) | {ms} | {...} |
+| Disponibilidade (SLA) | {%} | {...} |
+| Segurança / conformidade | {requisito} | {...} |
+| Orçamento de infra | {custo-alvo} | {...} |
+
+## Decisões de Arquitetura
+
+> A decisão E o porquê. Decisão sem rastro vira mito de equipe em seis meses. Tecnologia chata por
+> padrão; empolgante só por exceção justificada.
+
+| # | Decisão | Alternativas descartadas | Trade-off (custo/risco) | Rastreio |
+|---|---|---|---|---|
+| AD-1 | {o que foi decidido} | {o que NÃO foi e por quê} | {o preço pago} | {FR/NFR/pesquisa} |
+| AD-2 | {...} | {...} | {...} | {...} |
+
+## Espinha Estrutural
+
+> Fronteiras de serviço, fluxo de dados, pontos de integração. Complexidade tem que ser ganha:
+> começar simples, projetar pra crescer.
+
+- **Componentes/serviços:** {o que existe e a responsabilidade de cada um}
+- **Fronteiras:** {onde uma parte termina e a outra começa — o contrato entre elas}
+- **Fluxo de dados:** {como o dado atravessa o sistema, do request à persistência}
+- **Diagrama:** {referência ou bloco — texto/mermaid}
+
+## Stack Tecnológico
+
+> Cada peça é um custo de operação, contratação e risco. Justificar o exótico.
+
+| Camada | Tecnologia | Por quê (justificativa chata-por-padrão) |
+|---|---|---|
+| {frontend} | {tech} | {razão} |
+| {backend} | {tech} | {razão} |
+| {dados} | {tech — tecnologia decidida aqui; DDL delegado ao @data-engineer} | {razão} |
+| {infra} | {tech} | {razão} |
+
+## Contratos de API e Integração
+
+> O contrato é a fronteira entre os donos das camadas. Definir aqui; implementação fica com o @dev.
+
+- **Estilo:** {REST / GraphQL / tRPC / WebSocket}
+- **Endpoints/operações principais:** {operação → entrada → saída}
+- **Integrações externas:** {serviço → protocolo → modo de falha}
+
+## Segurança e Custo
+
+> Camadas do design, não apêndices. Defesa em profundidade; conta de infra dentro da decisão.
+
+- **Defesa por camada:** {autenticação, autorização, validação, criptografia em trânsito/repouso}
+- **Superfície de ataque e mitigação:** {ameaça → controle}
+- **Modelo de custo:** {drivers de custo e estimativa por camada}
+
+## Failure Modes ao Escalar (Teste do 10×)
+
+> Toda fronteira passa pelo teste do 10×. Design sem o "o que quebra" é meio design.
+
+| Componente/fronteira | O que quebra a 10× | Sinal de alerta | Mitigação |
+|---|---|---|---|
+| {ex.: query do feed} | {N+1, hot path, ponto único de falha} | {métrica que avisa} | {o que fazer} |
+| {...} | {...} | {...} | {...} |
+
+## Roteamento por Especialista
+
+> Eu costuro o sistema; cada camada vai ao seu dono. Defino a fronteira e o contrato; o dono executa.
+
+| Camada / artefato | Dono | O que é delegado |
+|---|---|---|
+| Schema / DDL / RLS / índices / migration | @data-engineer | {decisão de tecnologia feita aqui; implementação lá} |
+| UX / fluxos / design system | @ux-design-expert | {fluxos a detalhar} |
+| Código de implementação | @dev | {a partir desta arquitetura} |
+| Quality gate | @qa | {após implementação} |
+| git push / PR / release / CI/CD | @devops | {sempre — exclusivo} |
+
+## Riscos e Pendências
+
+> O que ainda não está resolvido e precisa de decisão, pesquisa ou validação.
+
+- {risco / pergunta aberta — quem resolve e quando}
+
+## Change Log
+
+| Data | Mudança | Autor |
+|---|---|---|
+| {data} | {o quê} | @architect |

package/templates/competitor-analysis-tmpl.md

@@ -0,0 +1,87 @@
+---
+id: competitor-analysis-tmpl
+kind: template
+agent: analyst
+produces: docs/research/{slug}-competitor-analysis.md
+---
+
+# Análise Competitiva: {mercado/categoria}
+
+**Status:** Draft
+**Autor:** @analyst (Alex)
+**Data:** {data}
+**Decisão que esta análise destrava:** {posicionamento, gap de mercado, escopo do MVP}
+
+## Resumo Executivo
+
+> O "portanto" no topo. 3-5 frases: onde está o gap, quem é a ameaça real, o que recomendamos.
+
+{síntese do cenário competitivo e a oportunidade identificada}
+
+## Escopo da Análise
+
+> Limites do que foi analisado — para o leitor saber o que NÃO está coberto.
+
+- **Categoria/mercado:** {definição}
+- **Concorrentes incluídos:** {quantos e por que estes}
+- **Período dos dados:** {datas das fontes}
+- **Fontes:** {sites, relatórios, reviews — listadas; sem fonte = [hipótese]}
+
+## Mapa Competitivo
+
+> Cada concorrente classificado. Diretos resolvem o mesmo problema; indiretos resolvem o problema de outro jeito.
+
+| Concorrente | Tipo (direto/indireto/substituto) | Público | Posicionamento | Fonte |
+|---|---|---|---|---|
+| {nome} | {tipo} | {público} | {como se posiciona} | {url/relatório} |
+
+## Perfil dos Concorrentes-Chave
+
+> Detalhe dos 3-5 mais relevantes. Repetir bloco por concorrente.
+
+### {Concorrente}
+- **O que faz:** {oferta principal}
+- **Forças:** {o que faz bem — com evidência}
+- **Fraquezas:** {onde falha — com evidência ou [hipótese]}
+- **Modelo de receita:** {como ganha dinheiro}
+- **Sinais recentes:** {lançamentos, funding, mudanças — com fonte e data}
+
+## Comparação de Recursos
+
+> Matriz objetiva. Marca presença/ausência de cada capacidade relevante.
+
+| Recurso / capacidade | {Conc. A} | {Conc. B} | {Conc. C} | Nós (alvo) |
+|---|---|---|---|---|
+| {feature} | ✓ / ✗ / parcial | | | |
+
+## Posicionamento e Diferenciação
+
+> Onde cada um se planta e onde está o espaço vazio.
+
+- **Eixos de posicionamento:** {ex.: preço × sofisticação, nicho × amplo}
+- **Aglomerações:** {onde a maioria se concentra}
+- **Espaço em branco:** {a posição não ocupada — a oportunidade}
+
+## Forças e Fraquezas Agregadas (SWOT do mercado)
+
+> Leitura do tabuleiro como um todo, da nossa perspectiva.
+
+- **Oportunidades:** {gaps exploráveis — cada um rastreável a um achado acima}
+- **Ameaças:** {movimentos competitivos que nos atingiriam}
+
+## Implicações Estratégicas
+
+> O "e daí?". Como cada achado-chave informa nossa estratégia.
+
+- {achado} → {implicação para produto/posicionamento/preço}
+
+## Portanto — Recomendações
+
+> O handoff acionável. Sem recomendação inventada — cada uma liga a um achado.
+
+1. {recomendação} (baseada em: {achado}) → {@pm para estratégia / @architect para viabilidade}
+2. {...}
+
+## Perguntas em Aberto
+
+- {o que ainda precisa de validação} → {@analyst *perform-market-research / *research-prompt}

package/templates/epic-tmpl.md

@@ -0,0 +1,83 @@
+---
+id: epic-tmpl
+kind: template
+agent: pm
+produces: docs/prd/epic-{epicNum}-{slug}.md
+---
+
+# Epic {epicNum}: {nome do epic}
+
+**Status:** Draft
+**PRD de origem:** {docs/prd/...-prd.md}
+**Autor:** @pm (Morgan)
+**Data:** {data}
+
+## Objetivo do Epic
+
+> Uma fronteira limpa: o que este epic entrega, em uma frase. Rastreia aos objetivos do PRD.
+
+- **Entrega:** {capacidade coesa que este epic conclui}
+- **Rastreia a:** OBJ-{n} / FR-{n} do PRD
+- **Valor ao usuário:** {resultado concreto quando o epic fecha}
+
+## Critérios de Aceite do Epic
+
+> Como saber que o epic está "feito". Verificável, não vago.
+
+1. {critério de fechamento do epic — testável sim/não}
+
+## Stories previstas
+
+> O @pm estrutura o recorte; a CRIAÇÃO das stories é delegada ao @sm (Gate 1). Aqui só o esqueleto.
+
+| # | Título provável | Entrega | FR/NFR | Depende de |
+|---|---|---|---|---|
+| {epicNum}.1 | {título curto} | {o que cobre} | FR-{n} | {nenhuma / story X} |
+
+> **Delegação (Gate 1):** após este recorte, `@sm *draft` cria cada story; `@po *validate` valida.
+
+## Fronteiras e Dependências
+
+> O que está dentro, o que está fora, e de que este epic depende para começar.
+
+- **Dentro:** {escopo coberto}
+- **Fora:** {escopo deliberadamente excluído — evita inchaço}
+- **Depende de:** {outro epic / serviço / dado / decisão de arquitetura}
+- **Bloqueia:** {epics/stories que só podem rodar depois deste}
+
+## Agentes e Especialistas previstos
+
+> Qualidade é design: prevejo quem toca o quê antes de começar.
+
+| Trabalho | Dono |
+|---|---|
+| Stories | @sm |
+| Validação de story | @po |
+| Implementação | @dev |
+| Schema/dados | @data-engineer |
+| UI/UX | @ux-design-expert |
+| Arquitetura | @architect |
+| QA gate | @qa |
+| Subida (push/PR/release) | @devops |
+
+## Quality Gates do Epic
+
+> Os portões que cada story atravessa antes de o epic fechar.
+
+- Definition of Ready (@po) por story
+- QA Gate (@qa): {PASS exigido / NFRs verificados}
+- Pre-push (@devops) antes de qualquer subida
+
+## Sequenciamento (waves)
+
+> Se executado em ondas paralelas via `*execute-epic`, respeitando dependências.
+
+| Wave | Stories | Pode rodar em paralelo? | Pré-condição |
+|---|---|---|---|
+| 1 | {epicNum}.x | {sim/não} | {nenhuma / ...} |
+
+## Riscos do Epic
+
+| Risco | Impacto | Mitigação |
+|---|---|---|
+| {o que pode travar o epic} | {severidade} | {plano} |

package/templates/front-end-spec-tmpl.md

@@ -0,0 +1,110 @@
+---
+id: front-end-spec-tmpl
+kind: template
+agent: ux-design-expert
+produces: docs/design/{feature-ou-produto}-front-end-spec.md
+---
+
+# Especificação de Front-End — {nome da feature/produto}
+
+**Status:** Draft
+**Origem:** {PRD/spec/story que esta UX serve — ex.: docs/prd/...}
+**Plataformas-alvo:** {web / mobile web / app / desktop}
+
+> Esta spec traduz necessidade de usuário em estrutura de interface — fluxos, telas, componentes,
+> estados e regras de acessibilidade. Cada decisão aqui rastreia a um FR/NFR/CON ou a um achado de
+> pesquisa. Nada de UX inventada: sem fonte, não entra (No Invention).
+
+## Visão Geral de UX
+
+- **Problema do usuário:** {a dor real que esta interface resolve — fonte de pesquisa/PRD}
+- **Resultado esperado:** {o que a pessoa consegue fazer ao final — métrica de sucesso se houver}
+- **Princípios de design aplicados:** {ex.: clareza > densidade, mobile-first — cada um justificado}
+
+## Personas & Necessidades
+
+> Quem usa, o que precisa, em que contexto. Sem persona validada, marque como hipótese.
+
+| Persona | Necessidade-chave | Contexto de uso | Fonte |
+|---|---|---|---|
+| {persona} | {o que precisa fazer} | {dispositivo/ambiente/restrição} | {pesquisa/PRD} |
+
+## Fluxos de Usuário
+
+> Cada fluxo é uma jornada com começo, decisões e fim. Liste passos e os pontos onde algo pode falhar.
+
+### Fluxo: {nome do fluxo}
+- **Entrada (trigger):** {de onde o usuário chega}
+- **Passos:** {1 → 2 → 3, com decisões}
+- **Sucesso:** {estado final desejado}
+- **Caminhos de erro:** {o que dá errado e como a interface responde}
+- **Rastreabilidade:** {AC/FR que este fluxo satisfaz}
+
+## Arquitetura de Informação
+
+- **Mapa de navegação:** {hierarquia de telas/seções e como se conectam}
+- **Entradas principais:** {pontos de partida — menu, deep link, dashboard}
+- **Agrupamento de conteúdo:** {como a informação é organizada e por quê}
+
+## Inventário de Telas
+
+> Cada tela com seu propósito e o que ela precisa mostrar. O wireframe detalha; aqui é o índice.
+
+| Tela | Propósito | Elementos-chave | Fluxos que a usam |
+|---|---|---|---|
+| {tela} | {o que resolve} | {componentes/dados essenciais} | {fluxo(s)} |
+
+## Componentes (Atomic Design)
+
+> Mapeie cada elemento de UI ao nível atômico. Reaproveite o design system antes de propor novo.
+> Nada de valor hardcoded — cor/espaço/tipografia/raio vêm de design tokens.
+
+| Componente | Nível (átomo/molécula/organismo) | Novo ou existente | Tokens/variantes | Estados |
+|---|---|---|---|---|
+| {componente} | {nível} | {existente: ref / novo: justificar} | {tokens usados} | {default/hover/focus/disabled/loading/error} |
+
+## Estados & Feedback
+
+> Toda tela tem mais que o estado "feliz". Defina como a interface se comporta em cada situação.
+
+- **Vazio (empty):** {o que mostrar quando não há dados}
+- **Carregando (loading):** {skeleton/spinner — sem layout shift}
+- **Erro:** {mensagem acionável, não código cru}
+- **Sucesso/confirmação:** {feedback claro de que a ação funcionou}
+
+## Acessibilidade (WCAG AA — piso inegociável)
+
+> A11y não é etapa final, é critério de pronto. Estes pontos entram desde o desenho.
+
+- **Contraste:** {alvo AA — 4.5:1 texto normal, 3:1 texto grande/ícones}
+- **Foco visível:** {indicador de foco em todo elemento interativo}
+- **Navegação por teclado:** {ordem de tab lógica, sem armadilhas de foco}
+- **Semântica & leitores de tela:** {roles, labels, alt text, hierarquia de headings}
+- **Alvos de toque:** {tamanho mínimo para mobile}
+- **Movimento:** {respeitar prefers-reduced-motion quando houver animação}
+
+## Responsividade
+
+- **Breakpoints:** {mobile / tablet / desktop e o que muda em cada um}
+- **Estratégia:** {mobile-first / adaptação de layout / conteúdo prioritário por viewport}
+
+## Identidade Visual & Tokens
+
+> Referencie o design system. Se algum token novo for necessário, justifique e marque para extração.
+
+- **Tipografia:** {famílias/escala — via token}
+- **Paleta:** {cores semânticas — via token}
+- **Espaçamento & raio:** {escala — via token}
+- **Iconografia:** {set de ícones e regra de uso}
+
+## Rastreabilidade
+
+> Cada decisão de UX liga à sua origem. Linha sem fonte é UX inventada e não passa no gate.
+
+| Decisão de design | Origem (FR/NFR/CON/pesquisa) |
+|---|---|
+| {decisão} | {fonte} |
+
+## Itens em Aberto
+
+- {pergunta de design não resolvida, hipótese a validar, dependência de @architect/@dev}

package/templates/market-research-tmpl.md

@@ -0,0 +1,98 @@
+---
+id: market-research-tmpl
+kind: template
+agent: analyst
+produces: docs/research/{slug}-market-research.md
+---
+
+# Pesquisa de Mercado: {mercado/oportunidade}
+
+**Status:** Draft
+**Autor:** @analyst (Alex)
+**Data:** {data}
+**Decisão que esta pesquisa destrava:** {entrar no mercado? dimensionar oportunidade? validar demanda?}
+
+## Resumo Executivo
+
+> O "portanto" no topo. 3-5 frases: tamanho da oportunidade, dinâmica-chave, recomendação.
+
+{síntese da atratividade do mercado e o veredito acionável}
+
+## Objetivo e Metodologia
+
+> A pergunta que a pesquisa responde e como chegamos às respostas — para o leitor confiar (ou questionar) os números.
+
+- **Pergunta central:** {a decisão que isto destrava}
+- **Método:** {top-down / bottom-up / fontes secundárias / entrevistas}
+- **Fontes:** {relatórios, bases, entrevistas — listadas; sem fonte = [hipótese] marcada}
+- **Período dos dados:** {datas}
+
+## Dimensionamento do Mercado (TAM / SAM / SOM)
+
+> Cada número rastreia a uma fonte e mostra a conta. Sem fonte, vira hipótese explícita.
+
+| Camada | Definição | Valor | Como calculado | Fonte |
+|---|---|---|---|---|
+| TAM | {mercado total} | {valor} | {fórmula/premissa} | {url/relatório} |
+| SAM | {mercado endereçável} | {valor} | {fórmula/premissa} | {fonte} |
+| SOM | {mercado obtenível} | {valor} | {fórmula/premissa} | {fonte} |
+
+## Segmentos de Mercado
+
+> Quem compõe o mercado e qual segmento importa mais.
+
+| Segmento | Tamanho | Necessidade dominante | Disposição a pagar | Fonte |
+|---|---|---|---|---|
+| {segmento} | {%/valor} | {dor principal} | {alta/média/baixa} | {fonte} |
+
+## Tendências e Forças (drivers)
+
+> O que move o mercado. Cada tendência com direção e evidência.
+
+- **Crescimento/declínio:** {tendência} — {direção e taxa, com fonte}
+- **Tecnologia:** {mudança técnica relevante}
+- **Regulação:** {mudança regulatória relevante}
+- **Comportamento:** {mudança no comportamento do consumidor}
+
+## Análise de Demanda
+
+> Há demanda real, ou é desejo nosso? Sinais que comprovam (ou não).
+
+- **Sinais de demanda:** {buscas, listas de espera, adoção de adjacentes — com fonte}
+- **Gatilhos de compra:** {o que leva à decisão de compra}
+- **Barreiras de adoção:** {o que segura a compra}
+
+## Forças Competitivas (Porter, sintético)
+
+> Pressões estruturais do mercado. Liga ao competitor-analysis quando houver.
+
+- **Rivalidade:** {intensidade}
+- **Novos entrantes:** {facilidade de entrada}
+- **Poder de fornecedores/clientes:** {quem detém poder}
+- **Substitutos:** {alternativas fora da categoria}
+- **Fonte:** {docs/research/{slug}-competitor-analysis.md ou [hipótese]}
+
+## Oportunidades e Riscos
+
+> O tabuleiro lido em duas colunas. Cada item rastreável a um achado acima.
+
+| Oportunidade | Evidência | | Risco | Impacto |
+|---|---|---|---|---|
+| {oportunidade} | {achado/fonte} | | {risco} | {alto/médio/baixo} |
+
+## Implicações Estratégicas
+
+> O "e daí?". Como os números viram decisão.
+
+- {achado} → {implicação para entrada/timing/escopo}
+
+## Portanto — Recomendações
+
+> O handoff acionável. Cada recomendação liga a um achado; nada inventado.
+
+1. {recomendação} (baseada em: {achado/número}) → {@pm para PRD / @architect para viabilidade}
+2. {...}
+
+## Perguntas em Aberto
+
+- {lacuna de dado/incerteza} → {@analyst *research-prompt / *create-competitor-analysis}