Po Feature Spec

Product Owner - Especificação de Features

O PO é o guardião do valor de negócio. Toda feature nova começa aqui.

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/handoffs.md, policies/token-efficiency.md, policies/evals.md, policies/prd-validation.md (13 checks fixos), policies/constitution.md (autoridade hierarquica) e policies/readiness-gate.md (critério de aceitação não-testável ou ambiguity score não resolvido reprova o gate antes do slice virar código — a skill 09 roda esse gate depois desta skill produzir a spec).

Constituicao (se existir)

Quando memory/constitution.md existe no repo consumidor:

• toda spec deve respeitar os 5 eixos (Code Quality, Testing, UX, Performance, Security)
• conflito spec ↔ constituicao: ajustar a spec (constituicao vence). Se principio precisa mudar, registrar em commit chore(constitution) separado.
• recomendar /checklist apos spec inicial e /analyze antes de /build

Para exemplos longos e checklists completos, consultar docs/skill-guides/po-feature-spec.md apenas quando necessario.

Quando Usar

• definir feature nova, escopo e prioridade
• transformar necessidade de negocio em criterios testaveis

Quando Nao Usar

• para decidir implementacao tecnica detalhada
• para substituir UI/UX, Backend, QA ou Reviewer

Entradas Esperadas

• objetivo de negocio
• restricoes e dependencias conhecidas
• contexto do usuario ou da operacao

Saidas Esperadas

• spec curta e acionavel
• criterios de aceitacao testaveis
• handoff claro para UI/UX e pipeline seguinte

Responsabilidades

1. Traduzir necessidade de negócio em especificação técnica consumível pelo time
2. Definir prioridade e impacto
3. Escrever critérios de aceitação claros e testáveis
4. Validar que a entrega final atende o esperado

Estrutura Minima da Feature Spec

Toda nova feature deve cobrir, no minimo:

• resumo do problema e da solucao proposta
• user stories com criterios de aceitacao testaveis
• regras de negocio e dependencias
• escopo IN e OUT
• prioridade e metricas de sucesso
• decisoes estruturais (ver Decisoes Estruturais Antes da Primeira Tela abaixo)
• vertical slices (se feature multi-camada — ver abaixo)

Para spec completa e exemplos extensos, consultar docs/skill-guides/po-feature-spec.md.

Decisões Estruturais Antes da Primeira Tela

O retrabalho mais caro num MVP não vem de código malfeito — vem de decisão de produto que ficou implícita e só aparece quando um cliente de verdade usa o sistema. As quatro categorias abaixo mudam telas inteiras se decididas tarde; decida cada uma antes de passar a spec para UI/UX, mesmo que a resposta seja "não se aplica nesta feature" (declarar isso é diferente de não ter pensado nisso).

1. Modelo de dados e posse do registro. Para cada entidade nova ou alterada: quem é o dono (usuário, organização, sistema?), quais campos são obrigatórios de verdade (não "provavelmente vou precisar"), e o que pode ser apagado — soft delete, hard delete, ou nunca. Mudar posse ou obrigatoriedade depois que existem registros reais de cliente exige migration de dado, não só de schema — é o retrabalho mais caro da lista.
2. Permissão por ator. Uma matriz curta — quem vê, quem edita, quem aprova cada entidade/ação da feature. "Depois eu coloco o login" quase sempre vira reescrita, porque permissão atravessa todas as telas que já foram construídas sem ela. Se a feature não tem múltiplos atores ainda, declare isso explicitamente («ator único nesta v1») em vez de omitir a seção.
3. Estados e transições. Se a feature tem fluxo — orçamento → aprovação → execução → cobrança, ou equivalente — liste os estados possíveis e o que é permitido em cada um (quem pode transicionar, o que fica travado) antes de pedir a primeira tela. Uma tela desenhada sem os estados declarados normalmente esconde um estado que ninguém previu (ex: "orçamento aprovado mas cliente cancelou antes da execução").
4. Ciclo de vida do cliente. Como ele entra (cadastro, convite de equipe), e como ele sai (cancelamento, exportação dos próprios dados). Se a feature manipula dado de cliente e o produto não tem ainda fluxo de exportação/cancelamento, isso vira OUT explícito da spec — não uma omissão.

O que acontece quando algo dá errado (pagamento recusado, import com coluna faltando, e-mail que não sai) já é coberto pelo critério de aceitação em si — rules/common/acceptance-criteria.md exige o caminho de erro como um dos casos obrigatórios de todo critério; a spec só precisa garantir que cada regra de negócio nova tem seu caminho de erro nomeado, não apenas o happy path.

Checkpoint antes do handoff: relia as 4 categorias uma a uma perguntando "se eu pular esta e um cliente de verdade usar amanhã, o que quebra?" — se a resposta for concreta (não "talvez dê problema"), a categoria precisa de uma frase na spec antes de seguir. Não é preciso desenhar solução aqui, só declarar a decisão — UI/UX e Backend implementam a partir do que foi decidido.

Vertical Slices em Specs Multi-Camada

Se a feature envolve >1 camada (front + back + DB ou similar), a spec deve organizar user stories como vertical slices demo-able. Cada slice e uma feature ponta-a-ponta testavel sozinha — nao subdividir por camada (ex: "spec do front", "spec do back" — errado).

Exemplo bom (vertical):

• Slice 1 — Login com email/senha (DB user table + endpoint /login + tela + e2e)
• Slice 2 — Cadastro (mesma table + endpoint /register + tela + e2e)
• Slice 3 — Esqueci senha (depende de Slice 1, adiciona endpoint + email service + tela + e2e)

Exemplo ruim (layered):

• Story 1 — UI de auth (login + cadastro + esqueci senha juntos)
• Story 2 — Backend de auth (login + cadastro + esqueci senha juntos)
• Story 3 — DB schema de auth

Cada slice deve:

• ter criterio de aceitacao testavel ponta-a-ponta (DADO/QUANDO/ENTAO atravessa camadas)
• caber em 1-3 dias de trabalho
• ser demo-able (usuario clica e ve resultado)
• declarar dependencia de outros slices se houver

Detalhes em policies/vertical-slices.md.

Critérios de Aceitação - Boas Práticas

Critérios de aceitação devem ser:

• Específicos: sem ambiguidade
• Mensuráveis: pode ser verificado como verdadeiro/falso
• Independentes: não depender de outro critério pra fazer sentido
• Testáveis: QA consegue escrever um teste automatizado a partir deles

Exemplo ruim: "O sistema deve ser rápido" Exemplo bom: "DADO que o usuário está na listagem QUANDO clicar em filtrar ENTÃO os resultados carregam em menos de 500ms"

Checkpoint antes de fechar a spec: para cada critério escrito, teste as 4 propriedades (Específico/Mensurável/Independente/Testável) uma por uma. Se algum falhar — "rápido" sem número, critério que só faz sentido lendo outro antes — reescreva aquele critério e teste de novo. Não avance pro handoff com um critério que falhou o teste "QA consegue escrever teste automatizado a partir dele sem perguntar nada de volta".

Priorização - Matriz de Valor

Use a fórmula: Score = (Impacto × Urgência) / Esforço

Score > 3 = Prioridade máxima Score 1.5-3 = Próximo sprint Score < 1.5 = Backlog

Evidencia de Conclusao

• problema, escopo e prioridade definidos
• criterios de aceitacao testaveis
• dependencias e riscos explicitos
• as 4 decisões estruturais declaradas (posse de dado, permissão por ator, estados/transições, ciclo de vida do cliente) — mesmo que a resposta seja "não se aplica"

Handoff para UI/UX

Ao finalizar a spec, entregar para UI/UX:

1. Feature spec completa com todas as user stories
2. Fluxos de usuário em texto (happy path + edge cases)
3. Referências visuais se houver
4. Restrições técnicas que impactam UI (ex: "não temos API de upload ainda")
5. Personas e contexto de uso
6. As decisões estruturais da seção acima — UI/UX não desenha tela de permissão, estado ou ciclo de vida sem saber o que foi decidido

Fase Divergente (Opcional)

Para features ambíguas ou inovadoras, use frameworks de ideação antes de especificar. Consultar: docs/skill-guides/ideation-frameworks.md

Quando usar:

• Requisito vago ("melhore a experiência de busca")
• Feature sem referência clara no mercado
• Stakeholder indeciso entre abordagens
• Solução atual não está funcionando

Quando pular:

• User story já está clara e específica
• É task de implementação com scope definido
• Time já convergiu em abordagem validada

Ordem recomendada: JTBD → HMW → SCAMPER → First Principles

Fundamento de Negócio (Discovery & Validação)

Antes de especificar, o PO valida que a feature/produto resolve um problema real que alguém paga (ou retém/indica) para resolver. Spec sem fundamento de negócio é desperdício caro. Base: Guia da Startup (Casa do Código), capítulos 11–32.

Quando aplicar: produto/feature novo, hipótese não validada, ou quando a métrica de sucesso da spec ainda é chute. Para feature incremental sobre fluxo já validado, pular direto para a spec.

1. Validar hipótese ANTES de especificar

Não escreva spec de algo que ninguém quer. Teste a demanda primeiro com o mínimo de esforço:

• 1 landing page simples com 3 blocos: o problema, a solução, o preço (pode ser preço hipotético).
• Formulário capturando e-mail de interessados (a conversão é o sinal).
• Tráfego pago segmentado por ~1 mês (ex: Google Ads, orçamento baixo controlado).
• Critério mínimo de prosseguir (parâmetros do livro): produto de consumidor final ≈ 20% de conversão; produto B2B/empresas ≈ 10%, com pelo menos ~150 e-mails válidos após um mês de campanha. Abaixo disso, repensar antes de construir.
• → Texto da landing e do anúncio: handoff para skill 13-marketing-copy / 50-direct-response-copy (não escrever copy aqui).
• → Instrumentação da conversão e do funil: handoff para skill 21-data-analytics.

Registrar o resultado do teste como input da spec: "hipótese X validada a Y% de conversão / N e-mails".

2. Problema vs. necessidade latente (descobrir o problema real)

• Separe problema de solução. Quando o usuário diz "queria um botão que faz X", X é uma sugestão de solução, não o problema. Pergunte "por quê" até chegar no problema de fato (no livro: o Sr. Smith pede "mais um cavalo", mas o problema é "passo pouco tempo com a família").
• Necessidade latente: às vezes o problema não está declarado — o usuário não sabe que tem o problema, ou não percebe a solução possível. Validar que ele reconhece o problema antes de assumir que vai querer a solução.
• Problema vs. necessidade: problema = obstáculo que pede resolução; necessidade = algo subjetivo/fundamental (autoestima, conexão, expressão — Pirâmide de Maslow). Ambos geram produto válido. A spec deve declarar qual dos dois está atacando.
• Proximidade: resolver problema próprio/conhecido reduz ambiguidade da spec. Cuidado: você vira usuário avançado rápido e esquece o novato.
• Regra-âncora (Steve Blank, citado no livro): "Startups não falham por não conseguir construir o produto. Falham por não encontrar clientes dispostos a pagar." Tecnologia bacana sem problema = não é produto.

3. MVP de verdade (mínimo viável, não mínimo bonito)

• A função do PO que não se terceiriza: definir as funcionalidades mínimas que resolvem o problema. É o coração da spec.
• Corte agressivo: cada funcionalidade extra atrasa receita/aprendizado e diminui a satisfação do usuário acima de certo ponto (excesso de funcionalidade vira problema novo). Lançar 3 meses antes pode antecipar 6 meses o retorno.
• Teste do "essencial": funcionalidade que parece indispensável muitas vezes não move a métrica. Validar por uso real (ex: ligar/desligar a feature e observar churn/conversão), não por opinião.
• Cuidado com o MVP virar "Proposta de Valor Medíocre": lançar mínimo só funciona se você tiver agilidade para iterar com base no feedback. MVP é o início do experimento, não o fim.
• Na spec: o escopo IN é o MVP; tudo que "seria bom ter" vai para OUT com justificativa de adiamento.

4. Modelo de monetização e pricing (input da spec, não detalhe técnico)

A spec deve declarar como a feature/produto gera ou protege receita. Tipos (do livro):

• Receita paga pelo usuário — assinatura recorrente (mensal/anual) ou pagamento por uso (medível: msgs enviadas, ligações, vendas). B2B aceita cobrança direta; consumidor final resiste mais.
• Receita paga por terceiro interessado no usuário — anúncios/dados. Exige base enorme e recorrente (centenas de milhares) para valer.
• Receita indireta — venda/aluguel de itens (e-commerce) ou redução de custo (internet banking, intranet — não há receita, há economia).
• Freemium: versão grátis só é sustentável se o custo de servir cada usuário grátis for ≈ zero. Conversão típica grátis→pago ≤ 2% (precisa de ~100k usuários para ~2k pagantes). Distinguir versão grátis (para sempre) de trial (tem fim).
• Pricing: considerar valor percebido + concorrentes + custo (a receita tem que cobrir operação + desenvolvimento + sobra). Preço pode variar por cliente. Testar preço é experimento válido (no livro, dobrar o preço quase não mudou a taxa de novas assinaturas — após período de maturação).

5. Métricas pirata (AARRR) como input da spec

Toda feature deve declarar qual estágio do funil ela move. O livro descreve o funil de conversão (visitante → usuário → cliente → churn) que mapeia direto nas métricas pirata AARRR:

• Foco qualificado, não volume: trazer 100k visitantes dos quais só 1k têm o problema é pior que trazer 1k qualificados. A spec deve mirar o público que tem o problema.
• Critério de aceitação ligado à métrica: a métrica de sucesso da spec deve nomear o estágio AARRR e um alvo mensurável.
• → Definição de eventos, naming e tracking plan: handoff para skill 21-data-analytics (não inventar nomes de evento aqui).

6. Product-market fit como critério de priorização

• O livro descreve as 4 fases (Startup Genome): Discovery (o produto resolve um problema?) → Validation (alguém paga/dá atenção?) → Efficiency (refinar aquisição) → Scale. Não escale o que não tem fit.
• Ajuste da priorização: antes de aplicar Score = (Impacto × Urgência) / Esforço, classifique a fase. Em Discovery/Validation, priorize features que aprendem (validam hipótese, ativam, retêm) sobre features que escalam (otimização, polish). Uma feature de polish com score alto mas sem fit validado é armadilha.
• Números de longo prazo como guarda-corpo: uma feature de monetização só faz sentido se a unidade econômica fecha — LTV > CAC (CAC = custo de adquirir cliente; LT = tempo de vida; LTV = receita no tempo de vida). Se a feature aumenta CAC sem mover LTV/retenção, repriorizar. Esses números estabilizam por volta de ~2 anos de operação — não decidir cedo demais com dados rasos.

Para canvas de hipótese, roteiro de teste de demanda e tabela AARRR detalhada, ver docs/skill-guides/po-feature-spec.md.

Ambiguity Scoring

Antes de iniciar a spec, calcular o ambiguity score para decidir se o briefing e suficiente.

Formula:

ambiguity = 1 - (goal * 0.40 + constraints * 0.30 + criteria * 0.30)

Variante Brownfield (codebase conhecida):

ambiguity = 1 - (goal * 0.30 + constraints * 0.25 + criteria * 0.25 + context_clarity * 0.20)

Thresholds:

• score < 0.4 → prosseguir direto
• score 0.4-0.7 → enrich mode (inferir do repo-audit e confirmar)
• score > 0.7 → iniciar Deep Interview

Usar devkit_ambiguity_score (MCP) para calcular programaticamente.

Deep Interview Protocol

Acionar quando score > 0.7. Seguir templates/deep-interview.md.

Principios:

• Uma pergunta por rodada, preferencialmente multipla escolha, com um palpite (guess) anexado à pergunta
• Sistema infere e confirma — nunca devolve "escreva mais"
• Max 5 rodadas, parar quando stability ratio > 0.8 por 2 rodadas
• Fail-forward: apos 5 rodadas sem estabilidade, prosseguir com melhor entendimento
• Desconfiar de resposta que soa "boa prática" em vez de necessidade real ("escalável", "do jeito que todo app faz") — sondar com "se não precisasse justificar pra ninguém, o que você realmente quer?"
• Restate final SEMPRE inclui linha "Fora de escopo" — e "beleza"/"manda ver"/"confio em você" não contam como confirmação (ver templates/deep-interview.md)

Enrich Mode (score 0.4-0.7): Usar repo-audit, session summary, git log e stack para inferir o que falta. Apresentar:

"Entendi que voce quer [X]. Baseado no projeto:
 - Escopo: [inferido do repo-audit]
 - Arquivos provaveis: [do repo-audit]
 - Constraints: [da stack conhecida]
 → Bora assim?
 → Quer ajustar ou detalhar algo?
 → Ou era outra coisa?"

Fontes

• Disciplina de palpite-anexado, sonda "want vs. should-want" e restate com "fora de escopo" (em templates/deep-interview.md) adaptados de addyosmani/agent-skills, skill interview-me (MIT).

Integração com Pipeline

• Orquestrador (skill 09): Coordena quando esta skill é invocada e define a próxima etapa
• Context Manager (skill 08): Rastreia progresso das tasks dentro desta skill
• Documentador (skill 10): Documenta entregas desta skill durante o desenvolvimento
• skill 48 (research-prep): roda antes desta skill quando a feature envolve tecnologia externa não dominada pelo time. Passar memory/research/<slug>.md como contexto de "o que existe" antes de escrever a spec.