spec-first-copilot 0.6.0-beta.9 → 0.7.0

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

@@ -1,286 +1,279 @@
-# PRD — {{NOME}}
-## Product Requirements Document
-
-> **Artefato gerado pela IA** a partir do processamento de todos os insumos em `workspace/Input/{{NOME}}/`.
-> Este é o checkpoint de extração — o usuário DEVE revisar e aprovar antes de prosseguir.
-> Todos os documentos subsequentes (SDD, tasks) são gerados a partir DESTE arquivo + chunks tech do `.extract-log.md`.
-
----
-
-## Meta
-
-| Campo | Valor |
-|-------|-------|
-| Scope | `{{NOME}}` |
-| Empty | `{{true\|false}}` — `true` quando insumos não têm conteúdo de produto (scope puro-técnico) |
-| Status | `em extração` → `aguardando revisão` → `aprovado` |
-| Insumos processados | {{LISTA_INSUMOS}} |
-| Gerado em | |
-| Aprovado em | |
-
-> **Se `empty: true`**: Meta é o único bloco preenchido. As 15 seções abaixo ficam
-> inalteradas (não apagar). Adicionar nota no rodapé: "PRD marcado como empty —
-> insumos não contêm conteúdo de produto (jornadas, RNs, UX). O SDD carregará
-> diretamente os chunks tech categorizados no `.extract-log.md`."
-
----
-
-<!--
-=============================================================================
-INSTRUÇÕES PARA O AGENTE (não incluir no arquivo gerado)
-=============================================================================
-
-QUANDO USAR: Gerado pelo /sf-extract (chamado via /sf-start).
-QUEM GERA: Agent Analyzer (Opus) a partir dos outputs dos Readers (Sonnet).
-
-CASO "PRD EMPTY":
-Se os insumos em `workspace/Input/{{NOME}}/` não contêm conteúdo de produto
-(nada de jornadas, atores, regras de negócio, UX — só stack/schema/infra),
-o Analyzer marca `empty: true` na Meta e NÃO preenche as 15 seções. É um
-outcome válido — scope puro-técnico (bootstrap de infra, mudança de stack).
-Chunks tech vão pro `.extract-log.md` pro /sf-design consumir.
-
-Critério: se após ler TODOS os insumos, o Analyzer consegue listar pelo menos
-1 regra de negócio OU 1 jornada OU 1 tela OU 1 ator → PRD NÃO é empty.
-Caso contrário → empty: true.
-
-COMO GERAR (quando empty: false):
-1. Readers (Sonnet) leem cada arquivo do Input/ individualmente e catalogam por seção
-2. Analyzer (Opus) recebe todos os outputs e:
-   a. Consolida em visão unificada
-   b. Cruza informações entre fontes — detecta contradições
-   c. Identifica gaps — seções sem informação viram ambiguidades
-   d. Gera este documento seguindo as 15 seções fixas
-3. **Consultar `docs/` (se existir) ANTES de marcar ambiguidade**: se a
-   resposta já está em `docs/` (ex: auth em `conventions.md §Autenticação`),
-   marcar "resolvido em docs/X §Y" em §14 em vez de perguntar ao user.
-   Ambiguidade real só surge se (a) docs/ ausente, (b) assunto novo,
-   (c) insumo contradiz docs/.
-4. Para cada informação, registrar DE QUAL insumo veio (rastreabilidade §15)
-5. Se faltam dados para preencher uma seção relevante → pergunta BLOQUEANTE em §14
-
-FORMATOS DE INSUMO (o que extrair de cada):
-- .txt, .md → requisitos, regras, contexto, restrições
-- .sql → entidades, campos, tipos, constraints, índices, relações
-- .html → telas, campos (data-field), ações (data-action),
-  validações (data-validation), rotas (data-route),
-  permissões (data-permission), estados (data-state)
-- .xml (drawio) → fluxos, decisões, atores, sequências
-- .csv → dados tabulares, mapeamentos
-- .png, .jpg, .pdf → wireframes, mockups (análise visual)
-- Outros → extrair o que for relevante — nunca ignorar
-
-REGRAS DA EXTRAÇÃO:
-- Categorias FIXAS (as 15 seções abaixo) — não inventar novas
-- §11 Fases de Entrega é OBRIGATÓRIO quando não-empty — organizar funcionalidades
-  em fases incrementais. Se existe `workspace/Output/{{NOME}}/backlog_extraido.md`,
-  usar como referência pra fases.
-  Princípio: entregáveis contínuos, cada fase entrega valor e pode ir pra produção
-- Regras de negócio com IDs únicos e ESTÁVEIS (RN-001, RN-002...)
-  → IDs nunca renumeram após criação. Em re-extração, novos continuam sequência
-- Ambiguidades como perguntas diretas — BLOQUEANTES
-- SEM texto narrativo — apenas informação estruturada em tabelas e listas
-- Rastreabilidade: de qual arquivo veio cada informação
-- Nunca INFERIR regra de negócio — se não está explícito, é ambiguidade
-- Contradição entre fontes → gerar ambiguidade citando os dois arquivos
-
-RE-EXTRAÇÃO:
-- Merge ADITIVO com PRD existente (não sobrescrever)
-- Seções afetadas marcadas com <!-- ATUALIZADO: re-extração ISO_DATE -->
-- IDs de regras continuam sequência existente
-- Se PRD era empty: true e re-extração encontra produto → flip para empty: false
-  e preencher seções normalmente
-
-=============================================================================
--->
-
-## 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 e Permissões
-
-| Ator | O que pode fazer | O que NÃO pode fazer |
-|------|------------------|----------------------|
-|      |                  |                      |
-
----
-
-## 3. Entidades e Modelo de Dados
-
-> Extraído de: arquivos `.sql`, protótipos, texto livre.
-
-| Entidade | Campos principais | Tipo dos campos | Relações |
-|----------|-------------------|-----------------|----------|
-|          |                   |                 |          |
-
-### Índices e constraints identificados
--
-
-### Histórico / Auditoria
--
-
----
-
-## 4. Jornadas do Usuário
-
-> Extraído de: protótipos HTML, textos, fluxos.
-
-### Jornada 1: {{NOME}}
-| Passo | Ator | Ação | Resultado esperado |
-|-------|------|------|--------------------|
-| 1     |      |      |                    |
-
----
-
-## 5. Regras de Negócio
-
-> Extraídas de TODOS os insumos. Cada regra deve ser clara, testável e ter ID único.
-
-| ID | Regra | Fonte | Testável? |
-|----|-------|-------|-----------|
-| RN-001 | | {{arquivo_fonte}} | Sim/Não |
-
----
-
-## 6. Validações
-
-> Extraídas de: protótipos (`data-validation`), `.sql` (constraints), texto.
-
-| Campo | Validações | Obrigatório? | Máscara | Fonte |
-|-------|-----------|--------------|---------|-------|
-|       |           |              |         |       |
-
----
-
-## 7. Telas e Componentes UI
-
-> Extraídos de: protótipos HTML (`data-field`, `data-action`, `data-route`, `data-state`).
-
-### Tela 1: {{NOME}}
-- **Rota**: 
-- **Campos**: (extraídos dos `data-field`)
-- **Ações**: (extraídas dos `data-action`)
-- **Navegação**: (extraída dos `data-route`)
-- **Estados**: (extraídos dos `data-state`)
-- **Permissões por elemento**: (extraídos dos `data-permission`)
-
----
-
-## 8. Integrações Externas
-
-| Serviço | Método | Quando é chamado | O que envia | O que recebe | Fallback |
-|---------|--------|------------------|-------------|--------------|----------|
-|         |        |                  |             |              |          |
-
----
-
-## 9. Cenários de Erro
-
-| # | Cenário | Causa | Comportamento esperado | Fonte |
-|---|---------|-------|----------------------|-------|
-| 1 |         |       |                      |       |
-
----
-
-## 10. Requisitos Não-Funcionais
-
-| Aspecto | Requisito | Fonte |
-|---------|-----------|-------|
-| Volume esperado | | |
-| Performance | | |
-| Disponibilidade | | |
-| Acessibilidade | | |
-
----
-
-## 11. 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.
-> Se o `/sf-extract` foi precedido por um roadmap (backlog_extraido.md), usar as fases como base.
-
-### Fase 1 — {{Nome}} [P1]
-
-> **Entregável**: {{O que o usuário pode usar ao final}}
-> **Critério de done**: {{Como validar — testes E2E que devem passar}}
-
-| # | Funcionalidade | Entidades | Regras | Jornadas |
-|---|---------------|-----------|--------|----------|
-| 1 | | | RN-NNN | Jornada N |
-
-### Fase 2 — {{Nome}} [P1]
-
-> **Entregável**: {{...}}
-> **Critério de done**: {{...}}
-> **Depende de**: Fase 1
-
-| # | Funcionalidade | Entidades | Regras | Jornadas |
-|---|---------------|-----------|--------|----------|
-| 1 | | | | |
-
-<!-- Repetir fases conforme necessário. Máximo 4-5 fases. -->
-
-### Visão geral
-
-| Fase | Nome | Prioridade | Entregável | Depende de |
-|------|------|-----------|------------|------------|
-| 1 | | P1 | | — |
-| 2 | | P1 | | Fase 1 |
-
----
-
-## 12. Dependências
-
-| Dependência | Tipo | Status | Impacto se indisponível |
-|-------------|------|--------|------------------------|
-|             | feature / serviço / tabela | pronto / pendente | |
-
----
-
-## 13. Fora de Escopo
-
-> Explicitamente listado — o que NÃO será feito nesta feature.
-
-| # | Item | Motivo |
-|---|------|--------|
-| 1 |      | futuro / outra feature / decisão do usuário |
-
----
-
-## 14. Ambiguidades e Perguntas
-
-> ⚠️ **BLOQUEANTE** — o `/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.
->
-> **Coluna `Resolvido em docs/`**: preenchida pelo Analyzer quando a resposta já
-> existe em `docs/` — formato `docs/{arquivo}.md §{seção}`. NÃO preencher manualmente.
-
-| ID | Pergunta | Contexto | Fonte | Resposta | Resolvido em docs/ |
-|----|----------|----------|-------|----------|--------------------|
-| AMB-001 | ⚠️ | | | (aguardando) | — |
-
----
-
-## 15. Rastreabilidade — De onde veio cada informação
-
-> Mapa de qual insumo originou qual seção. Permite auditoria da extração.
-
-| Insumo | Tipo | O que foi extraído |
-|--------|------|--------------------|
-| `{{arquivo}}` | {{tipo}} | {{seções alimentadas}} |
-
----
-
-> **Próximo passo**: Após aprovação do usuário, este PRD alimenta a geração do `sdd.md` e das tasks (`specs/{nome}/tasks.md`).
+# 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.