Atlas-KK/prd-lifecycle

Ciclo de Vida do PRD

Unifica as capacidades antes dispersas de criação, refinamento, revisão e planejamento de execução de PRDs em um único ponto de entrada, preservando ao mesmo tempo os diferentes limites de permissão e portões de confirmação de cada fase.

Roteamento de Modos

Primeiro, avalia os materiais que o usuário possui e o resultado esperado, entrando apenas no modo necessário, sem forçar o usuário a percorrer todo o fluxo do início ao fim.

Modo	Entrada Típica	Principal Resultado	Limite Chave
create (criar)	Conceito funcional + repositório existente	Relatório de estado atual, linha de base confirmada, PRD versionado	Primeiro, reunir evidências, confirmar passo a passo; não gerar PRD antes da aprovação da linha de base
refine (refinar)	Rascunho de PRD/requisitos	Revisão por etapas, histórico de versões, .docx opcional	Cada etapa primeiro revisa, só escreve e atualiza versão após confirmação
review (revisar)	PRD especificado + linha de base/repositório opcional	Problemas classificados, evidências, sugestões de revisão	Apenas revisar, não modificar documentos nem implementar código
execute (executar)	PRD aprovado + repositório existente	Auditoria de prontidão, documento de execução de desenvolvimento, matriz de rastreabilidade, prompt de controle	Apenas planejar, não modificar o PRD nem implementar código

Regras de roteamento:

• Apenas um conceito, com o objetivo de formar um PRD combinado com o projeto existente: use create.
• Já possui um rascunho, e o objetivo é complementar, revisar, refinar ou produzir uma versão final: use refine.
• O objetivo é encontrar contradições, riscos, omissões ou itens não verificáveis, sem exigir modificação: use review.
• Já possui uma versão claramente aprovada, e o objetivo é entregar ao Codex para desenvolvimento por fases: use execute.
• Quando o usuário solicitar processamento de ponta a ponta, comece na fase aplicável mais antiga; a cada portão mencionado abaixo, pare e aguarde autorização, não avance automaticamente entre fases.
• "Dá uma olhada" pode significar revisão ou modificação; priorize o review somente leitura e explique que os resultados da revisão podem entrar em refine após autorização separada do usuário.
• O usuário deseja apenas avaliar e implementar alterações localizadas no código, UI, interação, refatoração ou arquitetura do repositório existente: use repo-grounded-change; não force a escrita de um PRD primeiro.

Restrições Compartilhadas

Ordem de Autoridade

A menos que o usuário especifique o contrário, processe conflitos na seguinte ordem:

1. Instrução explícita atual do usuário.
2. Decisões claramente confirmadas na tarefa atual.
3. Linha de base de requisitos e PRD aprovados especificados.
4. Comportamento existente comprovado pelo código e testes atuais.
5. Documentação atual do produto.
6. Rascunhos anteriores, registros de revisão e sugestões.

O PRD alvo não é inerentemente correto; quando surgirem conflitos, apresente o conflito, o impacto e a decisão necessária, sem escolher um lado silenciosamente. O código serve para comprovar o estado atual, não pode negar novos requisitos já aprovados.

Rótulos de Fato e Sugestão

Use quando a conclusão puder ser confundida: confirmado, fato do código, fato da documentação, suposição de produto, sugestão técnica, a confirmar, não implementado nesta iteração.

Limites de Autorização

• Não inventar regras de negócio, estados, limites, permissões, prioridades, dependências, integrações externas ou critérios de aceitação.
• Não tratar conclusão de fase, aprovação de revisão ou geração de plano como autorização para implementação.
• Não modificar código de negócio, não commitar, dar push, fazer deploy, nem chamar sistemas de produção externos.
• Verificar a árvore de trabalho e proteger as alterações existentes do usuário; quando não for possível evitar com segurança, parar e explicar a área de sobreposição.
• Executar apenas o modo atual solicitado pelo usuário. Para entrar no próximo modo, é necessária uma solicitação ou confirmação explícita.

create: Criar PRD Após Análise Forense do Repositório

1. Ler project-discovery.md, verificar repositório, documentação do produto, testes e árvore de trabalho, e emitir um relatório do estado atual. A menos que o usuário solicite explicitamente a fusão de fluxos, parar e aguardar confirmação do estado atual.
2. Ler clarification-rounds.md, planejar tópicos com base em lacunas de evidência. Discutir apenas um tópico por rodada, apresentar 1–3 perguntas de múltipla escolha mutuamente exclusivas; recomendar uma opção primeiro e explicar o impacto.
3. Após a resposta do usuário, primeiro resumir os itens confirmados, não confirmados, conflitos e impactos a jusante desta rodada, depois aguardar a confirmação do resumo da rodada. Não confirmado, não entrar no próximo tópico.
4. Após todos os tópicos relevantes serem confirmados, ler baseline-and-prd.md, gerar a linha de base de confirmação de requisitos e parar.
5. Somente após o usuário aprovar explicitamente a linha de base e solicitar a geração do PRD, criar o PRD versionado; pesquisar versões existentes e incrementar, não sobrescrever silenciosamente.

Critério de conclusão: PRD consistente com as decisões confirmadas, escopo e não-escopo claros, requisitos e critérios de aceitação rastreáveis, impacto no repositório com evidências, itens pendentes não disfarçados como requisitos finais.

refine: Refinamento Passo a Passo e Revisão Versionada

1. Ler o texto original completo, preservar o significado original e estabelecer uma linha de base de trabalho. Se for necessário criar um novo documento de trabalho em Markdown, usar scripts/prd_doc.py init para estabelecer v1.0 e o esqueleto de seções.
2. Ler a subseção da etapa atual em refinement-steps.md. O esqueleto padrão é:
   • Esclarecimento de requisitos e histórias de usuário;
   • Solução funcional;
   • Condições de contorno;
   • Critérios de aceitação.
3. Fazer apenas a etapa atual de cada vez. Primeiro, apresentar o conteúdo a ser revisado no diálogo, sem escrever no arquivo antecipadamente.
4. Quando o usuário solicitar modificação ou complemento, permanecer na etapa atual, sem atualizar a versão. Somente após confirmação explícita do usuário, escrever no documento e executar um incremento de versão minor conforme versioning.md e registro de revisão.
5. Quando forem necessárias métricas, cronograma de dependências, rollback de riscos, conformidade ou realimentação de opiniões de revisão, etapas de extensão podem ser inseridas; também executar o portão "produzir → revisar → confirmar → escrever → atualizar versão".
6. Após todas as etapas serem confirmadas, fazer o merge do rascunho completo e executar um incremento de versão major. Quando o usuário solicitar .docx, usar scripts/prd_doc.py export e concluir a validação de formatação com as ferramentas de documento disponíveis.

O conteúdo de cada etapa deve tanto complementar quanto apontar itens vagos, contraditórios, não verificáveis e cenários propensos a omissão no texto original. Deve haver rastreabilidade entre histórias de usuário, funcionalidade, limites e critérios de aceitação; os itens de aceitação devem conter condições claras e resultados observáveis.

Concluir o refinamento não significa que o PRD foi aprovado pelo negócio, nem que automaticamente entra em review ou execute.

review: Revisão Adversarial com Evidências

1. Ler review-protocol.md, confirmar a versão alvo, escopo da revisão, fontes de autoridade, evidências do repositório e materiais ausentes. Ler o PRD alvo na íntegra.
2. Extrair escopo, tipo, estado, limites, permissões, dados, tempo, prioridades e invariantes de aceitação.
3. Ler finding-taxonomy.md, verificar respectivamente regressão de linha de base, consistência interna, ciclo de vida, histórico de dados, idempotência de interface, auditoria de permissões, limites de protótipo, NFR, executabilidade e rastreabilidade de FR/AC.
4. Após deduplicação, reter apenas problemas com evidência, consequências e que podem ser corrigidos. Não fabricar descobertas para parecer abrangente.
5. Ler review-report.md, emitir Aprovado, Aprovado com alterações, Bloqueado ou Revisão limitada, e produzir descobertas, evidências, impacto e sugestões mínimas de correção por gravidade.

A revisão é somente leitura por padrão. Mesmo que problemas óbvios sejam encontrados, não modificar diretamente o PRD; após autorização do usuário para revisão, entrar em refine.

execute: Transformar em Documento de Execução de Desenvolvimento para Codex

Pré-requisito: existe um PRD aprovado com versão identificável. Concluir o refinamento ou passar na revisão não equivale, por si só, a aprovação.

1. Ler readiness-audit.md, verificar a versão do PRD, linha de base confirmada, escopo de lançamento alvo, itens pendentes, repositório atual e testes, formando uma tabela de lacunas e uma conclusão de prontidão.
2. Se o comportamento do produto não puder ser determinado de forma única, houver conflitos de autoridade, critérios de aceitação não observáveis ou dependências/integrações/migrações não autorizadas, a conclusão será BLOQUEADO e pare, sem esconder o problema em suposições técnicas.
3. Ler execution-document.md, definir os limites arquiteturais mínimos, propriedade, estado, dados, interfaces, persistência, clock, degradação e proteção de sistemas existentes que satisfaçam o PRD.
4. Começando pela Fase 0 somente leitura, criar fases ordenadas por dependência, independentes e revisáveis. Cada fase deve especificar FR/AC, escopo de arquivos, proibições, testes, evidências de aceitação, portões de qualidade e portões de parada.
5. Ler traceability-and-gates.md, mapear cada FR/AC dentro do escopo para fases, áreas de código, testes e evidências, identificar requisitos órfãos e trabalho não autorizado.
6. Ler codex-control-prompt.md, gerar o prompt de controle mestre e prompts de fase individual. Os prompts devem reter versão, ordem de autoridade, testes reais, proteção de alterações do usuário e autorização fase a fase.

Critério de conclusão: Outra instância do Codex pode começar a partir da auditoria somente leitura, executar apenas uma fase aprovada, verificar com comandos reais, relatar resultados de rastreamento e parar; o documento define claramente suposições, exclusões, bloqueios, itens adiados e comportamentos protegidos.

Portões de Transição entre Fases

• create → refine: Entrar somente quando o usuário considerar que o PRD gerado ainda precisa de complemento ou revisão.
• create/refine → review: Deve ser explicitamente solicitado pelo usuário; a revisão não corrige automaticamente.
• review → refine: Entrar após autorização explícita do usuário para tratar das descobertas especificadas, mantendo o ID da descoberta e o mapeamento da revisão item a item.
• create/refine/review → execute: A versão do PRD "aprovada" e o escopo de lançamento alvo devem ser explicitamente especificados.
• execute → implementação: O documento de execução fornece apenas o plano de controle; a implementação real deve ser autorizada separadamente pelo usuário em uma tarefa subsequente.

Aprendizado por Feedback

Ao iniciar o fluxo de trabalho, ler feedback-learning.md e learned-guidance.md. O feedback é aplicado primeiro à tarefa atual; a persistência só é permitida se o usuário solicitar explicitamente que a regra específica e seu escopo sejam lembrados e confirmados. Regras aprendidas não podem sobrepor as instruções atuais, portões de fase, verificação de fatos, gerenciamento de versão ou limites de autorização.