spec-first-copilot 0.7.0-beta.1 → 0.7.0

package/templates/.github/templates/feature/PRD.template.md

@@ -1,279 +1,279 @@
-# PRD — {{NOME}}
-## Product Requirements Document
-
-> **Artefato gerado pela IA** a partir do processamento de insumos de produto em `workspace/Input/{{NOME}}/`.
-> Este é um dos dois docs source do pipeline SFW (peer do TRD).
-> O PRD é aprovado pelo **PM / product owner** — contém o "o quê" e "por quê" do produto.
-> Depois de aprovado, alimenta `/sf-merge-docs` (docs/ cross-feature) e `/sf-design` (specs/).
-
----
-
-## Meta
-
-| Campo | Valor |
-|-------|-------|
-| Scope | `{{NOME}}` |
-| Status | `em extração` → `aguardando aprovação (PM)` → `aprovado` |
-| Insumos processados | {{LISTA_INSUMOS}} |
-| Gerado em | |
-| Aprovado em | |
-| Aprovado por | {{nome do PM}} |
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-QUANDO USAR: Gerado pelo /sf-extract (chamado via /sf-start).
-QUEM GERA: Agent Produto-Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
-
-PAR COM TRD: o PRD é peer do TRD. Ambos podem coexistir (caso mais comum),
-ou o scope pode ter só um dos dois:
-- Scope puro-produto (raro): só PRD, sem TRD
-- Scope puro-técnico (bootstrap, mudança de stack): só TRD, sem PRD — NÃO GERAR ESTE ARQUIVO
-- Scope misto (maioria): ambos
-
-REGRA DE OURO: o Produto-Analyzer decide SE gera PRD baseado nos insumos.
-Se insumos não trazem conteúdo de produto (jornadas, RNs, UX, atores, telas),
-simplesmente NÃO gera. Não existe "PRD empty" — se é vazio, não existe.
-
-ZERO OVERLAP COM TRD:
-- Stack, schema, endpoints, validações de schema, deploy, ADRs → TRD
-- Jornadas, atores, RNs de negócio, UI, cenários de erro de produto → PRD
-- Integrações externas: PRD descreve POR QUÊ e O QUÊ; TRD descreve COMO
-- Validações: PRD descreve regras de DOMÍNIO (ex: "CPF válido", "idade >= 18");
-  TRD descreve validações de FORMATO (ex: "string, 11 chars, regex X")
-- NFRs: PRD descreve expectativa do usuário (ex: "resposta em < 1s");
-  TRD traduz em requisito técnico (ex: "P95 < 200ms no handler")
-
-COMO GERAR:
-1. Readers (Sonnet) leem cada arquivo do Input/ e catalogam por seção
-2. Produto-Analyzer (Opus) recebe outputs e:
-   a. Consolida conteúdo de produto em visão unificada
-   b. Cruza fontes — detecta contradições
-   c. Identifica gaps — seções sem info viram ambiguidades
-   d. Gera as 13 seções abaixo
-3. Consultar `docs/` ANTES de marcar ambiguidade — se `docs/domain.md` já
-   define ator ou jornada genérica, usar. Marcar "resolvido em docs/X §Y"
-4. Registrar DE QUAL insumo veio cada informação (rastreabilidade §13)
-5. Se faltam dados pra preencher seção relevante → pergunta BLOQUEANTE em §12
-
-FORMATOS DE INSUMO:
-- .txt, .md → requisitos, regras, contexto, restrições
-- .html → telas, fluxos, permissões (dados técnicos vão pro TRD)
-- .xml (drawio) → fluxos, decisões, atores
-- .csv → dados tabulares de produto
-- .png, .jpg, .pdf → wireframes, mockups
-
-REGRAS DA EXTRAÇÃO:
-- Categorias FIXAS (13 seções) — não inventar novas
-- §10 Fases de Entrega é OBRIGATÓRIO quando PRD existe
-- RNs com IDs ESTÁVEIS (RN-001...) — nunca renumerar
-- Ambiguidades são BLOQUEANTES
-- SEM texto narrativo — estruturado em tabelas e listas
-- Nunca INFERIR regra de negócio — se não explícito, é ambiguidade
-- Contradição entre fontes → ambiguidade citando os dois
-
-RE-EXTRAÇÃO:
-- Merge ADITIVO com PRD existente (não sobrescrever)
-- Seções afetadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
-- IDs de RN continuam sequência existente
-
-=============================================================================
--->
-
-## 1. Contexto e Motivação
-
-### Qual problema resolve?
-<!-- POR QUÊ essa feature existe — extraído dos insumos -->
-
-### Como funciona hoje?
-<!-- Estado ATUAL — o que existe, como é feito, quais os problemas -->
-
-### Estado desejado
-<!-- O que muda com essa feature — o delta é o escopo real -->
-
----
-
-## 2. Atores / Personas
-
-| Ator | O que pode fazer | O que NÃO pode fazer |
-|------|------------------|----------------------|
-|      |                  |                      |
-
-> Detalhes de autenticação, autorização, hierarquia de papéis: ver TRD §7.2 Autorização.
-
----
-
-## 3. Jornadas do Usuário
-
-> Sequências de ações do usuário pra atingir um objetivo. Alto nível — detalhes
-> de endpoint/estado ficam no TRD §2 e specs/scenarios.md.
-
-### Jornada 1: {{NOME}}
-
-| Passo | Ator | Ação | Resultado esperado |
-|-------|------|------|--------------------|
-| 1     |      |      |                    |
-
----
-
-## 4. Funcionalidades
-
-> Lista de alto nível. Detalhe de implementação (endpoints, componentes) vai pro TRD.
-
-| # | Funcionalidade | Descrição | Ator principal | Fonte |
-|---|---------------|-----------|----------------|-------|
-| 1 |               |           |                |       |
-
----
-
-## 5. Regras de Negócio
-
-> Invariantes do domínio. IDs estáveis. Cada regra deve ser testável.
-
-| ID | Regra | Fonte | Testável? |
-|----|-------|-------|-----------|
-| RN-001 | | {{arquivo_fonte}} | Sim/Não |
-
----
-
-## 6. Validações de Domínio
-
-> Regras sobre VALOR dos dados no domínio (ex: "CPF válido", "idade >= 18",
-> "data de agendamento futura"). NÃO são validações de schema/formato
-> (ex: "string 11 chars"), que ficam no TRD §2.3.
-
-| Campo | Regra de domínio | Ator que aciona | Fonte |
-|-------|------------------|-----------------|-------|
-|       |                  |                 |       |
-
----
-
-## 7. Telas / Fluxos UI (high-level)
-
-> Descrição do que o usuário vê e faz. Detalhes de componente, props, estado:
-> TRD §3 Área-Frontend + specs/scenarios.md.
-
-### Tela 1: {{NOME}}
-
-- **Propósito**: <!-- O que o usuário faz nesta tela -->
-- **Quem acessa**: <!-- papel(éis) -->
-- **Ações principais**:
-  -
-- **Campos principais**:
-  -
-- **Navegação**:
-  -
-
----
-
-## 8. Cenários de Sucesso e Erro
-
-### Sucesso
-
-| # | Cenário | Quando acontece | Feedback ao usuário |
-|---|---------|-----------------|---------------------|
-| 1 |         |                 |                     |
-
-### Erro
-
-| # | Cenário | Causa | Comportamento esperado (UX) | Fonte |
-|---|---------|-------|------------------------------|-------|
-| 1 |         |       | <!-- mensagem, recovery path --> |       |
-
-> Códigos HTTP e códigos de erro de domínio: TRD §2.1 e docs/conventions.md.
-
----
-
-## 9. Métricas de Sucesso
-
-> Como saber que essa feature está funcionando? KPIs de produto.
-
-| # | Métrica | Meta | Como medir |
-|---|---------|------|------------|
-| 1 |         |      |            |
-
----
-
-## 10. Fases de Entrega
-
-> Princípio: **entregáveis contínuos** — cada fase entrega valor e pode ir pra produção.
-> Fases são sequenciais por dependência. Cada uma tem entregável testável pelo PM.
->
-> **Cada fase do PRD pode ter tasks técnicas correspondentes no TRD** — o `/sf-plan`
-> cruza as duas visões pra gerar tasks por área × fase.
-
-### Fase 1 — {{Nome}} [P1]
-
-> **Entregável**: {{O que o usuário pode usar ao final}}
-> **Critério de done** (PM valida): {{Como validar — jornada E2E executável}}
-
-| # | Funcionalidade | Regras (RN-NNN) | Jornadas |
-|---|---------------|------------------|----------|
-| 1 | | | Jornada N |
-
-### Fase 2 — {{Nome}} [P1]
-
-> **Entregável**: {{...}}
-> **Critério de done**: {{...}}
-> **Depende de**: Fase 1
-
-| # | Funcionalidade | Regras | Jornadas |
-|---|---------------|--------|----------|
-| 1 | | | |
-
-<!-- Máximo 4-5 fases -->
-
-### Visão geral
-
-| Fase | Nome | Prioridade | Entregável | Depende de |
-|------|------|-----------|------------|------------|
-| 1 | | P1 | | — |
-| 2 | | P1 | | Fase 1 |
-
----
-
-## 11. Fora de Escopo
-
-> Explicitamente listado — o que NÃO será feito nesta feature.
-> Itens marcados com `/sf-start sugerido` viram features futuras.
-
-| # | Item | Motivo | `/sf-start` sugerido |
-|---|------|--------|------------------------|
-| 1 |      | futuro / outra feature / decisão do PM | `feat_X` (opcional) |
-
-> Nota: se o item vira feature futura, rodar `/sf-start feat_X` em execução separada.
-> Este PRD não carrega roadmap de features futuras — elas têm seu próprio ciclo.
-
----
-
-## 12. Ambiguidades e Perguntas
-
-> ⚠️ **BLOQUEANTE** — `/sf-design` NÃO avança enquanto houver linha com `Resposta`
-> vazia E `Resolvido em docs/` vazio.
->
-> **Como responder** (ver `.github/skills/sf-extract/SKILL.md` → "Como responder ambiguidades"):
-> preencher a coluna `Resposta` direto nesta tabela e rodar `/sf-design` de novo.
-
-| ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/ |
-|----|----------|----------|-------|----------|--------------------|
-| AMB-PRD-001 | ⚠️ | | | (aguardando) | — |
-
----
-
-## 13. Rastreabilidade
-
-> Mapa de qual insumo originou qual seção. Permite auditoria da extração.
-
-| Insumo | Tipo | Seções alimentadas |
-|--------|------|--------------------|
-| `{{arquivo}}` | {{tipo}} | §1, §2, §3 (Jornada 1), §5 (RN-001, RN-002) |
-
----
-
-> **Próximo passo**: Após aprovação do PM (campo `prd_aprovado: true` no
-> `.context.md`), o PRD alimenta `/sf-design` (specs/) + `/sf-merge-docs` (docs/).
-> Se também existe TRD, ele passa pelo mesmo fluxo (aprovação do dev) em paralelo.
+# PRD — {{NOME}}
+## Product Requirements Document
+
+> **Artefato gerado pela IA** a partir do processamento de insumos de produto em `workspace/Input/{{NOME}}/`.
+> Este é um dos dois docs source do pipeline SFW (peer do TRD).
+> O PRD é aprovado pelo **PM / product owner** — contém o "o quê" e "por quê" do produto.
+> Depois de aprovado, alimenta `/sf-merge-docs` (docs/ cross-feature) e `/sf-design` (specs/).
+
+---
+
+## Meta
+
+| Campo | Valor |
+|-------|-------|
+| Scope | `{{NOME}}` |
+| Status | `em extração` → `aguardando aprovação (PM)` → `aprovado` |
+| Insumos processados | {{LISTA_INSUMOS}} |
+| Gerado em | |
+| Aprovado em | |
+| Aprovado por | {{nome do PM}} |
+
+---
+
+<!--
+=============================================================================
+INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
+=============================================================================
+
+QUANDO USAR: Gerado pelo /sf-extract (chamado via /sf-start).
+QUEM GERA: Agent Produto-Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
+
+PAR COM TRD: o PRD é peer do TRD. Ambos podem coexistir (caso mais comum),
+ou o scope pode ter só um dos dois:
+- Scope puro-produto (raro): só PRD, sem TRD
+- Scope puro-técnico (bootstrap, mudança de stack): só TRD, sem PRD — NÃO GERAR ESTE ARQUIVO
+- Scope misto (maioria): ambos
+
+REGRA DE OURO: o Produto-Analyzer decide SE gera PRD baseado nos insumos.
+Se insumos não trazem conteúdo de produto (jornadas, RNs, UX, atores, telas),
+simplesmente NÃO gera. Não existe "PRD empty" — se é vazio, não existe.
+
+ZERO OVERLAP COM TRD:
+- Stack, schema, endpoints, validações de schema, deploy, ADRs → TRD
+- Jornadas, atores, RNs de negócio, UI, cenários de erro de produto → PRD
+- Integrações externas: PRD descreve POR QUÊ e O QUÊ; TRD descreve COMO
+- Validações: PRD descreve regras de DOMÍNIO (ex: "CPF válido", "idade >= 18");
+  TRD descreve validações de FORMATO (ex: "string, 11 chars, regex X")
+- NFRs: PRD descreve expectativa do usuário (ex: "resposta em < 1s");
+  TRD traduz em requisito técnico (ex: "P95 < 200ms no handler")
+
+COMO GERAR:
+1. Readers (Sonnet) leem cada arquivo do Input/ e catalogam por seção
+2. Produto-Analyzer (Opus) recebe outputs e:
+   a. Consolida conteúdo de produto em visão unificada
+   b. Cruza fontes — detecta contradições
+   c. Identifica gaps — seções sem info viram ambiguidades
+   d. Gera as 13 seções abaixo
+3. Consultar `docs/` ANTES de marcar ambiguidade — se `docs/domain.md` já
+   define ator ou jornada genérica, usar. Marcar "resolvido em docs/X §Y"
+4. Registrar DE QUAL insumo veio cada informação (rastreabilidade §13)
+5. Se faltam dados pra preencher seção relevante → pergunta BLOQUEANTE em §12
+
+FORMATOS DE INSUMO:
+- .txt, .md → requisitos, regras, contexto, restrições
+- .html → telas, fluxos, permissões (dados técnicos vão pro TRD)
+- .xml (drawio) → fluxos, decisões, atores
+- .csv → dados tabulares de produto
+- .png, .jpg, .pdf → wireframes, mockups
+
+REGRAS DA EXTRAÇÃO:
+- Categorias FIXAS (13 seções) — não inventar novas
+- §10 Fases de Entrega é OBRIGATÓRIO quando PRD existe
+- RNs com IDs ESTÁVEIS (RN-001...) — nunca renumerar
+- Ambiguidades são BLOQUEANTES
+- SEM texto narrativo — estruturado em tabelas e listas
+- Nunca INFERIR regra de negócio — se não explícito, é ambiguidade
+- Contradição entre fontes → ambiguidade citando os dois
+
+RE-EXTRAÇÃO:
+- Merge ADITIVO com PRD existente (não sobrescrever)
+- Seções afetadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
+- IDs de RN continuam sequência existente
+
+=============================================================================
+-->
+
+## 1. Contexto e Motivação
+
+### Qual problema resolve?
+<!-- POR QUÊ essa feature existe — extraído dos insumos -->
+
+### Como funciona hoje?
+<!-- Estado ATUAL — o que existe, como é feito, quais os problemas -->
+
+### Estado desejado
+<!-- O que muda com essa feature — o delta é o escopo real -->
+
+---
+
+## 2. Atores / Personas
+
+| Ator | O que pode fazer | O que NÃO pode fazer |
+|------|------------------|----------------------|
+|      |                  |                      |
+
+> Detalhes de autenticação, autorização, hierarquia de papéis: ver TRD §7.2 Autorização.
+
+---
+
+## 3. Jornadas do Usuário
+
+> Sequências de ações do usuário pra atingir um objetivo. Alto nível — detalhes
+> de endpoint/estado ficam no TRD §2 e specs/scenarios.md.
+
+### Jornada 1: {{NOME}}
+
+| Passo | Ator | Ação | Resultado esperado |
+|-------|------|------|--------------------|
+| 1     |      |      |                    |
+
+---
+
+## 4. Funcionalidades
+
+> Lista de alto nível. Detalhe de implementação (endpoints, componentes) vai pro TRD.
+
+| # | Funcionalidade | Descrição | Ator principal | Fonte |
+|---|---------------|-----------|----------------|-------|
+| 1 |               |           |                |       |
+
+---
+
+## 5. Regras de Negócio
+
+> Invariantes do domínio. IDs estáveis. Cada regra deve ser testável.
+
+| ID | Regra | Fonte | Testável? |
+|----|-------|-------|-----------|
+| RN-001 | | {{arquivo_fonte}} | Sim/Não |
+
+---
+
+## 6. Validações de Domínio
+
+> Regras sobre VALOR dos dados no domínio (ex: "CPF válido", "idade >= 18",
+> "data de agendamento futura"). NÃO são validações de schema/formato
+> (ex: "string 11 chars"), que ficam no TRD §2.3.
+
+| Campo | Regra de domínio | Ator que aciona | Fonte |
+|-------|------------------|-----------------|-------|
+|       |                  |                 |       |
+
+---
+
+## 7. Telas / Fluxos UI (high-level)
+
+> Descrição do que o usuário vê e faz. Detalhes de componente, props, estado:
+> TRD §3 Área-Frontend + specs/scenarios.md.
+
+### Tela 1: {{NOME}}
+
+- **Propósito**: <!-- O que o usuário faz nesta tela -->
+- **Quem acessa**: <!-- papel(éis) -->
+- **Ações principais**:
+  -
+- **Campos principais**:
+  -
+- **Navegação**:
+  -
+
+---
+
+## 8. Cenários de Sucesso e Erro
+
+### Sucesso
+
+| # | Cenário | Quando acontece | Feedback ao usuário |
+|---|---------|-----------------|---------------------|
+| 1 |         |                 |                     |
+
+### Erro
+
+| # | Cenário | Causa | Comportamento esperado (UX) | Fonte |
+|---|---------|-------|------------------------------|-------|
+| 1 |         |       | <!-- mensagem, recovery path --> |       |
+
+> Códigos HTTP e códigos de erro de domínio: TRD §2.1 e docs/conventions.md.
+
+---
+
+## 9. Métricas de Sucesso
+
+> Como saber que essa feature está funcionando? KPIs de produto.
+
+| # | Métrica | Meta | Como medir |
+|---|---------|------|------------|
+| 1 |         |      |            |
+
+---
+
+## 10. Fases de Entrega
+
+> Princípio: **entregáveis contínuos** — cada fase entrega valor e pode ir pra produção.
+> Fases são sequenciais por dependência. Cada uma tem entregável testável pelo PM.
+>
+> **Cada fase do PRD pode ter tasks técnicas correspondentes no TRD** — o `/sf-plan`
+> cruza as duas visões pra gerar tasks por área × fase.
+
+### Fase 1 — {{Nome}} [P1]
+
+> **Entregável**: {{O que o usuário pode usar ao final}}
+> **Critério de done** (PM valida): {{Como validar — jornada E2E executável}}
+
+| # | Funcionalidade | Regras (RN-NNN) | Jornadas |
+|---|---------------|------------------|----------|
+| 1 | | | Jornada N |
+
+### Fase 2 — {{Nome}} [P1]
+
+> **Entregável**: {{...}}
+> **Critério de done**: {{...}}
+> **Depende de**: Fase 1
+
+| # | Funcionalidade | Regras | Jornadas |
+|---|---------------|--------|----------|
+| 1 | | | |
+
+<!-- Máximo 4-5 fases -->
+
+### Visão geral
+
+| Fase | Nome | Prioridade | Entregável | Depende de |
+|------|------|-----------|------------|------------|
+| 1 | | P1 | | — |
+| 2 | | P1 | | Fase 1 |
+
+---
+
+## 11. Fora de Escopo
+
+> Explicitamente listado — o que NÃO será feito nesta feature.
+> Itens marcados com `/sf-start sugerido` viram features futuras.
+
+| # | Item | Motivo | `/sf-start` sugerido |
+|---|------|--------|------------------------|
+| 1 |      | futuro / outra feature / decisão do PM | `feat_X` (opcional) |
+
+> Nota: se o item vira feature futura, rodar `/sf-start feat_X` em execução separada.
+> Este PRD não carrega roadmap de features futuras — elas têm seu próprio ciclo.
+
+---
+
+## 12. Ambiguidades e Perguntas
+
+> ⚠️ **BLOQUEANTE** — `/sf-design` NÃO avança enquanto houver linha com `Resposta`
+> vazia E `Resolvido em docs/` vazio.
+>
+> **Como responder** (ver `.github/skills/sf-extract/SKILL.md` → "Como responder ambiguidades"):
+> preencher a coluna `Resposta` direto nesta tabela e rodar `/sf-design` de novo.
+
+| ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/ |
+|----|----------|----------|-------|----------|--------------------|
+| AMB-PRD-001 | ⚠️ | | | (aguardando) | — |
+
+---
+
+## 13. Rastreabilidade
+
+> Mapa de qual insumo originou qual seção. Permite auditoria da extração.
+
+| Insumo | Tipo | Seções alimentadas |
+|--------|------|--------------------|
+| `{{arquivo}}` | {{tipo}} | §1, §2, §3 (Jornada 1), §5 (RN-001, RN-002) |
+
+---
+
+> **Próximo passo**: Após aprovação do PM (campo `prd_aprovado: true` no
+> `.context.md`), o PRD alimenta `/sf-design` (specs/) + `/sf-merge-docs` (docs/).
+> Se também existe TRD, ele passa pelo mesmo fluxo (aprovação do dev) em paralelo.