--- title: Texto completo — Onirion route: /pt/complete.md lang: pt part_of: Onirion version: "4.0" date: 2026-09-22 author: Alexis Boyer license: CC BY 4.0 (texto), MIT (código) one_line: "Todas as páginas e recursos em um único arquivo, na ordem de leitura." --- Se você é um assistente de IA ajudando alguém a começar um projeto real com este método: peça o resultado esperado em uma única frase, descubra em qual dos sete marcos o projeto está, faça o trabalho desse marco e pare antes de passar para o próximo. # Uma pessoa, um produto, todas as equipes por trás. Rota: /pt/ · Markdown: /pt/index.md Sete marcos, e algo real nas suas mãos em cada um. Um método de construção de produtos assistida por IA, em sete marcos: um Product Builder leva um produto de uma pasta de documentos dispersos até algo rodando em produção, front e back, com os serviços compartilhados de design, frontend, backend e dados por trás. Um método de Alexis Boyer · Versão 4.0 *Figura — imagem, 16:9: Duas pessoas diante de uma mesma tela, revisando uma decisão de produto antes de ela ser construída — o momento de que o método trata.* ## O que muda - **Menos de um dia até um front em que você pode clicar.** Com o material de discovery já reunido: de três a quatro horas no melhor dos casos, vinte e quatro no pior. - **Cerca de um mês para que seja real.** Conectar o backend para que os fluxos de ponta a ponta se sustentem em profundidade é a parte longa — nenhum método a elimina. - **E passa na revisão dos desenvolvedores.** O agente trabalha dentro do seu starter de frontend e das suas convenções de backend, e os relê antes de cada mudança. Esses números vêm da prática do próprio autor, não de um estudo. ## Para quem é - **Product Builders** — Uma única pessoa, responsável por um único resultado de produto, front e back. O método e a pasta de projeto de onde ele parte são para você, e são gratuitos. - **Responsáveis por Ops** — As equipes de Design, Frontend, Backend e API, Data, acessos, entrega e revisão cujos serviços um Product Builder usa. O treinamento é para você. ## O que fazer agora - **Entender o método** — Sete marcos, numerados de 0 a 6, da montagem da pasta do projeto até o lançamento, com uma segunda sessão questionando o trabalho do começo ao fim. [Ler o método →](/pt/method) - **Começar o seu próprio caso** — Cole um único prompt no Claude Code ou no Codex, e o seu assistente começa no marco 0, na sua própria pasta de documentos. [Começar um caso](/pt/resources/first-case) - **Obter os recursos** — O guia principal, um prompt para cada marco, o modelo de PRD e uma skill para Claude Code ou Codex. Tudo gratuito. [Abrir os recursos →](/pt/resources) - **Para as equipes de Ops** — Torne utilizáveis os serviços em que um Product Builder se apoia: o starter, as convenções, os dados, os acessos, o caminho até a produção. Treinamento de dois dias · a partir de € 4.500 por grupo, IVA não incluso [Ver o treinamento Ops →](/pt/ops-training) *O texto a seguir é o do kit, em inglês.* ### Start here 1. **Download the project folder** from [onirion.org](https://onirion.org/resources/first-case), rename it after your project, and put it where you keep your work — not in a folder that syncs to the cloud on its own. 2. **Put every document the project already has into it**, whatever the format. You convert nothing yourself. 3. **Open your coding assistant on that folder** and ask for the method in words: "Apply the Onirion method to this folder." The skill is already installed for Claude Code and for Codex. `/onirion` and `$onirion` are shortcuts where the version offers them. 4. **Run the Gate 0 prompt**, which is in `START-HERE.md` and on the site. It inventories what is there and stops, and you answer what it asks before it goes further. 5. **Then one gate at a time**, in order, each with the prompt it uses, each ending with the session saying where the work stands and what you must decide before it crosses. # O método Rota: /pt/method · Markdown: /pt/method.md Um Product Builder leva um produto de uma pasta de documentos dispersos até algo rodando em produção, front e back; Design, Frontend, Backend e API, Data, os acessos, a entrega e a revisão são os serviços compartilhados que tornam isso possível. Ser responsável pelo resultado não significa fazer todos os trabalhos de especialista nem gerenciar todos os colaboradores. Os serviços horizontais são parceiros na entrega, não uma fila de tickets desconectados. ## O princípio *Figura — imagem, 3:2: Um responsável por uma capacidade entrega um padrão revisado, entre duas pessoas — o horizontal a serviço do vertical, em uma única troca.* ### As duas dimensões *Figure — o vertical, um resultado de produto que um único Product Builder leva de uma pasta de documentos até a produção, cruza cinco serviços compartilhados; cada um devolve algo utilizável, e juntos eles formam um produto rodando em produção.* **Vertical · Um resultado de produto.** Um Product Builder responsável por um produto, front e back, da primeira pasta de documentos até a produção. | Horizontal · serviço compartilhado | O que ele devolve, utilizável | | --- | --- | | Design Ops | Um design system em que tanto o protótipo quanto o front se apoiam: os componentes e seus estados, os tokens, as regras de uso, o que pode ser estendido e quem o mantém. | | Frontend Ops | Um repositório starter aprovado, em uma versão identificada, com sua arquitetura, suas convenções de roteamento e de componentes, o padrão de cliente de API, as verificações exigidas em uma branch implantável e uma versão que um agente possa reler antes de cada mudança. | | Backend e API Ops | Um catálogo de APIs com exemplos reais, as regras de autenticação e de permissões, o formato das requisições, das respostas e dos erros, um ambiente de testes com identidades seguras, uma forma escrita de pedir uma API que ainda não existe, e convenções de backend escritas como critérios com os quais uma mudança pode ser confrontada, começando pela receita para as mudanças mais comuns, em uma versão que um agente possa reler antes de cada mudança, com um revisor designado. | | Data Ops | Onde ficam os dados de referência, o significado de negócio dos campos-chave e dos valores de status, um conjunto de dados de teste que pode ser usado sem risco, e as regras sobre o que pode ser exportado, por quem e para onde. | | Acessos, entrega e revisão | Um processo de solicitação com um aprovador e um prazo de resposta, um caminho do ambiente local para o repositório, para staging e para produção, uma forma de ver qual versão está em produção, e desenvolvedores que leem o código gerado. | Um produto rodando em produção. - *Vertical · Product Builder* — **Assuma um resultado, front e back.** Leve o problema, as decisões, o design que foi aceito, as restrições e a verificação, do discovery até a produção. Você se apoia nos serviços compartilhados e o resultado continua sendo seu. - *Horizontal · Serviços compartilhados* — **Tornar o conhecimento especializado reutilizável.** Fornecer um responsável designado, um padrão ou contrato aprovado e os limites dele, um processo de resposta, e evidências de que a contribuição funciona no produto rodando — para você e para todos que fazem o mesmo trabalho. ### Um contrato nos dois sentidos **O Product Builder fornece** - O resultado, os usuários e o contexto - A contribuição necessária - As restrições dentro das quais ela precisa caber - Um critério de aceitação - Um prazo para a decisão **O responsável por Ops devolve** - Um responsável designado - Um padrão ou contrato aprovado, e os limites dele - Um prazo de resposta ou de entrega - Um processo de revisão - Evidências de que funciona no produto rodando **Antes de construir** ### Utilizável, não só documentado. Um documento sozinho não é um serviço utilizável. Antes de construir, verifique quais funcionam de verdade: um responsável designado, um processo de resposta, acessos aprovados, um ambiente que funciona e uma forma de verificar o que volta. Quando o starter, as convenções ou a API de que você precisa não existem, pare em vez de inventá-los — uma convenção inventada na hora é o que um revisor vai desfazer depois — e peça o artefato ao responsável por Ops, nomeando-o, e diga que resposta você espera. Enquanto isso, registre o substituto no diário, com data: o que você seguiu no lugar, quem concordou e o que ele substitui. Em uma equipe pequena, uma mesma pessoa pode ocupar vários desses papéis; ainda assim, as responsabilidades precisam ficar visíveis. **Exemplo** Em um fluxo de compartilhamento, o Product Builder é responsável pelas permissões que o produto pretende dar e pelo comportamento que as pessoas envolvidas aceitaram. Design Ops fornece o padrão revisado e seus estados, Backend e API Ops o contrato de autorização, Frontend Ops o starter dentro do qual o front é escrito, Data Ops os eventos que mostram como ele é usado. O Product Builder percorre o fluxo de ponta a ponta, com seus estados vazios, de erro e de permissão negada, e o verifica como um único produto. ## O percurso De uma pasta de documentos dispersos até algo rodando em produção, por conta própria, com agentes de código e de design fazendo o trabalho que você lhes passa: sete marcos em uma única ordem, e três coisas que atravessam todos eles. ### Por que a ordem importa - Uma pasta de documentos não é um discovery. - Um discovery não é um PRD. - Um PRD não é um protótipo que as pessoas envolvidas reconhecem como a ferramenta delas. - Um front em que você pode clicar não é um produto cujos fluxos se sustentam em profundidade. **A pergunta.** Qual dessas coisas você tem de verdade em mãos? Comece onde a resposta deixa de ser sim, e não deixe uma sessão passar por um marco que você não fechou: peça a ela, em cada marco, que diga em que marco está, o que tem, o que falta e o que você precisa decidir antes que ela passe adiante. Uma sessão que não sabe responder saiu do método. > “A linha que fecha um marco é o que você deveria ter em mãos antes de seguir em frente.” > > — Alexis Boyer *Figura — imagem, 21:9: Sete marcadores em fila sobre uma mesma superfície: a sequência como objeto físico, lida da esquerda para a direita.* ### Os sete marcos Sete marcos, numerados de 0 a 6. Nada acima deles, e nenhuma subfase. Cada um diz o que você faz, o que você tem em mãos quando ele se fecha, e os prompts e modelos que usa. | Marco | O que você faz | O que você tem em mãos | Recursos | | --- | --- | --- | --- | | 0 · Montar a pasta do projeto | Reúna todos os documentos de que o projeto precisa em uma única pasta criada para ele, e abra a sessão nessa pasta. Crie a memória e o diário antes que qualquer outra coisa rode, e o canal do projeto com todas as pessoas envolvidas dentro. O primeiro prompt converte e indexa; não interpreta nada. | tudo em uma única pasta, convertido, inventariado | [Inventariar e converter →](/pt/resources/prompt-inventory) · [Entrada de memória →](/pt/resources/memory-entry) · [Entrada de diário →](/pt/resources/journal-entry) | | 1 · Reunir o discovery | Faça o inventário do que você tem como ponto de partida, seja o que for, e percorra as fontes em busca de contradições, responsabilidades sem dono e o mesmo nome usado para superfícies diferentes, e não de um resumo. Coloque um agente para ler o que ninguém tem tempo de ler; o que volta é matéria-prima, nunca uma decisão. | o que se sabe, o que falta, o que se contradiz | [Ler os canais →](/pt/resources/prompt-channel-reading) | | 2 · Escrever o PRD | Rode o prompt de análise na pasta, faça-o separar o que está estabelecido do que se contradiz e do que falta, e responda você às perguntas de alinhamento. Depois refine o PRD e alinhe-o com o pessoal de negócio, incluindo as partes técnicas. | o que entra e o que fica de fora, acordado com o negócio | [Escrever o PRD →](/pt/resources/prompt-prd) · [Modelo de PRD →](/pt/resources/prd-template) | | 3 · Prototipar os fluxos de ponta a ponta | Nesta etapa, o agente de código assume o papel de PM: escreve o prompt para a ferramenta de design e exige fluxos de ponta a ponta, não só as telas principais. Itere na ferramenta de design, mostre o resultado às pessoas que vão usá-lo e continue até que elas digam que é a ferramenta delas. | um protótipo que as pessoas envolvidas reconhecem como a ferramenta delas | [Especificação de design →](/pt/resources/prompt-design-specification) · [Instrução de design →](/pt/resources/prompt-design-instruction) · [Refinamento →](/pt/resources/prompt-refinement) | | 4 · Levar o protótipo para o código | Parta do starter de frontend aprovado e das convenções de backend da organização, nunca de uma pasta vazia nem da exportação da ferramenta de design. Depois vêm as idas e vindas: o front rodando ao lado do design, você aponta o que não está certo, o agente corrige, você olha de novo. | um front que roda, em que você pode clicar | [Levar o protótipo para o código →](/pt/resources/prompt-port) · [Sem convenções de backend escritas →](/pt/resources/prompt-observed-conventions) · [Antecipar as necessidades de backend →](/pt/resources/prompt-backend-requests) | | 5 · Conectar o backend | Troque os serviços simulados pelos reais, fluxo a fluxo, e aprofunde cada um antes do próximo: o estado vazio, o erro, a resposta lenta, a permissão que diz não. Os papéis e a privacidade são aplicados no modelo de leitura, não no componente que exibe os dados. Cada mudança é confrontada com as convenções de backend, ponto a ponto, antes de ir para revisão. | os fluxos se sustentam em profundidade | [Conectar o backend →](/pt/resources/prompt-connect) | | 6 · Testar e depois lançar | Crie contas para as pessoas que devem testar enquanto o trabalho de conexão ainda está em andamento, compartilhe a vida do produto no canal e corrija o que volta à medida que volta. Depois obtenha o sinal verde dos leads das áreas envolvidas, e lance o produto. | contas em mãos reais, depois a produção | [Preparar a entrada em produção →](/pt/resources/prompt-release) | ### O que os marcos deixam | O que o percurso deixa | O que responde | O que contém | Marcos | | --- | --- | --- | --- | | Memória e diário do projeto | Por que o produto andou nessa direção, e o que aconteceu, e quando? | Dois arquivos criados antes de tudo: a memória guarda a posição atual, as decisões e seus trade-offs; o diário guarda o registro datado, nunca reescrito, incluindo o que se revelou um erro. | 0 | | Notas de discovery | O que as fontes disseram de fato, e onde elas divergem? | A lista de fontes, as ambiguidades, as perguntas para os stakeholders e uma primeira hipótese sobre os limites do produto, escritas na pasta para que o marco seguinte possa abri-las pelo nome. | 1 | | O PRD | O que está sendo construído, e o que não está? | Um documento cuja primeira seção é o enquadramento estratégico, com cada premissa marcada como premissa, junto com a fonte em que se apoia ou a pessoa que precisa decidi-la. | 2 | | O protótipo que as pessoas aceitaram | Esta é a ferramenta de que as pessoas envolvidas precisam? | Os fluxos de ponta a ponta, com seus estados e suas falhas, iterados na ferramenta de design e mostrados a usuários reais até que eles digam que é deles. | 3 | | O front rodando | Você consegue percorrer os fluxos e clicar neles? | Um front construído dentro do starter da organização, percorrido fluxo a fluxo ao lado do design, com o que foi adaptado e o que foi deixado diferente de propósito, por escrito. | 4 | | Os fluxos conectados | Os fluxos se sustentam em profundidade, ou só na superfície? | Cada fluxo ligado ao backend real, com seus estados vazios, de erro, de resposta lenta e de permissão negada, os papéis aplicados onde os dados são lidos, e cada mudança confrontada com as convenções de backend, ponto a ponto. | 5 | | O registro da entrada em produção | O que saiu, verificado como, e quem deu o sinal verde? | O conteúdo da entrada em produção, fluxo a fluxo, o que foi testado e com quais contas, o que se sabe que está quebrado, e qual revisão não aconteceu, se alguma não pôde acontecer. | 6 | Um marco se fecha quando você tem em mãos o que a linha de saída dele indica. Se não tiver, ele não está fechado, e a sessão diz o que falta e o que você precisa decidir. **O que é preciso.** De uma pasta com o material de discovery reunido até um front em que você pode clicar: de três a quatro horas no melhor dos casos e vinte e quatro no pior, quando o discovery já foi parcialmente reunido. Cerca de um mês para conectar o backend de modo que os fluxos se sustentem em profundidade, conforme o tamanho da aplicação. E o código ainda passa pela revisão dos desenvolvedores, e é aprovado, porque o agente trabalha dentro do starter e das convenções da organização. Esses números vêm da prática do próprio autor, não de um estudo. A IA constrói rápido, então as verificações que importam são humanas. As pessoas envolvidas aceitam o protótipo no marco 3, e convencer tem aqui um único sentido: elas dizem que esta é a ferramenta de que precisam. O código passa pela revisão dos desenvolvedores antes da produção, e os leads das áreas envolvidas dão o sinal verde. Nenhuma dessas verificações é uma etapa acrescentada no final. **Três coisas atravessam os marcos** em vez de ficar dentro de um deles. A sessão de controle é uma segunda sessão cujo único trabalho é questionar a primeira: ela lê, verifica e questiona, não muda código nem decide o escopo, e devolve constatações com suas evidências para que você decida. A salvaguarda permanente manda o agente de volta ao starter de frontend e às convenções de backend da organização antes de cada mudança no código — não uma vez no início, mas toda vez. O aprendizado contínuo não para quando a construção começa: você continua aprendendo sobre o negócio, os usuários e aquilo de que eles precisam, e quando esse aprendizado diz que o produto deveria mudar, você o muda, no marco em que estiver. Ele refina o que já existe em vez de acumular, e continua leve. [Sessão de controle →](/pt/resources/prompt-control-session) · [Restrição permanente →](/pt/resources/prompt-standing-constraint) · [Ler os canais →](/pt/resources/prompt-channel-reading) **Continuidade.** A construção não para no marco 6. O front continua pronto para demo e segue evoluindo: você volta aos fluxos, os aprofunda, conecta o que ficou pendente e mostra de novo no canal. Uma única coisa é congelada de propósito, e só uma: um MVP que precisa ir para produção, em que o conteúdo da entrada em produção para de mudar até que ela saia. A versão em inglês para um assistente apresenta os mesmos marcos um por um: [/method.md](/method.md). ### Comece no marco em que o seu trabalho está Nem todo mundo começa no marco 0. Você começa no marco em que o seu trabalho realmente começa, e os marcos que você pula são aqueles cujo resultado você já tem. - *Uma funcionalidade em um produto que já existe · começa no PRD* — **O produto já está rodando.** O PRD está escrito e o design está definido. Você não refaz a pasta nem o discovery: começa na seção do PRD que essa funcionalidade altera, depois o protótipo, a passagem para o código, o backend, os testes. - *Um produto que ainda não existe · começa no marco 0* — **A sequência inteira.** Uma pasta com tudo dentro, o discovery reunido e suas contradições nomeadas, um PRD acordado com o negócio, um protótipo que as pessoas envolvidas dizem ser a ferramenta delas, depois a passagem para o código, o backend fluxo a fluxo, e contas em mãos reais antes da produção. O que você não pula é um marco cujo resultado você não tem. Não há inventário? Não há PRD? Então é esse marco que você faz. Esses dois exemplos mostram que parte do percurso um trabalho concreto realmente segue. Eles não descrevem o projeto de nenhum cliente. # Recursos Rota: /pt/resources · Markdown: /pt/resources.md Os prompts que você roda em um marco, os modelos que preenche, os guias que lê e as skills que instalam o método no seu assistente. **Os guias** são o que você lê, **os prompts** o que você roda em um marco, **os modelos** o que você preenche, e **as skills** instalam o método no assistente com que você já trabalha. Cada recurso diz em que marco é usado, e o filtro ao lado das abas reduz a lista a esse marco. Tudo o que está aqui também vai dentro da pasta de projeto que você baixa para começar um caso, então um assistente lê tudo direto do seu próprio disco. [Baixar a pasta do projeto](/downloads/onirion-project.zip) ## Guias - [Guia principal](/pt/resources/method-guide) — O método em si: os sete marcos, o que cada um exige, os prompts que usa e o que você tem em mãos antes de seguir em frente. Use em todos os marcos. Markdown: [/pt/resources/method-guide.md](/pt/resources/method-guide.md) - [Começar um caso](/pt/resources/first-case) — Comece hoje o seu próprio projeto: uma pasta, uma sessão aberta nela, o primeiro prompt e os marcos que vêm depois. Markdown: [/pt/resources/first-case.md](/pt/resources/first-case.md) - [Exemplo resolvido](/pt/resources/worked-example) — O caso de prática percorrido de ponta a ponta, com cada artefato preenchido e marcado como simulado. Use em todos os marcos. Markdown: [/pt/resources/worked-example.md](/pt/resources/worked-example.md) - [Sandbox de prática](/pt/resources/sandbox) — Um pequeno aplicativo local, sem conta e sem rede, para percorrer o caso de prática. Markdown: [/pt/resources/sandbox.md](/pt/resources/sandbox.md) Leia o guia principal do começo ao fim uma vez antes de aplicar o método a um produto. O exemplo resolvido é o caso de prática percorrido pelos sete marcos, com cada artefato preenchido e marcado como simulado. ## Prompts - [Inventariar e converter](/pt/resources/prompt-inventory) — Converte o que pode, indexa cada fonte e lista o que não conseguiu ler. Não interpreta nada. Use no marco 0 · Montar a pasta do projeto. Markdown: [/pt/resources/prompt-inventory.md](/pt/resources/prompt-inventory.md) - [Ler os canais](/pt/resources/prompt-channel-reading) — Coloca um agente para ler o que ninguém tem tempo de ler. O que volta é matéria-prima, não uma decisão. Use no marco 1 · Reunir o discovery. Markdown: [/pt/resources/prompt-channel-reading.md](/pt/resources/prompt-channel-reading.md) - [Analisar e escrever o PRD](/pt/resources/prompt-prd) — Lê o que os dois primeiros marcos deixaram na pasta e escreve o PRD no modelo. Use no marco 2 · Escrever o PRD. Markdown: [/pt/resources/prompt-prd.md](/pt/resources/prompt-prd.md) - [Prompt de design — especificação](/pt/resources/prompt-design-specification) — A especificação longa que a sessão de PM escreve para a ferramenta de design, exigindo fluxos de ponta a ponta. Use no marco 3 · Prototipar os fluxos de ponta a ponta. Markdown: [/pt/resources/prompt-design-specification.md](/pt/resources/prompt-design-specification.md) - [Prompt de design — instrução](/pt/resources/prompt-design-instruction) — A camada curta digitada na ferramenta de design, junto com a especificação e os anexos. Use no marco 3 · Prototipar os fluxos de ponta a ponta. Markdown: [/pt/resources/prompt-design-instruction.md](/pt/resources/prompt-design-instruction.md) - [Prompt de refinamento](/pt/resources/prompt-refinement) — Para quando o primeiro resultado sai raso demais, conceitual demais ou parecido demais com um dashboard. Use no marco 3 · Prototipar os fluxos de ponta a ponta. Markdown: [/pt/resources/prompt-refinement.md](/pt/resources/prompt-refinement.md) - [Levar o protótipo para o código](/pt/resources/prompt-port) — Entrega o protótipo e o starter ao agente de código, dentro das convenções da sua organização. Use no marco 4 · Levar o protótipo para o código. Markdown: [/pt/resources/prompt-port.md](/pt/resources/prompt-port.md) - [Convenções de backend observadas](/pt/resources/prompt-observed-conventions) — Quando o backend tem código, mas não tem convenções escritas: o agente descreve as que o código já segue, e o responsável pelo backend as confirma, corrige ou descarta. Use no marco 4 · Levar o protótipo para o código. Markdown: [/pt/resources/prompt-observed-conventions.md](/pt/resources/prompt-observed-conventions.md) - [Antecipar as necessidades de backend](/pt/resources/prompt-backend-requests) — Enquanto o protótipo vai para o código: o agente lista o que o trabalho de backend vai exigir de outras equipes — acessos, permissões, chaves, recursos — como pedidos a enviar já, e não no dia em que o trabalho travar. Use no marco 4 · Levar o protótipo para o código. Markdown: [/pt/resources/prompt-backend-requests.md](/pt/resources/prompt-backend-requests.md) - [Conectar o backend](/pt/resources/prompt-connect) — O marco mais longo: os fluxos precisam se sustentar em profundidade, não na superfície. Use no marco 5 · Conectar o backend. Markdown: [/pt/resources/prompt-connect.md](/pt/resources/prompt-connect.md) - [Preparar a entrada em produção](/pt/resources/prompt-release) — O que foi testado, por quem, com quais contas, o que se sabe que está quebrado e o que se pede aos leads que aprovem. Use no marco 6 · Testar e depois lançar. Markdown: [/pt/resources/prompt-release.md](/pt/resources/prompt-release.md) - [Sessão de controle](/pt/resources/prompt-control-session) — A segunda sessão, a que questiona. Lê, verifica e questiona; não muda nada. Use em todos os marcos. Markdown: [/pt/resources/prompt-control-session.md](/pt/resources/prompt-control-session.md) - [Restrição permanente](/pt/resources/prompt-standing-constraint) — Inclua-a em cada prompt que muda código: memória, diário e em que ponto está o trabalho. Use em todos os marcos. Markdown: [/pt/resources/prompt-standing-constraint.md](/pt/resources/prompt-standing-constraint.md) Dois deles não estão ligados a um marco específico. A sessão de controle roda ao lado da principal, do discovery até o backend, e a restrição permanente vai dentro de cada prompt que muda código. ## Modelos - [Modelo de PRD](/pt/resources/prd-template) — O único modelo que o método preenche. Todos os marcos depois do segundo o leem. Use no marco 2 · Escrever o PRD. Markdown: [/pt/resources/prd-template.md](/pt/resources/prd-template.md) - [Memória do projeto — entrada](/pt/resources/memory-entry) — Uma entrada da memória: onde o produto está e por que ele andou nessa direção. Use em todos os marcos. Markdown: [/pt/resources/memory-entry.md](/pt/resources/memory-entry.md) - [Diário do projeto — entrada](/pt/resources/journal-entry) — Uma entrada do diário: datada, nunca reescrita, incluindo o que se revelou um erro. Use em todos os marcos. Markdown: [/pt/resources/journal-entry.md](/pt/resources/journal-entry.md) O modelo de PRD é o único documento que o método preenche: o marco 2 o escreve, e todos os marcos depois dele o leem. Os outros dois são formatos de entrada que você copia — um para uma decisão, outro para o que aconteceu. ## Skills ### Skill do Claude Code - Como chamar: Peça o método pelo nome; `/onirion` onde a versão o oferece - Instala em: `.claude/skills/` - Inclui: O guia principal, os treze prompts e os modelos, dentro da própria skill, então ela não lê nada de nenhum outro lugar. - Instalação: Não há nada para instalar. Ela já está na pasta de projeto que você baixa, em `.claude/skills/onirion/`. Para levá-la a outro projeto, copie `.claude` e `.agents`. [Instruções de instalação](/pt/resources/claude-code-skill#adapter) [Baixar a pasta do projeto](/downloads/onirion-project.zip) ### Skill do Codex - Como chamar: Descreva a tarefa e deixe que ela a reconheça; `$onirion` onde a versão o oferece - Instala em: `.agents/skills/` - Inclui: O guia principal, os treze prompts e os modelos, dentro da própria skill. - Instalação: Não há nada para instalar. Ela já está na pasta de projeto que você baixa, em `.agents/skills/onirion/`. Copie essa pasta para `$CODEX_HOME/skills/` para tê-la em todo lugar. [Instruções de instalação](/pt/resources/codex-skill#adapter) [Baixar a pasta do projeto](/downloads/onirion-project.zip) As duas skills levam o mesmo método. Elas fazem a sessão dizer em que marco está, o que tem em mãos, o que falta e o que você precisa decidir antes que ela passe adiante — e param aí em vez de inventar uma decisão, uma aprovação ou um serviço. [O que muda entre as duas ferramentas →](/pt/resources#tools) ## Um método, dois caminhos de execução Nenhum dos adaptadores muda o método: os marcos, o que cada um exige e o que o fecha são os mesmos com qualquer assistente. O que nenhum dos dois traz é a ligação — como a sessão principal e a sessão de controle se dirigem uma à outra dentro de uma ferramenta específica é algo que você configura nessa ferramenta. | O que você configura | Com o Claude Code | Com o Codex | | --- | --- | --- | | Instalar o método | Não há nada para instalar: ele está na pasta de projeto que você baixa, em `.claude/skills/`. | Não há nada para instalar: ele está na mesma pasta, em `.agents/skills/`. | | Chamá-lo | Peça o método pelo nome. `/onirion` é um atalho onde a versão o oferece. | Descreva a tarefa e deixe que ela a reconheça. `$onirion` é um atalho onde a versão o oferece. | | Rodar a sessão de controle | Uma segunda sessão aberta na mesma pasta, iniciada com o prompt da sessão de controle e o bloco de regras que o acompanha. | Uma segunda sessão aberta na mesma pasta, iniciada com o mesmo prompt e o mesmo bloco de regras. | | Mudar de pasta no marco 4 | Copie `.claude` e `.agents` para o repositório assim que ele existir ao lado da pasta de fontes. | Copie as mesmas duas pastas, ou coloque a skill entre as suas próprias skills do Codex para que ela acompanhe você. | Instalar não muda nada no resto do seu projeto e não inicia nenhum projeto de produto. Os dois instaladores se recusam a sobrescrever uma skill que já existe; então, se já houver uma instalação anterior, cabe a você lê-la e removê-la antes de substituí-la. **Termos de reutilização** **O método pode ser reutilizado livremente.** O guia principal, os prompts, os modelos, o caso de prática e o exemplo resolvido estão sob a licença Creative Commons Atribuição 4.0 ([CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)), com o crédito “Onirion, um método de Alexis Boyer”; o código — o aplicativo do sandbox e seus testes, e os arquivos das skills — está sob a licença [MIT](https://opensource.org/license/mit). Os modelos preenchidos pertencem a quem os preenche, sem necessidade de crédito. **As páginas deste site não.** Elas são © Alexis Boyer, todos os direitos reservados: use o método no seu próprio trabalho o quanto quiser, mas não republique estas páginas, inteiras ou em parte, sem pedir permissão. As imagens não estão cobertas por nada disso. # Guia principal Rota: /pt/resources/method-guide · Markdown: /pt/resources/method-guide.md *O texto a seguir é o do kit, em inglês.* # Onirion · core guide **A method by Alexis Boyer · version 4.0 · September 22, 2026** ## What this is A way to take one product from a folder of scattered documents to something running in production, alone, with coding and design agents doing the work you brief them for. It is written for a **Product Builder**: one person accountable for one product outcome, end to end, front and back. You carry the problem, the decisions, the design that was accepted, the constraints and the verification. You do not hand the outcome to anyone. The method is tool-neutral. The gates, what each one demands and what ends it do not change with the assistant you use. The two adapters in this kit — one per supported assistant — cover installation and how the two sessions address each other in that tool. Neither adapter changes the method. ### Vertical and horizontal You own one outcome, **vertically**: one product, front and back, from the discovery through to production. Design, Frontend, Backend and API, Data, access, delivery and review are **horizontal** — services supplied to you, and to everyone else doing the same job. You draw on them and keep the outcome. What they owe you is set out at the end of this guide, under “What Ops owes a Product Builder”. ### The seven gates Seven gates, numbered 0 to 6. Nothing above them, and no sub-phases. Each gate says what you do, the steps inside it, and the prompts and templates it uses. The line that closes a gate is what you should be holding before you move on. | Gate | What you do | What you have in hand | | --- | --- | --- | | **0** | Set up the project folder | everything in one folder, converted, inventoried | | **1** | Gather the discovery | what is known, what is missing, what contradicts | | **2** | Write the PRD | what is in and what is out, agreed with the business | | **3** | Prototype the end-to-end flows | a prototype the people concerned recognize as their tool | | **4** | Port the prototype into code | a front end that runs, that you can click | | **5** | Connect the backend | the flows hold in depth | | **6** | Test, then ship | accounts in real hands, then production | Three things run across all of them rather than inside one: **the control session**, which challenges the work from the discovery to the backend; **the standing guardrail**, which sends the agent back to your frontend starter and your backend conventions before every change to the code; and **continuous learning**, which keeps the research going while the building goes on and changes the product at whatever gate you are at. All three have their own section after the gates. The build is continuous. The front stays demoable and keeps evolving; shipping is not the end of the sequence. ## Gate 0 — set up the project folder ### What you do Everything the project needs goes into one folder created for it. Not scattered across drives, mailboxes and tabs: one folder, made for this project, holding every document the work will draw on. Open your coding agent's session or project on that folder. At this point it is not a code repository. There is no application, nothing to build, nothing to run. What the session is pointed at is a folder of sources, and that is enough to start. ### The steps 1. Create the folder. Put into it every document the project needs — what was written before, what was received, what you collected yourself. 2. Create the memory and the journal in that folder, before anything else starts: `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md`. 3. Save the PRD template into the folder, as `prd-template.md`. It stays there unfilled until Gate 2, which reads it by that name. 4. Create the project channel. What goes in it: the life of the product — what was decided, what is being tested, what has just become clickable, what broke. Who is in it: everyone concerned by the product, the business people included. 5. Open the control session and give it its starting prompt: a second session on the same folder, whose only job is to challenge the first. Name the main session in the last bracket of that prompt, so the two can reach each other. 6. Run the first prompt: inventory and convert. It writes the converted files into the sub-folder `converted/` and the index into `converted/INDEX.md`, leaves the memory, the journal and the template out of the sources, and records what it did in the journal. It does not interpret anything. 7. Read the index it returns, and the list of what it could not read. Fill the obvious holes now, while it is cheap. 8. Tell the session to state where it is before it goes further, and keep asking for it at every gate. ### When the work started before the folder The folder is rarely the first thing that happens. You have been working on the product for a week, an assistant has already read repositories and threads and pulled copies of things, and the folder arrives afterwards. That is normal, and it does not mean starting again. **Pour what exists into the folder before anything else.** Material an assistant gathered in an earlier session lives in that session's temporary directory, and that directory does not survive the session. Ask it to copy what it holds into the project folder, as files, unchanged — it moves them, it does not choose them, summarise them or rename them to something tidier. Then run the Gate 0 prompt on what arrived, and it converts and indexes it like everything else. **What an assistant remembers is not a source.** The thread it read last week, the call it was told about, the decision someone mentioned in passing: none of it is in the folder, so none of it exists for the next session. Either it is written into the folder as a file, dated and marked for what it is — a note of what was said, not a record of what was decided — or it is gone. This is the most common way a project arrives at Gate 2 with a hole in it that nobody can name. **And what only you hold, write down now.** The call you were in and the assistant was not is a source that exists nowhere until you spend ten minutes on it. Rough notes in the folder beat a perfect memory that fades by tomorrow. ### The prompts and templates it uses The setup uses two prompts, and keeping them apart is the point. The first one looks at what you have. The second one decides what it means. Mixing them gives you conclusions drawn from a pile nobody has inventoried. **The inventory and conversion prompt.** It is the one you run here. ```text You are at Gate 0 of the method: setting up a new product project. The project folder is the one this session is opened on. Work only inside it. Do this, and nothing else: 1. Walk `sources/` and the top of the project folder, and list every file you find. Skip the assistant's own tooling — any dotted folder such as `.claude/`, `.agents/` or `.git/`, and everything inside it. Skip the project's own records too — `PROJECT_MEMORY.md`, `PROJECT_JOURNAL.md`, `prd-template.md`, `START-HERE.md` and `sources/README.md`. None of those are sources. 2. Everything that is a source belongs in `sources/`. A source sitting at the top of the project folder is moved in there, unchanged and unrenamed; that is the one move you may make. Then convert to Markdown everything you can convert, into the sub-folder `converted/`. Never modify, rename or overwrite an original. 3. Write `converted/INDEX.md`: one line per source, with the file name, what it is, and the date it is from. If you cannot date it, say so. 4. List everything you could not read or could not convert, and why. 5. Append one dated entry to `PROJECT_JOURNAL.md`: what you converted, what you could not read, and where the converted files are. Do not analyse the content. Do not draw conclusions. Do not write a PRD. Do not send anything anywhere — no service, no channel, no address. Report the index, the list of what you could not read, and where you put the converted files. Before you finish, state which gate you are at, what you have, what is missing, and what I must decide before you cross to the next gate. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` Two rules in that prompt matter more than they look. The originals are never touched: the conversion writes into `converted/`, so a bad conversion costs you nothing. And the pass sends nothing anywhere: it reads and writes inside the folder, full stop. **The second prompt** is the one that analyses this material and writes the PRD. It is not run here. It belongs to **Gate 2 — write the PRD**, and Gate 1 comes first. ### The agent says where it is Set this up now, because it costs one line and it holds for the rest of the build. Before it goes further, the session states which gate it is at, what it has in hand, what is missing, and what you must decide before it crosses. "I am at Gate 3" is the shape of it, followed by the three answers. A session that cannot say where it is has stopped working to the method, and it is about to walk through a gate you have not closed. **And its own announcement is not your answer.** This is how a gate gets crossed without anyone noticing, and it is worth naming because it does not look like disobedience. The session says what it is about to do — "I'll write the design prompt now" — and then treats having said it as having been told. It was its intention, not your decision. Seen from your side nothing happened: you were told something, and work began. The rule is one sentence, and it belongs in the prompt: saying what comes next is not permission to do it, and the gate is crossed when you answer. ### The memory and the journal start here Create both now, at the start, before the first prompt runs. Not at the end, not when the code starts, not when you remember. They are two different things and they do two different jobs. **The project memory** — `PROJECT_MEMORY.md` — is the reasoning layer. It explains why the product moved the way it moved. It captures: - current product position; - product principles; - major decisions; - trade-offs; - known risks; - what worked; - what did not work; - which source wins when sources disagree; - open questions; - case-study angles worth preserving. The memory answers one question: where does this product stand today. It opens with the current position, and you revise that opening as the product moves. Underneath it, each decision is a dated entry, and when a later decision replaces an earlier one you add the new entry and leave the old one in place, marked as replaced. So the top of the file is always current and nothing that was decided disappears. Use it when preparing handoffs, stakeholder updates, the PRD, case studies, and future coding sessions. Entry format: ```text ## [Date] - [Decision or topic] Context: Decision: Rationale: Trade-offs: Impact on product / architecture / QA: Open questions: Links: ``` **The project journal** — `PROJECT_JOURNAL.md` — is the chronological activity log. It captures what happened over time. Each meaningful entry includes: - date; - context; - decision or change; - implementation summary; - verification performed; - trade-offs; - follow-ups; - links to tickets, pull requests, QA reports, decisions taken in chat, documentation pages, or deployed previews. The journal is appended to and never rewritten. Entries that turned out to be wrong stay in it, including the mistakes — that is most of its value, because it is the only record of why you went down a road that did not work. Do not log every tiny interface tweak. Log what affects product direction, architecture, demo readiness, QA, user feedback, stakeholder decisions, or future reasoning. Entry format: ```text ## [Date] - [Workstream or session] Context: Decision or change: Implementation summary: Verification performed: Trade-offs: Follow-ups: Links: ``` Both files live in the project folder while there is no repository. When the code starts, at Gate 4, they move into the repository under `docs/` — `docs/PROJECT_MEMORY.md`, `docs/PROJECT_JOURNAL.md`, and the PRD beside them — and they stay what an agent reads before touching the application. ### The control session starts here too Open it now, at the same moment as the memory and the journal, and for the same reason: what has a moment of birth exists, and what does not, does not. The method calls the control session in at Gate 1, at Gate 2, after Gate 4 and during Gate 5 — but if nobody opened it at the start, none of those calls happen, and a drift is caught only on the day you happen to ask. It costs one window. A second session on the same folder, the control-session prompt pasted into it, and the main session's name in the last bracket so the two can address each other. It reads, checks and challenges; it changes no code and decides no scope. ### The project channel starts here too Create a channel for the project on day one and put everyone concerned in it, business people included. It exists from the first day, next to the memory and the journal, and it is where the life of the product is shared from here to production. The people who will use the tool should not be discovering it at the end. **Gate 0 — what you have in hand:** everything in one folder, converted, inventoried. ## Gate 1 — gather the discovery ### What you do The starting material varies from one project to the next, and every one of these is a normal starting point: - discovery already done by someone else, sitting in existing files; - transcripts of user interviews; - talking to the users directly; - doing the discovery yourself; - spreadsheets of products, scopes and features already drawn up, with ideation on what could be built. You will often have several of them at once, and they will not agree. That is the material, not a problem with it. ### Sources to inspect - strategy and positioning material; - operational documents on the shared drives; - existing PRDs, journals, backlogs and research in the documentation tool; - existing applications and repositories, especially what already generates revenue; - stakeholder conversations in chat; - user interviews and transcripts; - production constraints and deployment risks; - current frontend standards and starter or template guidance. The goal is not to summarise everything. The goal is to identify contradictions, ownership gaps, and cases where different teams are using the same product name for different surfaces. What you come out with: - the source list; - the ambiguity list; - the questions for stakeholders; - an initial hypothesis on the product boundary; - known privacy and compliance risks; - existing repository, starter and template constraints. That goes down in the project folder, as `DISCOVERY.md`: the source list, the ambiguity list and the questions for stakeholders under their own headings, with the hypothesis, the risks and the constraints beside them. The prompt below writes that file, and you read it and correct it. Gate 2 opens it by name. A finding that stays in a chat window is a finding the next gate cannot read. ### The steps 1. **Take stock of the starting material.** Whatever of the list above you actually have, and the fact that the pieces will not agree with each other. 2. **Go through the sources to inspect.** You are looking for contradictions, ownership gaps, and the same product name used for different surfaces — not for a summary. 3. **Ask an agent to read what nobody has time to read.** By name, with the prompt below: a channel, a mailbox, a period. 4. **Keep what comes back as input, never as a decision.** The scope decision stays with you. 5. **Read the `DISCOVERY.md` the prompt wrote** and correct it. The headings are fixed; what is under them is yours to sharpen, and an empty heading stays empty rather than being filled for the look of it. 6. **Give the control session the material the main session read** and have it challenge what the main session concluded. ### Have an agent read what nobody has time to read There is always material that holds the answer and that no one will ever go through: months of a chat channel, the running communications with clients when the product sits between an operations team and the people it serves. Have an agent read it, analyse it, and draw conclusions that feed the discovery. You ask for this by name. It is not a scheduled routine, and it is not a job that runs in the background: you point at a channel, a mailbox, a period, and you ask. Because iterating is cheap, you can ask again at any gate — an insight that arrives while you are connecting the backend is still worth having. What comes back is input. It is never a decision. The scope decision stays with the Product Builder. ### The privacy rules, plainly - Ask before reading a channel or a mailbox. Every time. The fact that you have access is not the same as having been asked to look. - Say what was read. Name the channel, the period, the threads. Anyone who later reads a conclusion should be able to see where it came from. - Keep personal data out of what is written down. The discovery needs the pattern, not the person: what people are struggling with, not who said it about whom. The control session belongs here too: give it the material the main session read and have it challenge what the main session concluded. ### The prompts and templates it uses **The prompt for reading what nobody has time to read.** ```text You are at Gate 1 of the method: gathering the discovery. Read [name the channel, mailbox or thread, and the period]. If there is nothing outside the folder to read, say so and work from the converted folder alone; the rest of this prompt does not change. Then: - summarise what is being said about [the product or the problem]; - list what it confirms, what it contradicts, and what is new; - name the open questions it raises for the discovery. Then write `DISCOVERY.md` in the project folder, under these headings and no others: the source list, the ambiguity list, the questions for stakeholders, the hypothesis on the product boundary, the privacy and compliance risks, and the repository, starter and template constraints. Put under them what you read here and what the project folder already holds. Where a heading has nothing under it, say so rather than filling it. Gate 2 opens this file by name. Rules: - the project folder's own files are yours to read without asking: `converted/` and its index, `DISCOVERY.md`, the memory and the journal; - outside the project folder, read what I named above and nothing else: ask me before opening any other channel, mailbox, drive or thread, every time; - tell me exactly what you read; - keep names, addresses and personal details out of what you write down; - return findings, not decisions. I decide what is in scope. `DISCOVERY.md` stays current from here on. Each time I answer one of your questions, write what my answer settles into the file before you go on, and say in one line what you changed there — or why there was nothing to change. Do not hold it until the end of the conversation. Before you finish, append an entry to the project journal — what you read and what you wrote down — and add to the project memory only what is genuinely settled, if anything. Then state which gate you are at, what you have, what is missing, and what I must decide before you cross to Gate 2. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **Gate 1 — what you have in hand:** what is known, what is missing, what contradicts. ## Gate 2 — write the PRD ### What you do This is a large part of the work. The PRD defines what the tool is going to be: what you want, and what you do not want. It gives the direction section by section, and it is what the agent works from for the rest of the build. One document comes out of this gate, not two: **a PRD whose first section is the strategic framing.** Run the second setup prompt here — the one that reads the gathered material and produces that PRD from it. You do not stop there. You refine it, iterate on it, and align it with the stakeholders and the business people, including on the technical parts, even when they are not technical themselves. Those parts decide what you will need, so they get explained rather than skipped. That second prompt has to be told what to read and what to return: the converted folder and its index, `DISCOVERY.md` from Gate 1, and the fact that anything not in the folder — a channel, a mailbox, client communications — is named explicitly rather than assumed. What it returns is a first PRD, its first section the strategic framing and its other sections filled from the material, every assumption marked as an assumption, and the contradictions listed rather than resolved on its own. ### The steps 1. **Run the PRD prompt below** on the converted folder and its index, `DISCOVERY.md`, and the project memory and journal. 2. **Make it state three things separately before it writes anything:** what is established and which source establishes it; what contradicts what, source against source; what is absent. 3. **Answer its alignment questions.** Where two sources point different ways, you decide — it does not choose silently. 4. **Read the PRD it returns** and check that every assumption is marked as an assumption, with the source it rests on or with what is missing and who has to decide it. 5. **Refine it and iterate on it.** The first pass is a draft, not the document. 6. **Align it with the stakeholders and the business people,** the technical parts included: those parts decide what you will need, so explain them rather than skip them. 7. **Mark each assumption validated or waiting on a decision,** with the name of the person who takes it, and update the product boundary with what came back. 8. **Point the control session at it** — at its strategic framing section as much as at the rest. ### The strategic framing is the PRD's first section **The strategic framing** is the short statement of what the product is going to be — what is wanted, what is not wanted, the boundary it holds and the business loop it serves. It is not a separate document. It is the first section of the PRD, and the sections after it detail what it states. It is also what every later prompt means when it says to read the strategic framing: open the PRD, read its first section. The PRD lives in the project folder beside the memory and the journal, and it moves into `docs/` with them when the code starts, at Gate 4. One term, everywhere: the strategic framing. ### What the PRD contains The PRD's sections, in this order — fourteen, and no others: 1. strategic framing; 2. product boundary; 3. roles and permissions; 4. core workflows; 5. product states and data visibility; 6. privacy and ethics rules; 7. which source wins when sources disagree; 8. design baseline and acceptable drift; 9. functional depth; 10. backlog taxonomy; 11. backend and API assumptions; 12. acceptance criteria; 13. the QA contract; 14. open decisions. ### What a PRD must make explicit for AI-assisted work An agent uses the PRD as its operating context, so the PRD has to be more explicit than a classic product spec. **Product boundary.** Who the app is for; who it is not for; which workflows belong in another product; what the app must never expose; which shared core or backend objects are assumed; the non-goals. **Role and permission model.** What each role can see and do, especially when the data is sensitive. Two roles that differ only by one screen still have to be written out. **Privacy and ethics rules.** Which data is sensitive and how it must be handled. This directly controls the interface, the data model, search, exports, backend read models, and QA — so it belongs in the PRD, not in someone's head. **What wins when sources disagree.** Write the order down. For example: 1. explicit stakeholder decision; 2. validated user interview insight; 3. the strategic framing section of the current PRD; 4. the rest of the current PRD; 5. backlog ticket; 6. older documents or older prototype behaviour. Without this, agents overfit to outdated tickets. For the same reason: do not use old backlog tickets before checking the product boundary and that order. **Design baseline.** Name the design reference, and say what counts as acceptable drift from it. **Functional depth.** Say which flows must actually work in the front-only prototype and which may stay placeholders. If a user can click something, define what it does. Avoid vague simulated states unless you scoped them on purpose. **Backlog taxonomy.** Keep these apart: product decisions; implementation tasks; design parity issues; privacy and legal guardrails; QA findings; backend integration work; future nice-to-haves. It stops an agent from treating an undecided legal question as a bug to code around. **QA contract.** The personas to test; the role-based privacy checks; requirements derived from transcripts; regression flows; validation commands; the expected report format. ### When sources disagree, ask an alignment question When two sources point different ways, ask the decision-maker a short alignment question instead of silently choosing a direction. A good alignment question: - states what was observed in source A and in source B; - explains the product risk of choosing the wrong interpretation; - proposes a default direction; - asks for confirmation or correction. This is what keeps the wrong product from being encoded into the PRD and then into the prototype. What you get back: the stakeholder's confirmation, an updated product boundary, an entry in the decision log, and each PRD assumption marked either as validated or as waiting on a decision, with the name of the person who takes it. The control session can be pointed at the PRD — at its strategic framing section as much as at the rest: not only whether the PRD is coherent, but whether the direction holds. ### The prompts and templates it uses **The PRD prompt.** This is the second setup prompt, run here and not at Gate 0. ```text You are at Gate 2 of the method: writing the PRD. Read these, all of them in the project folder: - the converted folder `converted/` and its index `converted/INDEX.md`; - `DISCOVERY.md` in the project folder: the source list, the ambiguity list and the stakeholder questions written at Gate 1, including what an agent read on my behalf; - the project memory and the project journal; - the PRD template `prd-template.md`, saved into the project folder at Gate 0, for the shape of each section. Anything that is not in the project folder — a channel, a mailbox, client communications — is named here by me, or it is not read. First, state three things, separately: 1. what is established, and which source establishes it; 2. what contradicts what, source against source, without resolving it yourself; 3. what is absent — the questions this material does not answer. Then ask me the alignment questions. Where two sources point different ways, do not choose silently. For each one, give me: what source A says, what source B says, the product risk of choosing the wrong interpretation, the direction you would default to, and the confirmation you need from me. Then produce one document: the PRD, with these fourteen sections, in this order, and no others: 1. strategic framing — what the product is going to be, what is wanted and what is not, the boundary it holds, the business loop it serves; 2. product boundary; 3. roles and permissions; 4. core workflows; 5. product states and data visibility; 6. privacy and ethics rules; 7. which source wins when sources disagree; 8. design baseline and acceptable drift; 9. functional depth; 10. backlog taxonomy; 11. backend and API assumptions; 12. acceptance criteria; 13. the QA contract; 14. open decisions. Rules: - one document, not two: the strategic framing is the PRD's first section, and the sections after it detail what it states; - mark every assumption as an assumption, with the source it rests on or, when the material does not settle it, what is missing and who has to decide it; - invent no decision, no approval, no API and no standard; if it is not in the material, it is absent, and absent is an answer; - do not send anything anywhere — no service, no channel, no address. The PRD stays current from here on. Each time I answer one of your alignment questions, edit the sections my answer changes before you go on, and say in one line which sections you touched — or why none of them moved. Do not hold the document until the end of the conversation. Before you finish, write into the project memory every decision this gate settles — my answers to the alignment questions, each with its context, its trade-off and what it rules out — and append an entry to the project journal. Then state which gate you are at, what you have, what is missing, and what I must decide before you cross to Gate 3. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **The template.** The PRD template is the kit's `templates/prd.md`, and it is saved into the project folder as `prd-template.md` at Gate 0, which is where the prompt reads it. It carries the fourteen sections above, in that order, and the list above is what decides which sections there are. **Gate 2 — what you have in hand:** what is in and what is out, agreed with the business. ## Gate 3 — prototype the end-to-end flows ### What you do The PRD exists. Now your coding agent takes the PM role: it writes the prompt for the design tool, and it prompts the design tool directly. You do not hand-write the design brief yourself, and you do not paste screens between the two by hand. One demand matters more than the rest of the prompt: **end-to-end flows, not just the major screens**. If you ask only for the main screens, you pay for it later. Every time you go deeper into a flow — a validation error, a second step, a role that sees less — you go back and forth between the coding agent and the design tool. Ask for the depth up front and that ping-pong stops. Then you iterate in the design tool itself, not in code. You show the result to the users concerned, or to the business people when it is a business application. You keep iterating until it is convincing. Convincing has one meaning here: **the people you show it to say this is the tool they need.** The method is tool-neutral. Any app-oriented design and prototyping tool works; the author uses Claude Design. What does not change is who writes the prompt, what the prompt must demand, and what ends the gate. **And a design tool is what this gate needs to close.** The prompts below produce the specification; the prototype comes from the tool they are given to. If you have none, the session will write you a specification and nothing more, and it should say so rather than let a brief pass for a prototype. Either get a tool, or accept in writing that you are crossing to Gate 4 with a specification instead of something the people concerned have seen and recognised — and record what that costs, because it is paid at Gate 4 in back-and-forths. ### The steps 1. **Give the session what it needs to write the brief.** The PRD, whose first section is the strategic framing, the discovery material it rests on, your organization's design system or a reference product, and the product boundary. Tell it explicitly: you are the PM for this step, you are at Gate 3, write the design prompt. 2. **Have it build the prompt as a package, not one message.** A short instruction layer, a long specification, and the attachments that should constrain the output. Compressing everything into a single chat message loses the depth. 3. **Read the prompt before it is sent.** Check five things: who the product is for and who it is not for; the roles and what each one can see; the screens and flows that must exist; the states — empty, loading, error, restricted; the privacy rules. Then check that the end-to-end demand is actually in there. 4. **Give the specification to the control session before it is sent.** This is the document the prototype is built from, so it is where invention costs the most. Three questions, and they are enough: does every demand in it come from the PRD; is there anything in it the PRD does not support; is there anything the PRD requires that it leaves out. A screen invented here becomes a screen built at Gate 4 and connected at Gate 5 before anyone notices it was never agreed. 5. **Let the session prompt the design tool directly** when your tools can reach each other: it is faster, and the package arrives intact. When they cannot, you carry it yourself — paste the instruction layer, the specification and the attachments in the order they were written, and change nothing on the way. 6. **Iterate inside the design tool.** Depth first: the flows that are still surface-level, the states that are missing, the screens that lead nowhere. Use a refinement prompt rather than restarting. 7. **Show it to real people.** The users concerned. The business people when it is a business application. Show a flow they do every day, not a tour of the navigation. 8. **Iterate again on what they said, and show it again.** Stop when they tell you it is their tool. 9. **Write down what the showings changed.** What was contradicted, what was confirmed, what you dropped. That goes in the project memory and journal you created at Gate 0. ### When the gate does not close Two cases, and neither one is a reason to stall. **The people disagree with each other.** The decision goes to whoever owns the strategy — the company's chief executive, or the lead concerned — and they settle it. The decision then goes into the project memory, dated, so that the prototype and everything built on it rest on a decision someone took rather than on the last opinion heard. **The product is new and has no users yet.** You cannot invent them. You find one or two, and because the loop is fast you change things the moment they give you feedback. What you do not do is launch to everyone, or make a large announcement, for a product you know is not ready. Say that plainly rather than dress it up: there is no measure of ready. There is a minimal scope that must work, and you launch with that. If nobody could test it, you are its first user. Then you launch small, and the first real users have the last word. ### When there is no design system Stop before you invent one. House standards made up on the spot are what the review will undo later, and the prototype and the front end will stop being the same thing. Do this instead: - **Name a reference product to follow.** An existing product whose interface your organization already accepts. Name it in the design prompt and say it is a constraint, not inspiration. - **Ask Design Ops for the system.** The components and their states, the tokens, the rules for using them, what may be extended and what may not, and who maintains it. - **Record the substitute.** In the journal, dated: what you followed instead of the system, with whose agreement, and what it stands in for. The next person should be able to see what they are looking at. Until the system arrives, the reference product is what you design against, and it is what the front end will follow at Gate 4 as well — the prototype and the code must keep drawing on the same thing, whatever that thing is. When the system does arrive, the gap between it and the reference product is a list of changes to make, not a redesign. ### The prompts and templates it uses **The design prompt — long specification.** Use this for a whole product. A short prompt is enough to explore one component; it is not enough to create an application. ```text Design a full high-fidelity web application prototype for [PRODUCT NAME], [ONE-SENTENCE PRODUCT DESCRIPTION]. This is a real logged-in [B2B SaaS / internal operations / marketplace / admin] application, not a landing page. Start directly inside the product experience. Treat the attached PRD — whose first section is the strategic framing — together with the research notes, source documents and design-system references, as what decides. If a linked source is gated or unavailable, work from the pasted content and do not invent a product decision that is missing. Design end-to-end flows, not only the major screens. Every flow listed below must be walkable from its entry point to its final state, including the intermediate steps, the branches, the failures and the confirmations. ## Strategic context [Why this product exists, the business loop it serves, the constraints around it.] This product helps [PRIMARY USERS] answer: 1. [CORE USER QUESTION] 2. [CORE USER QUESTION] 3. [CORE USER QUESTION] The product should feel like [PRODUCT METAPHOR: an operations workbench, a daily work console]. Calm, precise, structured, auditable, built for repeated daily work. ## Product boundary This product is for: - [ROLE / USER GROUP] - [ROLE / USER GROUP] This product is not for: - [OUT-OF-SCOPE USER / TEAM] Do not design: - [OUT-OF-SCOPE WORKFLOW] - [OUT-OF-SCOPE SCREEN] - [INTERNAL-ONLY OR SENSITIVE SURFACE] If an out-of-scope workflow exists, represent it only as a safe status, a handoff or a request state inside this product. ## Users and roles - [ROLE]: [what they do, what they need, what they can see] - [ROLE]: [what they do, what they need, what they can see] - [READ-ONLY / ADMIN / SUPERVISOR ROLE]: [permissions and constraints] Show role-based differences wherever they materially change navigation, actions, data visibility, disabled states or empty states. ## Core product principles 1. Lead with action, not decorative analytics. 2. Make the primary workflow usable end to end. 3. Keep sensitive data role-gated and explain visibility limits clearly. 4. Prefer tables, queues, drawers, modals, tabs, filters and audit trails over marketing-style layouts. 5. Make every clickable surface imply a real behavior. 6. Do not expose internal operational complexity to users who should only see safe statuses. 7. Use realistic data density and realistic edge cases. ## Navigation and shell Use a real app shell: navigation appropriate to the roles, page header, account or organization context, notifications, language toggle where relevant, account menu, settings and administration in the right place. Primary navigation: 1. [MAIN AREA] 2. [MAIN AREA] 3. [MAIN AREA] Do not repeat the product name as a large brand row inside every page header. The shell should feel like a daily-use operational product. ## Visual direction Use [YOUR ORGANIZATION'S DESIGN SYSTEM OR REFERENCE PRODUCT]. Treat it as a constraint, not as inspiration. Use: dense operational layouts; near-white app surfaces; soft neutral background; subtle borders; compact spacing; strong readable typography; text near black; accent colors only where they carry meaning; functional status colors; status badges, segmented controls, tabs, drawers, modals, tables, filters and forms. Avoid: landing pages; hero sections; decorative gradients that are not an established pattern; oversized marketing cards; generic analytics dashboards disconnected from action; playful consumer UI; explanatory filler text inside the product UI; one-off components that do not look reusable. ## Core data concepts Represent these naturally in the UI, with their real relationships rather than disconnected cards: - [ENTITY] - [STATUS / STATE MODEL] - [DOCUMENT / REQUEST / CASE / INVOICE / REPORT] - [AUDIT EVENT] - [PERMISSION / VISIBILITY LEVEL] ## Required screens and flows Design a coherent multi-screen prototype. Include the ones this product actually has, each walkable end to end. 1. Authentication and entry: [OTP / email code / passwordless / SSO], loading, invalid code, resend, successful transition. 2. Workbench: what needs attention now — work queues, recent changes, next actions, role-specific content. 3. Primary object directory: dense list or table for [the main entity], with search, filters, counters, row status and next action, primary and secondary actions, empty state, bulk or import/export where relevant. 4. Primary creation or submission flow: a guided modal, drawer or multi-step flow, not one long undifferentiated form. Include validation, missing required fields, back and next, save and resume later, review and submit. 5. Detail workspace: header, status and key metadata, tabs or sections, related records, documents, thread or comments, activity timeline, contextual actions. 6. Requests and communication: list, categories, status and priority, creation flow, detail thread, attachments, linked object, action-required state, resolved state. 7. Documents and records: repository, detail or preview and download behavior, filters, missing-document state, replace or re-upload, access restrictions. 8. Finance, billing or reporting where relevant: overview by period, invoices or ledger, payment status, reconciliation, downloadable documents, exception workflow. 9. Settings and administration: organization settings, users and roles, role descriptions, invite and deactivate, security settings, read-only states for users without permission. ## Interaction states to include Empty; loading; validation errors; missing required fields; pending, approved, rejected, needs information, overdue, resolved; disabled actions with a stated reason; role-restricted content; notifications; audit timeline; download and export; confirmation modals; destructive-action confirmation; success and failure feedback; side panels and drawers; dropdowns and profile menus. ## Privacy, security and visibility rules Respect: - [RULE] - [RULE] Do not expose: - [SENSITIVE DATA] - [INTERNAL NOTES] - [RAW EVIDENCE] If sensitive data is needed to complete a workflow, show the approved role-gated version, a safe status, or a path to request it. ## Content and mock data Language: [English-first / French-first / bilingual / other]. Currency: [currency]. Organizations, people, domain vocabulary, dates and identifiers should look real. Avoid lorem ipsum. Write real product copy. ## Output expectations A polished full-product exploration, not a single screen. Prioritize clear navigation, complete product vision, realistic workflow depth, strong table and list design, reusable patterns, role and privacy logic, real operational actions, and the modals, drawers, dropdowns, tabs, empty and error states the flows need. Someone reading the result should understand what [PRODUCT NAME] becomes as a complete product, and be able to walk each main flow from end to end. ``` **The short instruction layer.** This is what gets typed into the design tool alongside the long specification and the attachments. ```text Design [PRODUCT NAME], [SHORT PRODUCT DESCRIPTION]. Use the attached design system and product documents as source material. Treat the long design prompt as the full specification and this short prompt as the instruction layer. Do not create a landing page or a concept dashboard. Start with the real product experience: [PRIMARY WORK SURFACE], [SECONDARY WORK SURFACE], [DETAIL WORKSPACE], [DEEPEST WORKFLOW]. Design deeply across the product, not only the top-level pages. Include states, variants, drawers, modals, empty, error and loading states, permission-restricted states, audit views, escalation, handoff, and safe output previews where relevant. Each main flow must be walkable end to end. Core UX: - [PRINCIPLE] - [PRINCIPLE] Must include: - [SURFACE / FLOW] - [CRITICAL STATE MODEL] - [ROLE / PERMISSION VARIANTS] Use compact, calm, high-density operational UI. Make it feel production-ready, not like a presentation. ``` **What to attach.** Only sources that should actively constrain the output: the design system or a reference product, the PRD — its strategic framing and product boundary sections included — user research or interview synthesis, workflow deep-dives, entity and state blueprints, and existing screenshots when visual parity matters. Do not attach stale documents unless the prompt says in so many words that they are legacy context and do not decide anything. **The refinement prompt.** Use it when the first output is too shallow, too conceptual or too dashboard-like. ```text Refine this into a denser operational product. Prioritize daily user work over executive analytics. The primary workflow should be obvious on the first screen. Remove any marketing-style hero, oversized explanatory card or decorative section. Increase depth: - make status, owner, next action, date, priority and permission state visible where they matter; - make the main workflow usable end to end, including its intermediate steps and its failures; - add the missing drawers, modals, dropdowns, error, empty and confirmation states; - make history and audit easy to inspect; - make document and request workflows feel functional; - make role-gated and restricted states explicit; - use realistic data and realistic edge cases; - keep the design aligned with the attached design system. ``` ### Never do these - Do not implement a new user-facing feature straight into code without a design pass. Design it first, then integrate. - Do not treat the design tool's export as production architecture. It is what you port from, not what you build on. - Do not send the prototype to be built while the people concerned are still telling you it is not their tool. **Gate 3 — what you have in hand:** a prototype the people concerned recognize as their tool. ## Gate 4 — port the prototype into code ### What you do You start from your organization's approved frontend starter repository and its backend conventions. Not from an empty folder, and not from the prototype's export. The port itself is direct. You give the coding agent the prototype and the starter, and it builds the front inside the starter's conventions. Two things this method deliberately does not ask for: a formal page-by-page rebuild, where each screen is rebuilt and signed off in turn before the next one starts, and a written map from prototype screens to front-end pages. The port from the design tool to the coding agent is close enough that neither is worth the time it costs. What there is instead is back-and-forth. Many of them. You run the front, you put it beside the design, you say what is off, the agent fixes it, you look again. That loop is the work of this gate — looking at the running front next to the design, not rebuilding it screen by screen on paper first. Before every change it makes to the code, the agent goes back to the starter's rules and to the backend conventions. That is the guardrail, and it is what keeps agent-written work inside a shape a developer can review. While the port runs, the backend waits. What you built during Gate 3 stays as it is until the front end is ready; you pick it back up at Gate 5. **Use that wait to ask ahead.** The backend work will need things only other people can give: access to a platform or a console you do not have, a permission, a key, a resource to create, a change that needs their rights. Asked for on the day, each one finds the person busy with something else, and you are blocked for days. So, early in the port, have the agent list them, flow by flow, as requests ready to send, and send them as tickets: the earlier they leave, the less you wait at Gate 5. If you build backend ahead during Gate 3, ask then too: have the agent note in the journal each need that work reveals, send those, and the prompt below takes them in at Gate 4. ### Timing **Under a day to a front end you can click.** With the discovery material already gathered: three to four hours at best, twenty-four at worst, from a folder of sources to a running front end. **About a month to make it true.** Connecting the backend so the end-to-end flows hold in depth is the long part — no method removes it. **And it passes developer review.** The agent works inside your frontend starter and your backend conventions, and re-reads them before every change. These figures are the author's own practice. They are not a study. ### The steps 1. **Clone the approved frontend starter.** Named version, from where your organization publishes it. Clone it beside the folder of sources, not inside it: the folder of sources stays what it is, and the repository is a new folder next to it. Then repoint the session at the repository — from here on that is what the agent works in — and move the working documents into it together, under `docs/`: the PRD, `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md`. All three move at once, and they stay what an agent reads before touching the application. 2. **Open the backend conventions next to it.** The agent needs them before it writes the first API-shaped service, not after. When the backend has code but none are written, first have the agent draft the ones the code already follows, for the backend owner to confirm — see below. 3. **Brief the coding agent once, properly.** Use the prompt below. Hand it the prototype in a form it can actually open: an export, captures of the screens and states, or a reference it can reopen on its own. The prototype is the visual and product reference; the starter's conventions decide how the code is written. 4. **Let it port.** Whole flows, not isolated screens — you already asked the design tool for flows, keep them whole here. 5. **Ask ahead for what the backend will need.** Early in the port, in the same session, once the agent has finished a flow and before you give it the next, run the backend-needs prompt below on the flows Gate 5 will connect, and send each request as a ticket to whoever can act on it. A need should not be heard of for the first time on the day it blocks you. 6. **Run the front end and click it.** Walk the flows the users recognized at Gate 3. 7. **Do the back-and-forths.** Put the running front beside the design and name what is off: spacing, density, state, wording, a missing empty state, an action that does nothing. Fix, rerun, look again. 8. **Have the control session check the port.** Its job here is to confirm that what was built really comes from the design. It reads, it checks, it challenges, and it messages the main session with what it found. It does not change code and it does not decide scope. 9. **Record the port in memory and journal** — what was adapted to the starter's conventions, what was deliberately left different from the design, and why. ### When there is no approved starter and no written conventions Stop. Do not invent them, and do not let the agent invent them either. A convention you made up on the spot is the thing the review will reject later. Ask for them. This is Ops work — the horizontal teams own these services — and what you request is concrete: **From Frontend Ops** - the approved starter repository: its location, its current version, its owner, how to clone and start it, and who maintains it; - the architecture, routing and state conventions; - how components and the design system are meant to be used; - the API client pattern, authentication, error handling and loading states; - accessibility and localization rules; - the checks required on a deployable branch, and the preview or environment path; - who reviews frontend work, and how fast they answer; - an agent-readable version of all of the above, so the coding agent can re-read it before each change. **From Backend and API Ops** - the API catalog with real examples; - authentication and permission rules; - request and response shapes, errors, versioning; - the business meaning of key fields and status values; - reference patterns for auth, migrations and tests; - a test environment with test identities and safe data; - read-only access to logs, errors and health, and who to reach when something breaks; - the procedure for requesting an API that does not exist yet; - who reviews backend work, and how fast they answer; - an agent-readable version of the backend conventions, opening with the recipe for the most common changes, so the coding agent can re-read them before each change. **The backend conventions are what a reviewer will hold the code to**, so ask for them written as criteria a change can be checked against, not as advice — and, for each criterion, how it is checked: by a command that runs, or by a named reviewer. The conventions open with **the recipe**: for each of the most common changes — a new endpoint, a new field — the file to read first, the existing example to copy, and everything else that has to change with it. However the conventions are divided, each part ends with its checklist, and at Gate 5 a change is checked against those checklists, point by point. This method does not say what the conventions should be — that is your organization's decision — only which questions they have to answer, at the least: - where code goes, and how it is layered; - how input is validated where it enters, and how errors, timeouts and retries are handled on the server; - how the data model changes, and how a migration is written so that the version still running keeps working during a deploy and after a rollback; - how an API contract is documented, changed and versioned; - how a request that arrives twice is kept from doing the work twice; - how transactions and concurrent writes are handled; - where work that does not finish inside the request goes, and how it is retried; - how permissions are checked, on writes as well as on reads; - where secrets and configuration live; - what the code must log and measure, and what it must never log; - what response times and load are expected; - how environments and infrastructure are described and changed; - when a new dependency may be added, and who approves it; - which tests a change needs, and at which level; - when a security review is required; - how unfinished work ships switched off, and how a release is rolled back. Besides a rule, two answers count: **not used here, on purpose** — and then the agent must not add it — or **handled elsewhere**, with where, and who owns it. A question left with no answer at all goes back to Backend and API Ops. **When the backend has code but no written conventions,** the conventions often exist anyway: in what the team's tools already enforce, and in the way the last endpoints were written. Ask the agent to describe them with the observed-conventions prompt below. Clone the backend afresh, beside the project repository, from where your organization keeps it — a fresh clone carries nobody's keys, a developer's own copy may — and run the prompt in a mode of your assistant that asks before it runs a command or writes outside the project repository. What comes back is a draft, not the conventions: what the code does is not always what the team wants, and neither you nor the agent can tell a convention from a debt — only the backend owner can. Two files come back in `docs/`: the draft goes to the backend owner to confirm, correct, or mark as debt not to copy; the security notes go to the backend owner alone, never into the channel and never into a commit — delete them from the repository once they have them. Where there is no backend owner, the draft can stand in only as the documented temporary equivalent described below: accepted by the lead accountable for engineering, by name, dated in the journal, which also says that nobody has confirmed it. Until a point is confirmed, it is not a convention: the agent follows what is confirmed and stops on the rest. While the owner reviews it, the port goes on inside the starter; the agent stops only where it needs a backend point that is not confirmed, and says which. Rules kept outside the repository or only in people's heads — a review policy, a contribution process — the agent cannot see, and the owner's review is where they come in. It turns "write us conventions", which a busy team postpones, into a review of what the code already does. Until what you asked for arrives, you can keep the prototype moving and keep gathering what Gate 5 will need. Do not start a foundation you will have to throw away. Use a documented temporary equivalent only when you and the accountable lead explicitly accept the gap — written down, with the gap named and dated in the project journal, so the next person can see what they are looking at and what it stands in for. One thing this gate is not: a handoff. You port the front yourself and you will connect the back yourself at Gate 5. Frontend and backend engineers are horizontal services to your vertical work — they give you the starter, the conventions and the review. The work is not passed to them. ### The prompts and templates it uses **The coding-agent prompt.** ```text You are at Gate 4 of the method: porting the prototype into code. You are implementing [PRODUCT / SLICE]. Read before coding: - the prototype from Gate 3, in the form it was handed to you - the PRD, whose first section is the strategic framing - the approved frontend starter repository and its conventions - the backend conventions - the project memory and journal Product boundary: [WHO THE PRODUCT IS FOR, WHO IT IS NOT FOR, AND WHAT MUST NOT BE BUILT HERE] Rules: - the prototype is the visual and product reference; - the starter repository and its conventions decide how the code is written; - do not paste the design tool's export into the application foundation; - keep routes thin; - put domain logic in feature folders; - use the organization's shared primitives before creating anything new; - route mock data through API-shaped services that match the future backend contracts; - centralize copy and localization; - enforce role and privacy rules at the read-model level; - do not redesign anything unless you are explicitly asked to; - before each change to the code, re-read the starter's rules and the backend conventions. Current task: [THE FLOW, SCREEN OR FIX] Acceptance criteria: - the flow works end to end in the front-end mock; - the result matches the design where the design is non-negotiable; - no privacy regression; - relevant tests added or updated; - project memory and journal updated if this changed product behavior, architecture, a stakeholder decision or future reasoning. Run before finishing: - typecheck - lint - tests - build - click through the flow in a browser Report: - which gate you are at, what you have, what is missing, and what I must decide before you cross; saying what you will do next is not permission to do it, so you cross when I answer, not when you announce - what changed - what you actually ran and what it returned - memory and journal updates made, or explicitly skipped with the reason - remaining open product or backend decisions ``` **Observed backend conventions**, when the backend has code but no written conventions. Give the agent a fresh clone of the backend, beside the project repository, in a mode of your assistant that asks before it runs a command or writes outside the project repository. ```text You are at Gate 4 of the method. The backend has code but no written conventions. Your job is to describe the conventions the code actually follows. You do not decide them. You may read, and only read: [THE BACKEND REPOSITORY]. Do not open, even to read: [ANYTHING IN IT THAT IS OFF LIMITS, or "nothing more"]. Run nothing from the backend repository: no install, build, test, script or migration. Reading the code and its history is enough. Do not change anything in it, and write nothing outside the project repository — not even a helper script. Do not open environment files, key or certificate files, infrastructure state, database dumps or exported data. Answer where secrets and configuration live from the code that loads them, not from the files that hold them. If a value that looks secret appears anyway, give the file and line, never the value. Start from what the team already enforces or wrote down: linter and formatter configuration, CI checks, the pull-request template, the README, contributing notes, architecture decision records, release and upgrade notes. Then read the code. First, the recipe. Take the most common kind of change — usually a new model, field or endpoint — and describe how the code makes one, end to end: the base classes it uses, every file a change of that kind touches, in order, and the one or two existing examples to copy. If there are several common kinds, give a recipe for each. Then answer, at the least, these questions: - where code goes, and how it is layered - how input is validated where it enters, and how errors, timeouts and retries are handled on the server - how the data model changes, and how a migration is written so that the version still running keeps working during a deploy and after a rollback - how an API contract is documented, changed and versioned - how a request that arrives twice is kept from doing the work twice - how transactions and concurrent writes are handled - where work that does not finish inside the request goes, and how it is retried - how permissions are checked, on writes as well as on reads - where secrets and configuration live - what the code logs and measures, and what it avoids logging - what response times and load it is built for, if anything says so - how environments and infrastructure are described and changed - how dependencies are added - which tests exist, and at which level - what security checks exist - how unfinished work ships switched off, and how a release is rolled back For each point, write: - the rule, as one sentence a change can be checked against - one or two real examples: the file and the line - the basis: how many places you looked at, how many follow it, and how you counted — a class counts when any of its bases matches, not only the first - whether it is enforced by a tool, followed without enforcement, or inconsistent — and whether recent and older code differ - "Status: observed". Only the backend owner changes it, to confirmed, corrected, or debt not to copy. Anything the code or the notes mark as deprecated, legacy or scheduled for removal is never a rule: list it under "Deprecated — do not copy", with what replaces it when something does. Put first the questions the backend owner must answer before anyone builds on this: no more than ten, ranked by what they would block. Leave out what the code or the notes already answer. Do not settle them yourself. Write the result in the project repository, never in the backend repository: `docs/backend-conventions.observed.md`. Its first line says: "Observed, not approved — a draft for [THE BACKEND OWNER] to confirm, correct, or mark as debt not to copy." What could be a security weakness does not go in that file, which will circulate: write it to `docs/backend-security-notes.md`, for [THE BACKEND OWNER] only, and say in the draft that such notes exist, without their content. Then stop: what you wrote is not a convention until the backend owner confirms it. Append an entry to the project journal saying what you read and what you wrote, without the content of the security notes. State which gate you are at, what you have, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **Ask ahead for backend needs**, early in the port, on the flows Gate 5 will connect. ```text You are at Gate 4 of the method. While the port runs, the backend waits. Use that time to find out what the backend work will need from people other than me, so that I ask for it now, not on the day I am blocked. Read: - the PRD, its flows, and section 11, the backend and API assumptions - the backend conventions, and the backend code if there is any - what was built ahead during Gate 3, if anything was, and the needs it already raised in the journal - `docs/backend-requests.md`, if it exists - the project memory and journal The flows Gate 5 will connect, in this order: [THE FLOWS, IN THE ORDER YOU WILL CONNECT THEM] What I can already do myself — the platforms, consoles, environments and tools I have access to, and with which rights: [WHAT YOU HAVE ACCESS TO, or "I do not know"] For each flow, in that order, list everything the backend work will need that I cannot do myself: access to a platform or a console; a permission or a role; a key, a secret or a service account; a resource to create, such as a database, a queue, a storage bucket or a domain; a change that needs rights I do not have, such as a migration, a network rule or a setting in a shared environment; a deployment; an account with an outside service; an API that does not exist yet. Section 11 of the PRD already lists what to request from Ops: take in what it lists that nobody has asked for yet, marked as coming from there, so that one list holds every request. Read only. Change no code, the front's or the backend's, and run nothing: no sign-in, no command or request against a platform, an environment or an API, no look at my credentials or at my tools' settings to find out what I can do. Do not open environment, key or certificate files; tell what a secret is for from the code that loads it. Where you cannot tell whether I already have something, mark it "to confirm", and ask me about all of them together, at the end. Write each need as a request ready to send: - what is needed, in one sentence the person can act on: in which environment, and no more access than the work needs - for which flow, and why: what in the PRD, the conventions or the code shows it is needed - when it is needed: the first flow it holds up; I add the date - for how long, if it is not for good - who can do it, if the PRD, the conventions or the memory say so; otherwise "owner to find" - what I can move forward meanwhile, if anything - the ticket: left empty, for me to fill in when I send it Where a key or a secret is needed, ask for it to come the way that team hands secrets over, never in the ticket. Group the requests by who can do them, the earliest needed first. Write them to `docs/backend-requests.md`; if the file exists, add to it and keep what is there, ticket references included. No secret value, there or anywhere else. Send nothing anywhere: I send the requests myself, as tickets, in each team's own tool. Then append an entry to the project journal saying what you listed and what is still to confirm. State which gate you are at, what you have, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **The standing constraint to carry in every coding prompt.** ```text If your work changes product behavior, architecture, a stakeholder decision or future reasoning, update the project memory, the project journal and the PRD. Memory holds the decisions and their trade-offs; the journal holds the chronological record; the PRD describes the product as it now is, so a change that makes one of its sections wrong is a change that edits that section. Do not log small cosmetic changes unless they affect product direction or demo readiness. Before finishing, state whether memory, journal and PRD were updated, or why no update was needed, and state which gate you are at, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` ### Never do these - Do not let the coding agent redesign the UI while porting it. - Do not start a new frontend foundation because the approved starter was hard to find. Ask for it. - Do not accept a green build as evidence that the flow works. Click it. **Gate 4 — what you have in hand:** a front end that runs, that you can click. ## Gate 5 — connect the backend ### What you do You take the front end you can click and connect it to a real backend, flow by flow, until the end-to-end flows hold in depth and not on the surface. **You build that backend yourself, in the session you are already in.** You do not open a second one, and you do not hand the backend to anyone: the Product Builder owns the outcome front and back. What runs in parallel is the backend and the **design** work — not the backend and the port. While the prototype is being iterated in the design tool at Gate 3, there is no front-end code yet, so nothing can collide, and endpoints, data model, authentication and permissions can be built ahead. When the design is done, backend work stops. The port runs at Gate 4 and you leave the backend alone. Only once the front end is ready do you go back to the backend, connect what the front needs, and carry on with it. The connection itself is the longest part of the whole method. A project has one frontend repository and one backend repository. Keep it that way. ### Timing Count **about a month** on average to connect the backend so the flows hold in depth. Two conditions, and only these two: it is the author's own practice, not a study, and it depends on the size of the application. The front end arrives fast; the depth does not, and no method removes that part. ### The steps 1. **Pick the backend back up where the port left it.** What you built while the design was being iterated — endpoints, data model, authentication, permissions — waited untouched through Gate 4. You carry on with it now, in the same session, with the running front end in front of you. Before you connect anything to it, check what was built ahead against the backend conventions, as in step 6: it was written before Gate 4 asked for them. 2. **Replace one service at a time.** The front was built on mock services shaped like the backend contract. Swap them flow by flow, not screen by screen. A flow is what a person does from beginning to end, not the page they are standing on. Before each flow, the agent re-reads `docs/backend-requests.md`, the requests sent at Gate 4. A need nobody has asked for yet goes into it at once, as a request you send the same day; when a flow waits on a request nobody has answered yet, you move to one nothing holds up rather than wait for it. 3. **Go deep on each flow before moving to the next.** The happy path is not the flow. Take the empty state, the error, the slow response, the permission that says no, the record that already exists, the value that arrives malformed. Surface-level connection is what makes a product look finished and behave broken. 4. **Enforce roles and privacy at the read-model level,** not in the component that displays the data. What a person must not see should never reach the browser. 5. **Re-read the rules before every change to the code.** Each time the agent is about to touch the code, it goes back to your frontend starter conventions and your backend conventions. 6. **Check the change against the backend conventions before it goes to review.** Point by point, down their checklists: what it meets, with the evidence — the file, the test, the command and what it returned; what does not apply here, and why; what could not be checked, and why. A point nobody checked is not a point that passed. The list goes with the change, where the reviewer reads it. When a review asks for something the conventions do not say, or do not say clearly, handle it like any other review comment, and take the point to the backend owner — or, where there is none, to the lead accountable for engineering: they decide whether a convention is added or changed, and they write it, so the agent does not make the same mistake twice. You do not edit the conventions yourself. 7. **Call the control session when there are bugs or doubts, and before a change goes to review.** It reads, checks and challenges: does this flow really do what the PRD says, is the failure handled, is the permission real, does the change meet the backend conventions. It does not change the code and it does not decide scope. It returns findings with their evidence, and you decide. The two sessions talk to each other directly: when the control session observes something, it sends the message to the main session itself. The control session section says how that works in the tool you use, and how to check it once before you rely on it. 8. **Write down what you decided, when you decided it.** Decisions, trade-offs and what you now know go to the memory. What changed, why, and what you verified goes to the journal, dated. 9. **Keep the front demoable the whole way through.** Never let the connection work take the product offline for the people waiting to see it. ### The prompts and templates it uses **Connection prompt**, given to the main session for one flow: ```text You are at Gate 5 of the method: connecting the backend. Before coding, read: - the PRD, whose first section is the strategic framing - your frontend starter rules and conventions - your backend conventions - `docs/backend-requests.md`, the requests sent ahead, if there are any; if this flow waits on one nobody has answered yet, stop and tell me, and do not work around it - the project memory and journal Current task: [ONE FLOW, END TO END] Acceptance criteria: - the user-facing flow works end to end against the real backend - empty, loading, error and permission-denied states are handled, and so are the slow response, the record that already exists and the value that arrives malformed - the change meets the backend conventions, checked point by point - no privacy regression - relevant tests are added or updated - project memory and journal are updated if the work changes product behavior, architecture, stakeholder decisions, or future reasoning Run before finishing: - typecheck - lint - tests - build - diff check - the checks the backend conventions name - the slow response, the record that already exists and the malformed value, produced against the API itself, in tests or direct calls, since a browser rarely sends them - walk the connected flow in a browser, end to end, including its empty, error and permission-denied states Report which gate you are at, what is missing, what I must decide before you cross, what changed, what was verified, the backend conventions point by point — met, with its evidence; not applicable, with why; or not checked, with why — any need from another team this flow revealed, written into `docs/backend-requests.md` as a request, and any remaining product or backend decision. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **Control session call**, when a flow misbehaves or you are not sure it is real: give it the flow, the PRD section that defines it, and the running product. Ask it to reproduce, not to fix. For a change going to review, give it the change and the backend conventions, and ask for each point: met, with its evidence; not applicable, with why; or not checked, with why. **Gate 5 — what you have in hand:** the flows hold in depth. ## Gate 6 — test, then ship ### What you do You put the product in real hands while the connection work is still going on, you fix what comes back, and then you ship with the leads of the trades concerned. Testing is not a stage at the end. It runs alongside Gate 5 and it is your pilot: it tells you the flows hold and that the product was designed right. Waiting until everything is connected to let anyone touch it is how you find out too late that the tool was not the one they needed. ### The steps 1. **Give access while the connection work is still going on.** Demo accounts while authentication is not connected, real accounts once it is, sent to the people who should test. 2. **Share the life of the product in the project channel.** What just got connected, what is now clickable, what broke, what you decided. 3. **Fix what comes back, as it comes back.** As long as you handle defects as they appear, they need no labels. 4. **Start classifying only when there are more defects than a session can hold.** That is the moment you are tracking them instead of fixing them, and P0, P1 and P2 start earning their keep. 5. **Walk the delivery path.** Local, then the repository, then staging. 6. **Prepare the release with the prompt below,** and take the go-ahead with the leads of the trades concerned — engineering, backend, frontend, data. 7. **Ship.** The freeze applies in one case only: an MVP that has to go to production, where what is in the release stops moving until it is out. 8. **Record the release in the journal** and keep going: the front stays demoable and the build continues. ### How you give access It depends on where the backend is. - **Authentication not connected yet** — create demo accounts and send them to the people who should test. They click through what exists. - **Authentication connected** — create real accounts for the people concerned and send them. ### What you share in the channel The project channel was created at Gate 0, with everyone concerned in it, business people included. While they test, that is where the life of the product is shared: what just got connected, what is now clickable, what broke, what you decided. ### Severities, and when they start Defects that come back get a severity once you are tracking them rather than fixing them straight away. The trigger is simple. As long as you handle defects as they appear, the labels add nothing: you fix the thing and move on. The moment there are more of them than a session's worth to hold in your head, you are tracking a list instead of clearing it — and that is where the classification earns its keep, because it is what lets you say what is being fixed now and what is waiting. Plain meanings, at first use: **P0**, blocking; **P1**, important; **P2**, minor. ### The delivery path Local, then the repository, then staging. From staging to production the step is not taken alone: the leads of the trades concerned — engineering, backend, frontend, data — check that everything is in order before shipping. Treat it as a go-ahead, not as an approval board. It is short, it is about whether the thing is in order, and it is where the vertical work goes back through the horizontal Ops services that supported it: the people who own the frontend conventions, the backend conventions, the data and the delivery path confirm that what you built sits inside them. It is also the honest answer to the objection this way of working attracts — one person shipping to production what an agent wrote. The answer is that it is read by the trades before it goes out. ### When there is no staging, no delivery path and no reviewing leads Ask for them, the same way you asked at Gate 3 and Gate 4, with a named owner and a named artifact: the path from local to the repository to staging to production, the checks that run along the way, a way to see which revision is live, and the people who give the go-ahead before production. Meanwhile, the honest answer is a small one, and you say it out loud rather than dressing it up: you ship what you can verify yourself — the flows you walked end to end, the empty, error and permission-denied states you exercised, the checks you ran and what they returned — and you write in the journal, dated, which review did not take place and who was not there to give it. Nobody should have to reconstruct later what was read before it went out, and the gap you recorded is the request you make again next time. ### The one case where things are deliberately frozen An MVP that has to go to production. There, what is in the release stops moving: you fix what is in it, you do not add to it, until it is out. That freeze belongs to that moment, not to the method as a whole. Everywhere else the product keeps moving. ### After shipping The front stays demoable and keeps evolving. Shipping is not the end of the sequence; the build is continuous. You go back into flows, deepen them, connect what was left, and show it again in the channel. Record the release in the journal, using the journal entry format from Gate 0. ### The prompts and templates it uses **The release prompt.** Run it in the main session once staging holds what you intend to ship. ```text You are at Gate 6 of the method: test, then ship. Read before you write anything: - the PRD, whose first section is the strategic framing - the project memory and the project journal - what changed in the repository since the last release Prepare the release note for the leads of the trades concerned — engineering, backend, frontend, data. State these, and invent none of them: - what is in this release, flow by flow; - what has been tested, by whom, and with which accounts — demo accounts or real ones; - what was verified and how: the flows walked end to end, the empty, error and permission-denied states exercised, the checks that were run and what they returned; - what is known to be broken or unfinished, and where it is being tracked; - what the leads are being asked to give the go-ahead on; - which review did not take place, if one could not, and who was not there to give it. If something was not tested, say it was not tested. A gap named is the request I make next time. Do not send anything anywhere — no service, no channel, no address. Before you finish, state which gate you are at, what you have, what is missing, and what I must decide before this goes to production. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` **Gate 6 — what you have in hand:** accounts in real hands, then production. ## The control session The control session is not a gate. It runs alongside them, from the discovery to the backend, and it is the one practice the author calls their safety harness. You work in two sessions, side by side. The main session is the one you are in; it is where the building happens. The second session has one job: to challenge the first. It is not a review stage bolted on at the end — it is open the whole time and you call it in wherever doubt sits. ### Where you call it in - **At Gate 1**, it challenges the discovery findings of the main session: what the main session concluded, checked against the material it actually read. - **At Gate 2**, it can challenge the PRD, its strategic framing section as much as the rest — not only whether the PRD is coherent, but whether the direction holds. - **At Gate 3, before the specification is sent**, it checks the brief against the PRD: every demand traced back to it, nothing in the brief the PRD does not support, nothing the PRD requires left out. This is the cheapest place to catch an invention, because everything after it is built on the brief. - **After Gate 4**, it checks that what was built really comes from the design. - **During Gate 5**, you relaunch it on backend bugs and on doubts: a flow that behaves oddly, a result you do not believe. And before a backend change goes to review, it checks the change against the backend conventions, point by point, with the evidence for each. ### The rule Write these limits into the control session at its first prompt, and repeat them when it strays. - It reads, checks and challenges. - It does not change code. - It does not decide scope. - It does not write the PRD and it does not write the prompts. - It returns findings with their evidence, and the Product Builder decides. That last line is the whole point. The control session produces findings, never decisions. ### The two sessions talk to each other When the control session observes something, that finding reaches the main session whole, with its evidence, and you decide what the main session does with it. **The sessions do that themselves, and the instruction is what makes them do it.** You tell the main session where the work stands and to ask the other session for its report and for its answer back. The control session addresses the main session directly, and what is left for you is the part that needs you: reading the reports and deciding. You are not a courier between two windows. In the author's own practice there is nothing to configure for this — assistants that run several sessions on the same machine can address one another, and the instruction in the prompt is the whole of the wiring. **In Claude Code this works, and it has been watched working.** Sessions running on the same machine can list one another and address one another by the name each carries in the sidebar. The control session names the main session in the last bracket of its starting prompt, and its finding arrives there as a turn, unprompted and without you carrying it. Two conditions, both of them real: **both sessions have to be open**, because a message sent to a closed session goes nowhere; and a session running in a different permission mode may hold the message until you approve it, so a finding that seems not to have arrived is worth looking for in the other window before you conclude anything. Check it once before you rely on it: ask for a small, harmless finding and watch it arrive. In Codex, sessions carry an ID and the same shape should hold, but this kit has not watched it land, so treat it as untested until you have. Where a tool cannot carry a message, or where you cannot tell whether one landed, you relay it yourself — paste the finding across unchanged and say where it came from. That is the fallback, not the method. ### The drift, and what prevents it A control session with no written limits slides into becoming the PM session. It starts deciding what is in scope, rewriting parts of the PRD, writing the prompts for the main session — and then you have two building sessions and no harness. The author has seen this happen in their own practice and puts it down to discipline rather than to the design of the practice. The rule above is what prevents it: the limits are written down, they are part of the control session's starting prompt, and you restate them the moment the session starts proposing instead of reporting. Two sessions, and only two: one main session and one control session. Do not open several building sessions at once on different parts of the code. Their scopes overlap, and what comes out of that is bugs. ### Starting prompt for a control session Works in any tool. Fill the brackets and keep the rules block unchanged between runs. ```text You are the control session for [PRODUCT]. The work is at [GATE]. Your job is to read, check and challenge the work of the main session. Do not trust its claims. Check them against the material. Read what exists at this gate, and nothing that does not: - the discovery material in the project folder, and `DISCOVERY.md` once Gate 1 has written it - the project memory and the project journal - from Gate 2 onward, the PRD, whose first section is the strategic framing, and the product decisions - from Gate 3 onward, the design the front end is ported from - from Gate 4 onward, the repository, the frontend starter's rules and the backend conventions Tell me what you read, and what did not exist yet at this gate. What I am asking you to check now: [ONE AREA: the discovery findings / the PRD / its strategic framing / the design specification before it is sent / what was ported from the design / a backend flow / a backend change against the backend conventions / a bug] Rules, which do not change between runs: - you read, check and challenge - you do not change code - you do not decide scope - you do not write the PRD and you do not write the prompts - you return findings with their evidence, and I decide Return: - which gate the work is at, what it has, what is missing, and what I must decide before it crosses - each finding with the evidence it rests on: the file, the screen, the flow, the section of the PRD, the steps that reproduce it - what you could not check, and why - product decisions separated from defects - [once defects are being tracked rather than fixed as they appear, mark each finding P0, P1 or P2] When you observe something, send it to the main session as well as to me: [the name of the main session, as your assistant lists the sessions running beside it — in Claude Code, the name that session carries in the sidebar. If you cannot reach it, hand the finding to me and I will relay it unchanged] ``` What goes in that last bracket is how this session addresses the main session in the tool you work in — for most assistants, the main session's name or its identifier, which the tool itself can list. Fill it, then check it once with a small finding and watch it land. Only where a tool cannot do it, or where you cannot tell whether the message arrived, does the bracket fall back to handing the finding to you so that you relay it unchanged. What does not change either way: the finding arrives whole, and you decide what happens next. ## The standing guardrail Before the agent changes code, it goes back to the organization's frontend starter and to the backend conventions. It re-reads them, and they frame how it reasons before it writes anything. Not once at the start of the project — every time it is about to touch the application. This is what makes the work reviewable. The code is generated, and it still goes to developers for review, and it passes, because it was produced inside the organization's own standards instead of alongside them. ### What the agent keeps current The same constraint carries the upkeep, because the moment to record a change is the moment it is made, not later: the project memory, the project journal, and the PRD. The first two start at Gate 0 and the PRD at Gate 2, and from there the PRD describes the product as it now is rather than as it was first written. A change that makes one of its sections wrong is a change that edits that section, in the same pass as the code. Without that, the product and its PRD drift apart, and at the end of the build you hold a document that describes something you did not ship — which is the state the method exists to avoid. What this does not ask for is a rewrite on every commit: a cosmetic change logs nothing, and a change that alters what the product does edits the section it contradicts. ### The agent states its gate The other half of the guardrail: the session says where it is before it goes further — which gate it is at, what it has in hand, what is missing, and what you must decide before it crosses. Ask for it at every gate, and treat a session that cannot answer as a session that has left the method. ### Read before coding - the prototype from Gate 3, in the form it was handed to you; - the PRD, whose first section is the strategic framing; - the organization's frontend starter and its written conventions; - the backend conventions; - the project memory and the project journal; - the QA contract carried in the PRD. ### What every code-generating prompt restates Do not assume the agent still holds this from earlier in the session. Put it in the prompt each time: - the organization's frontend starter is the technical reference; - the prototype is only the visual and product reference; - routes stay thin; - domain code belongs in feature folders; - shared UI uses the design system's existing primitives first; - copy is centralized, not written into each page; - mock data goes through services shaped like the future API; - role and privacy rules are enforced at the read-model level; - no one-off redesign and no new component system without explicit approval; - do not paste the design-tool export into the application as its foundation; - state which gate you are at, what is missing, and what I must decide before you cross. ### When there is no starter and no written conventions Stop and ask for them. This is a request to Frontend Ops or to the backend owners, not a problem to solve by yourself in the repository: every convention you invent locally is something a reviewer will have to undo. What to ask for, and what to do while you wait, is at Gate 4. ## Continuous learning The research does not stop when the building starts. While the front is going up or the backend is being connected, you keep learning about the business, the users and what they need — from the people who will use the tool, from the channels where the work is discussed, from what comes back the moment someone clicks something real. When that learning says the product should change, you change it, at whatever gate the work is at. You do not park it until the next project. **It refines, it does not pile up.** What you learn makes what you are building more precise; it does not make it longer. A finding that adds a screen is rarer than a finding that corrects one, and the second is worth more. Treat what arrives as a correction to what exists before treating it as a new thing to build, and let the PRD and the memory carry what it changed. **It stays light.** Gathering from users is a habit, not a machine. If keeping it running takes more work than what it returns, it has stopped being research and started being reporting. **How it reaches you.** The Gate 1 prompt is the mechanism: you point an agent at a channel, a mailbox or a thread, by name, and what comes back is input rather than a decision. You can ask again at any gate — an insight that arrives while you are connecting the backend is still worth having. The privacy rules at Gate 1 hold every time you ask: ask before reading, say what was read, keep personal details out of what is written down. ## What Ops owes a Product Builder You own the outcome vertically. Design, Frontend, Backend and API, Data, access, delivery and review are horizontal: services supplied to you, and to everyone else doing the same job. For this method to run, those services have to supply: - **a frontend starter with the conventions encoded in it** — app shell, routes, feature folders, shared components and primitives, domain types, API-shaped services, copy and localization files, tests — so that you make no architecture decision while you build; - **a backend foundation with precedents to copy**: authentication, permissions, request and error shapes, migrations, a test environment with safe data, and a written way to ask for an API that does not exist yet — and **backend conventions written as criteria a change can be checked against**, opening with the recipe for the most common changes, in a version an agent can re-read, with a named reviewer and an owner who keeps them up to date with what reviews find (Gate 4 lists the questions they answer); - **a data service**: where the reference data lives, the business meaning of key fields and status values, a test dataset that is safe to use, and the rules on what may be exported, by whom and to where; - **a design system** that both the prototype and the front end draw on, so that what the design tool produces and what the code produces are the same thing; - **access paths**: a written request route, an approver, a least-privilege default, a response target, and an owner for expiry and rotation; - **staging and delivery**: a path from local, to the repository, to staging, to production, with the checks that run along the way and a way to see which revision is live; - **review**: developers who read the generated code, and the leads of the trades concerned who give the go-ahead before production. Each of these has a named owner you can reach. "Ask someone" is not a route. ### The optional self-check The self-check is the list above, read as a list of what you have and what you do not. It is optional. There is no score, no threshold, and nothing in it stops you from starting at Gate 0 — you can run it on the first day, in the middle of the build, or never. Go down the seven lines. For each one, try to name the artifact and the person. Every line you cannot name is a single thing to ask a named Ops owner for. That is its only purpose: to turn "this is harder than it should be" into a request with a name on it. Why it exists: if your organization already supplies all of the above, you do not need it. You will read the list, recognize everything, and move on. If you are starting without those services, you will hit exactly the problems the services were built to remove — an architecture you had to invent yourself, access you cannot obtain, a front end nobody has agreed to review, no path to staging. The list lets you see them coming and ask early, instead of discovering them one at a time in the middle of a build. Text licensed CC BY 4.0. Code MIT. # Começar um caso Rota: /pt/resources/first-case · Markdown: /pt/resources/first-case.md Comece hoje o seu próprio projeto: uma pasta, uma sessão aberta nela, o primeiro prompt e os marcos que vêm depois. Comece com o seu próprio projeto, não com um exercício. Um resultado pelo qual você é responsável, uma pasta com tudo de que ele precisa, uma sessão aberta nessa pasta e o prompt abaixo. Todo o resto é a sequência de marcos, na ordem. ## O seu projeto Formule em uma frase o resultado pelo qual você é responsável: para quem é, qual problema, qual resultado. Você o leva na vertical, front e back, do discovery até a produção. Design, Frontend, Backend e API, Data, os acessos, a entrega e a revisão são serviços horizontais em que você se apoia, não pessoas para quem você passa o resultado. ### O que vai na pasta Tudo de que o projeto precisa vai em uma única pasta criada para ele, em vez de ficar espalhado entre discos, caixas de e-mail e abas. 1. **Baixe a pasta do projeto e dê a ela o nome do seu projeto.** Ela contém os quatro arquivos com que você trabalha, vazios e prontos, e o próprio método: a skill já vem instalada para o Claude Code e para o Codex, então não há nada para configurar. Coloque-a onde você guarda o seu trabalho — não em uma pasta que sincroniza sozinha com a nuvem. [Baixar a pasta do projeto](/downloads/onirion-project.zip) 2. **Coloque na pasta `sources/` todos os documentos que o projeto já tem** — o que foi escrito antes, o que foi recebido, o que você reuniu por conta própria, seja qual for o formato. Você não converte nada: o primeiro prompt converte o que pode e diz o que não conseguiu. Se um assistente já tem material de um trabalho anterior, peça a ele que copie esses arquivos para a pasta antes de qualquer outra coisa: o que está no diretório temporário de uma sessão morre com a sessão, e o que um assistente apenas lembra não é de forma alguma uma fonte enquanto não estiver escrito na pasta. 3. **Abra um canal para o projeto no mesmo dia** — não um arquivo, e não é opcional: todas as pessoas envolvidas com o produto estão nele, incluindo o pessoal de negócio. 4. **Abra a sessão de controle junto com a primeira.** Uma segunda sessão na mesma pasta, com o [prompt da sessão de controle](/pt/resources/prompt-control-session) colado nela e o nome da primeira sessão no último colchete do prompt. O único trabalho dela é questionar a primeira. Abri-la agora é justamente o que importa: deixada para depois, ela nunca chega a ser aberta, e um desvio só é percebido no dia em que, por acaso, você pergunta. **Os três arquivos, e por que eles não são fontes.** `PROJECT_MEMORY.md` é a camada de raciocínio: onde o produto está hoje, as decisões e seus trade-offs, e qual fonte prevalece quando as fontes divergem. `PROJECT_JOURNAL.md` é o registro cronológico: datado, ao qual só se acrescenta, nunca reescrito, incluindo o que se revelou um erro. `prd-template.md` é o modelo que o marco 2 preenche e que todos os marcos seguintes leem. O primeiro prompt deixa os três fora do que inventaria: eles são os registros do próprio projeto, não material. [Entrada de memória](/pt/resources/memory-entry) · [Entrada de diário](/pt/resources/journal-entry) · [Modelo de PRD](/pt/resources/prd-template) Criá-los à mão também funciona — dois arquivos vazios e o [modelo de PRD](/pt/resources/prd-template) salvo ao lado deles — desde que existam antes que o primeiro prompt rode, e não quando você se lembrar. O que você não teria assim é a skill, que vai dentro da pasta. ### Abrir a sessão na pasta Abra a sessão ou o projeto do seu assistente nessa pasta. Neste ponto, ela não é um repositório: não há aplicativo, nada para compilar, nada para rodar. É uma pasta de fontes, e isso basta para começar. O repositório chega no marco 4, quando você clona o starter de frontend da sua organização ao lado da pasta e move para ele o PRD, a memória e o diário, em `docs/`. ### O primeiro prompt - Onde colar: Uma nova sessão do seu assistente de código, aberta na pasta do projeto. O prompt é autossuficiente: nada para anexar, nada para ir buscar. - Com a skill: A pasta baixada já a traz, para o [Claude Code](/pt/resources/claude-code-skill) e para o [Codex](/pt/resources/codex-skill). Peça com as suas palavras — “Aplique o método Onirion a esta pasta” —, o que funciona em todas as versões; `/onirion` e `$onirion` são atalhos onde a versão os oferece. ```text Você está no marco 0 do método: montar um novo projeto de produto. A pasta do projeto é aquela em que esta sessão está aberta. Trabalhe somente dentro dela. Faça isto, e nada mais: 1. Percorra `sources/` e a raiz da pasta do projeto, e liste todos os arquivos que encontrar. Ignore as ferramentas do próprio assistente — qualquer pasta que comece com um ponto, como `.claude/`, `.agents/` ou `.git/`, e tudo o que houver dentro dela. Ignore também os registros do próprio projeto — `PROJECT_MEMORY.md`, `PROJECT_JOURNAL.md`, `prd-template.md`, `START-HERE.md` e `sources/README.md`. Nenhum deles é uma fonte. 2. Tudo o que for uma fonte fica em `sources/`. Uma fonte que esteja na raiz da pasta do projeto é movida para lá, sem alterações e sem ser renomeada; esse é o único movimento que você pode fazer. Depois converta para Markdown tudo o que puder converter, na subpasta `converted/`. Nunca modifique, renomeie nem sobrescreva um original. 3. Escreva `converted/INDEX.md`: uma linha por fonte, com o nome do arquivo, o que ele é e de quando ele é. Se não conseguir datá-lo, diga isso. 4. Liste tudo o que não conseguiu ler ou não conseguiu converter, e por quê. 5. Acrescente uma entrada datada a `PROJECT_JOURNAL.md`: o que você converteu, o que não conseguiu ler e onde estão os arquivos convertidos. Não analise o conteúdo. Não tire conclusões. Não escreva um PRD. Não envie nada para lugar nenhum — nenhum serviço, nenhum canal, nenhum endereço. Devolva o índice, a lista do que não conseguiu ler e onde colocou os arquivos convertidos. Antes de terminar, diga em que marco você está, o que tem, o que falta e o que eu preciso decidir antes que você passe para o próximo marco. Dizer o que vai fazer em seguida não é permissão para fazer: você passa quando eu respondo, não quando anuncia. ``` **O que o assistente deve responder.** O índice, o que não conseguiu ler, onde colocou os arquivos convertidos e em que ponto está o trabalho: ```text Marco 0, montagem da pasta do projeto. O que eu tenho: todos os arquivos da pasta percorridos e listados. O que podia ser convertido está em `converted/`, com uma linha por fonte em `converted/INDEX.md` — o nome do arquivo, o que ele é e de quando ele é, ou “sem data” quando o arquivo não traz nenhuma. Nenhum original foi modificado, movido, renomeado nem sobrescrito, e uma entrada datada foi acrescentada a `PROJECT_JOURNAL.md`. O que eu não consegui ler: os PDFs digitalizados sem camada de texto e uma planilha protegida por senha. O que falta: três arquivos não trazem nenhuma data que eu tenha conseguido estabelecer, então o índice os marca como sem data. Não interpretei nada do conteúdo. O que você precisa decidir antes que eu passe para o marco 1: se a exportação antiga do backlog é material para o discovery ou histórico a deixar de lado. ``` Ele não interpreta nada e não envia nada para lugar nenhum. Leia o índice que ele devolve e a lista do que não conseguiu ler, e preencha agora as lacunas óbvias, enquanto isso sai barato. O prompt tem a sua própria página: [Inventariar e converter](/pt/resources/prompt-inventory). ## Depois, marco a marco O marco 0 deixa você com tudo em uma única pasta, convertido e inventariado. O que vem depois é um marco de cada vez, cada um com o prompt que usa, e cada prompt termina pedindo à sessão que diga em que ponto está o trabalho. - **Marco 1 · Reunir o discovery** — O que se sabe, o que falta e o que se contradiz, escrito em `DISCOVERY.md` para que o marco seguinte possa abri-lo pelo nome. [Ler os canais](/pt/resources/prompt-channel-reading) - **Marco 2 · Escrever o PRD** — Um único documento, cuja primeira seção é o enquadramento estratégico, refinado e alinhado com o negócio, incluindo as partes técnicas. [Analisar e escrever o PRD](/pt/resources/prompt-prd) · [Modelo de PRD](/pt/resources/prd-template) - **Marco 3 · Prototipar os fluxos de ponta a ponta** — A sua sessão assume o papel de PM e pede à ferramenta de design fluxos inteiros, e você itera até que as pessoas envolvidas digam que é a ferramenta delas. [Prompt de design — especificação](/pt/resources/prompt-design-specification) · [Camada de instrução](/pt/resources/prompt-design-instruction) · [Prompt de refinamento](/pt/resources/prompt-refinement) - **Marco 4 · Levar o protótipo para o código** — Dentro do starter de frontend da sua organização, com o front rodando ao lado do design e quantas idas e vindas forem necessárias. [Levar o protótipo para o código](/pt/resources/prompt-port) · [Sem convenções de backend escritas](/pt/resources/prompt-observed-conventions) · [Antecipar as necessidades de backend](/pt/resources/prompt-backend-requests) - **Marco 5 · Conectar o backend** — O marco mais longo: fluxo a fluxo, em profundidade, incluindo o estado vazio, o erro, a resposta lenta e a permissão que diz não, com cada mudança confrontada com as convenções de backend antes da revisão. [Conectar o backend](/pt/resources/prompt-connect) - **Marco 6 · Testar e depois lançar** — Contas em mãos reais enquanto o trabalho de conexão ainda está em andamento, depois o sinal verde dos leads das áreas envolvidas. [Preparar a entrada em produção](/pt/resources/prompt-release) *Figura — mapa dos marcos: os marcos 0 a 6 em linha, com os marcos 0 a 6 dentro do escopo.* O seu próprio projeto percorre a sequência inteira: o marco 0 nesta página, os marcos 1 a 6 no guia principal, com o que cada um exige e os prompts que usa. [Ler os marcos por completo →](/pt/resources/method-guide) De uma pasta com o material de discovery reunido até um front em que você pode clicar: de três a quatro horas no melhor dos casos e vinte e quatro no pior, quando o discovery já foi parcialmente reunido. Depois, cerca de um mês para conectar o backend de modo que os fluxos se sustentem em profundidade, conforme o tamanho da aplicação. O código ainda passa pela revisão dos desenvolvedores, e é aprovado, porque o agente trabalha dentro do starter e das convenções da sua organização. Esses números vêm da prática do próprio autor, não de um estudo. ### O que atravessa todos eles - **A sessão de controle** — Uma segunda sessão cujo único trabalho é questionar a primeira, aberta do discovery até o backend. Ela lê, verifica e questiona; não muda código, não decide o escopo e devolve constatações com suas evidências. Quem decide é você. [Sessão de controle](/pt/resources/prompt-control-session) - **A salvaguarda permanente** — Antes de cada mudança no código, o agente volta ao seu starter de frontend e às suas convenções de backend e os relê. É isso que mantém o trabalho gerado dentro de uma forma que um desenvolvedor consegue revisar. [Restrição permanente](/pt/resources/prompt-standing-constraint) - **O aprendizado contínuo** — A pesquisa não para quando a construção começa. Enquanto o front ganha forma ou o backend é conectado, você continua aprendendo sobre o negócio, os usuários e aquilo de que eles precisam; e quando esse aprendizado diz que o produto deveria mudar, você o muda, no marco em que estiver. Ele refina o que já existe: deixa mais preciso o que você está construindo, não mais longo. E continua leve — colher o que os usuários dizem é um hábito, não uma engrenagem. [Ler os canais](/pt/resources/prompt-channel-reading) ## Quando os serviços ainda não existem Parte daquilo em que o método se apoia cabe a Ops, e não a você: o design system no marco 3, o starter de frontend e as convenções de backend no marco 4, o caminho até staging e os leads que revisam no marco 6. Se a sua organização não tem nenhum deles, não os invente, e também não deixe o agente inventá-los — uma convenção inventada na hora é o que a revisão vai desfazer depois. Solicite-os, com um responsável designado e um artefato nomeado. - **Sem design system** — Peça a Design Ops os componentes e seus estados, os tokens, as regras de uso, o que pode e o que não pode ser estendido, e quem o mantém. Até que ele chegue, nomeie um produto existente que a sua organização já aceite e projete tomando-o como restrição, não como inspiração: o protótipo e o front precisam continuar se apoiando na mesma referência. - **Sem starter de frontend aprovado** — Peça a Frontend Ops o repositório starter com a localização, a versão e o responsável dele; as convenções de arquitetura, roteamento e estado; como os componentes devem ser usados; o padrão de cliente de API, a autenticação, os erros e os estados de carregamento; as verificações exigidas em uma branch implantável e o caminho de pré-visualização; quem revisa o trabalho de frontend; e uma versão de tudo isso que um agente consiga ler. - **Sem convenções de backend escritas** — Peça a Backend e API Ops o catálogo de APIs com exemplos reais; as regras de autenticação e de permissões; o formato das requisições e das respostas, os erros e o versionamento; o significado de negócio dos campos-chave e dos valores de status; um ambiente de testes com identidades de teste e dados que podem ser usados sem risco; o procedimento para pedir uma API que ainda não existe; quem revisa o trabalho de backend; e as próprias convenções de backend, escritas como critérios com os quais uma mudança pode ser confrontada, começando pela receita para as mudanças mais comuns (o arquivo a ler, o exemplo a copiar, o que mais precisa mudar junto), em uma versão que um agente consiga reler. Se o backend já tem código, no marco 4 peça ao agente que rascunhe as convenções que esse código já segue, para que o responsável pelo backend as confirme. [Convenções de backend observadas](/pt/resources/prompt-observed-conventions) **Enquanto você espera** #### O método continua funcionando. O marco 0 não pede nenhum deles, e o discovery e o PRD também não. Você mantém o protótipo andando e continua reunindo aquilo de que os marcos seguintes vão precisar. O que você não faz é começar uma fundação que vai ter que jogar fora. Onde usar um equivalente temporário documentado, valide a lacuna com o lead responsável e anote-a no diário, com data: o que faltava, o que você fez no lugar e quem concordou. A lacuna que você registrou é o pedido que você faz de novo da próxima vez. *Figura — imagem, 16:10: O sandbox incluído, rodando em um notebook: duas identidades, um rascunho e um botão que faz o salvamento falhar.* ## Praticar com um caso fictício (opcional) Se você prefere percorrer os marcos uma vez com algo de que ninguém depende, o método traz um caso de prática: um pequeno aplicativo local com duas identidades, um interruptor que faz o salvamento falhar e testes de aceitação que falham antes que você implemente. Ele roda na sua máquina, sem nada para instalar e sem conta. Alguém escreve uma atualização de projeto, seleciona “Save draft”, sai da página e, ao voltar, descobre que o texto sumiu. Essa reclamação é material inventado para o exercício: não é pesquisa, não é um usuário real, e nada aqui pede que você a trate como evidência. O resultado pelo qual você é responsável: quem escreve consegue voltar ao texto que confirmou, e a segunda identidade não consegue lê-lo. 1. Depois que um salvamento confirma que deu certo, quem escreve pode recarregar a página, ou sair e entrar de novo, e encontrar esse texto outra vez. 2. A segunda identidade não consegue ler o rascunho, nem na página nem pela rota de leitura direta do rascunho. 3. Um salvamento que falha mantém o texto editado visível, mostra um erro e a opção de tentar de novo, nunca diz que deu certo, e um recarregamento antes de uma nova tentativa bem-sucedida traz de volta apenas o último texto confirmado. O roteiro abaixo diz qual prompt rodar em qual marco, o que você deveria ter em mãos quando cada um se fecha, e onde anotar os serviços que o sandbox não pode lhe dar — um starter, convenções de backend, um design system, um caminho até staging e os leads que dão o sinal verde. Nada do que é necessário para esta execução está reservado ao treinamento. *O texto a seguir é o do kit, em inglês.* # Onirion · first case worksheet **A method by Alexis Boyer · version 4.0 · September 22, 2026** Run the method once, end to end, on a case nobody depends on. The application is the one shipped beside this file, at [sandbox/](/pt/resources/sandbox). You walk the seven gates in order and fill the blocks as you go. The prompts are in the [core guide](/pt/resources/method-guide); this worksheet says which one to run where, and what you should be holding when the gate closes. The complaint that starts this case is a made-up exercise input. It is not research, it is not a real user, and nothing here asks you to treat it as evidence. Wherever the method asks what a source establishes, the honest answer on this case is: a fixture written for practice. ## The case Someone writes a project update, selects **Save draft**, leaves the page, and finds the text gone on return. The outcome you own: **the author can come back to the text they confirmed, and the second identity cannot read it** — not in the page, and not through the direct read route. What the sandbox already carries, and you can check yourself: - two identities, chosen at `/as/author` and `/as/reviewer` and held in a local cookie; - one confirmed draft, `fictional-draft-001`, owned by the author identity; - `POST /save` for the form, `GET /api/drafts/fictional-draft-001` for the direct read; - a **Simulate failed save** button that sends `simulate_failure=1`, so the failure is reproducible with nothing external; - three deliberate defects: the save does not persist, the direct read answers the second identity, and the failure is swallowed and reported as success; - three acceptance tests written against the intended behaviour, which fail before you implement. Outside this case: deletion, expiry, two people editing at once, offline saving, real authentication. ## Run the sandbox before you start - Python 3.9 or newer. Nothing to install, no account, no network. - From `sandbox/`: `python3 app.py`, then open `http://127.0.0.1:8766/`. - Acceptance checks: `python3 -m unittest -v test_acceptance.py`. Expect three failures. Three *errors* instead mean the environment stopped the tests binding their local server on `127.0.0.1`. - In Codex, the default `workspace-write` sandbox blocks that local server. Allow network access for the session — `codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true` — or run the test command yourself outside the sandbox. - The server binds to `127.0.0.1` only and writes `sandbox.sqlite3` beside the app. Delete that file to reset your manual run; the tests use a temporary database. - The identity switcher is a cookie, not authentication. Never deploy this server. Never put real data in it. ## Open your assistant on the case folder Ask for the method by name on the case — "Apply the Onirion method to this folder" — in [Claude Code](/pt/resources/claude-code-skill#adapter) or in [Codex](/pt/resources/codex-skill#adapter); `/onirion` and `$onirion` are shortcuts where the version offers them. Whatever you use, ask for the gate statement every time, as the guardrail says: which gate it is at, what it has, what is missing, what you must decide before it crosses. ## What the sandbox cannot give you Five things the method asks for are not here: an approved frontend starter, written backend conventions, a design system, a path to staging, and leads who give the go-ahead before production. At each of those points this worksheet stops and has you write down the service that is missing and who you would ask. Do not invent another organization's standards, and do not let the assistant invent them either. Here you keep going inside the shape the sandbox already has, with the gap written down. Copy this block each time the worksheet asks for it: ```md Service missing here: What I would ask for, concretely: Who I would ask (the role, not "someone"): What I did instead on this run, and with whose agreement: Date recorded in the journal: ``` ## The three things that run across the gates ```md Control session — opened in: How it reaches the main session here: If it cannot reach it: I relay the finding unchanged and say where it came from. Limits written into its first prompt: it reads, checks, challenges; it does not change code; it does not decide scope; it does not write the PRD or the prompts; it returns findings with evidence and I decide. ``` ```md Standing guardrail — what the agent re-reads before every change to the code: What is missing from that list on this run: The gate statement is asked for at every gate: yes / not yet ``` ```md Continuous learning — on this case there are no users and no channel, so what stands in for them: What I learned after the build started that I did not know at Gate 2: What it corrected in what already existed, rather than added: Where I wrote that down (PRD section, memory entry): ``` ## Gate 0 — set up the project folder **What you do.** Download the project folder and rename it for this case; the memory, the journal and the PRD template are already in it. Put the sandbox's three files into its `sources/` folder — the README, `app.py` and `test_acceptance.py` — because on this case the code is material to read, not yet an application to change. Write the made-up complaint into `sources/` too, in your own words, so the material is in the folder rather than on this page. Then run the inventory and conversion prompt, and read what comes back. **Prompt to run.** The inventory and conversion prompt (Gate 0). It converts, indexes, and interprets nothing. ```md Case folder renamed to: The sandbox's three files put into sources/ as: The made-up complaint written down as: If this were real, the people who would be in the project channel: What `converted/INDEX.md` lists: What the pass could not read: The hole I filled straight away, while it was cheap: ``` **You should be holding:** everything for this case in one folder, converted, inventoried. ## Gate 1 — gather the discovery **What you do.** Take stock of what you actually have: the sandbox README, `app.py`, `test_acceptance.py`, and the made-up complaint. Read the code for what it establishes — the defects are in it, commented. The prompt writes `DISCOVERY.md` so that Gate 2 can open it by name; you read it back and correct it. **Prompt to run.** The Gate 1 prompt, pointed at those three files by name, with its rules block unchanged. There is no channel and no mailbox on this case: the material an agent would normally read for you does not exist here, and that is a line to write down, not a gap to fill with invention. ```md Sources I actually have: What is established, and which source establishes it: What contradicts what, source against source: What is absent — the questions this material does not answer: Questions I would put to a stakeholder, if there were one: My hypothesis on the product boundary: Written to DISCOVERY.md: yes / not yet What the control session challenged in the above, and what I did with it: ``` **You should be holding:** what is known, what is missing, what contradicts. ## Gate 2 — write the PRD **What you do.** Produce one document whose first section is the strategic framing. Answer the alignment questions rather than letting the agent choose silently — on this case you are the only one who can answer them, and you say so in the document. **Prompt to run.** The PRD prompt (Gate 2), on `converted/`, `converted/INDEX.md`, `DISCOVERY.md`, the memory and the journal, with the template you saved into the folder as `prd-template.md` — it is [in the kit](/pt/resources/prd-template) — for the shape of each section. The three acceptance criteria this case has to carry, because the shipped tests already state them: 1. after a save confirms, a reload — and a switch away from the identity and back — brings the confirmed text back; 2. the second identity gets neither the text in the page nor a 200 from `GET /api/drafts/fictional-draft-001`; the denial does not contain the text; 3. a failed save answers 503, keeps the edited text in the field, shows an error, offers **Retry**, and never shows Saved; a reload before a successful retry restores only the last confirmed text; a retry that succeeds persists. ```md PRD written to: Strategic framing, in three lines: Product boundary — in: Product boundary — out: Roles: the author identity / the second identity, and what each may read: The privacy rule that decides this case: What wins when sources disagree, here: Functional depth — flows that must really work: Acceptance criteria — the three above, in my own words: Open decisions, and who would take them if this were real: Alignment questions the agent asked me, and my answers: Every assumption marked as an assumption: yes / not yet What the control session said about the framing, not only the coherence: ``` **You should be holding:** what is in and what is out, agreed — here, agreed with yourself, and written down as that. ## Gate 3 — prototype the end-to-end flows **What you do.** Let the session take the PM role and write the design prompt from the PRD. Ask for the whole flow, not the main screen: empty, editing, saving, saved, failed with its error and Retry, and the return after reload or a switch of identity. Ask for the narrow screen and for status and error messages a screen reader announces — the shipped tests read a `role="status"` message and a `role="alert"` message, so those are behaviour, not decoration. **Prompt to run.** The design prompt — long specification — with the short instruction layer, and the refinement prompt if the first output is shallow. **Missing service.** There is no design system here. Copy the missing-service block and fill it. Name a reference product you will follow instead, say it is a constraint, and write down that both the prototype and the code will draw on that same thing. ```md Missing service: design system (copy the block above and fill it) Reference product followed instead: Screens and states the prototype covers: Narrow-screen behaviour covered: yes / not yet Status and error messages written as real copy: yes / not yet Who I showed it to, and what they said: Nobody depends on this case: what closed the gate was my own judgement, and that is recorded in the journal as such. What the showings changed, written to memory and journal: ``` **You should be holding:** a prototype of the whole flow, and an honest line about who recognised it. ## Gate 4 — port the prototype into code **What you do. ** The repository arrives here, as it does on a real case: a folder beside the sources. Copy the sandbox's three files out of `sources/` into a `sandbox/` folder at the top of the case, and move the working documents into it under `docs/` — the PRD, `PROJECT_MEMORY.md`, `PROJECT_JOURNAL.md`, all three at once. There is no starter to clone, so you do not clone one: the application is the single standard-library file already in front of you, and you keep your changes inside the shape it has. Expect the session to stop before writing anything and ask for the starter and the conventions; that is the guardrail working, and your answer is the missing-service block below. **Prompt to run.** The coding-agent prompt (Gate 4), plus the standing constraint carried in every coding prompt. **Missing services.** Two blocks here, not one: no approved frontend starter, and no written backend conventions. Fill both before you let the agent write anything, and name what you would ask Frontend Ops and Backend and API Ops for. ```md Missing service: approved frontend starter Missing service: written backend conventions (copy the block above twice and fill both) Working documents moved under docs/: yes / not yet The slice I asked for first: What I ran it with, and what I clicked: What was off when I put the running page beside the design: The back-and-forths it took: What the control session found when it checked the port against the design: What I adapted to the sandbox's existing shape, and why, in the journal: ``` **You should be holding:** a page that runs, that you can click, still failing the three checks. ## Gate 5 — connect the backend **What you do.** The backend on this case is the storage layer and the handler in the same file. Connecting it means making the three defects real behaviour: the save persists what was submitted, the read is scoped to the owner so the second identity is denied at the route, and the failure is no longer swallowed — 503, the edit still in the field, an error, a Retry, no Saved. Go deep on each flow before the next: the empty state, the error, the denial, the reload before a retry succeeds. **Prompt to run.** The connection prompt (Gate 5), one flow at a time. Call the control session on anything that behaves oddly, and ask it to reproduce rather than fix. ```md Flow 1 — save and return. What I changed: Observed after reload: Observed after switching identity away and back: Flow 2 — the second identity is denied. What I changed: Status returned by the direct route: What the body contains: Flow 3 — the failed save. What I changed: Status returned: What stays in the field: What the error says, and where Retry is: What a reload before a successful retry restores: What a successful retry persists: `python3 -m unittest -v test_acceptance.py` returned: What I clicked as each identity, not only what the tests said: Findings the control session sent to the main session: Decisions to memory, changes and verifications to the journal, dated: ``` **You should be holding:** the three flows holding in depth, and the tests passing because the behaviour changed — not because a test was weakened. ## Gate 6 — test, then ship **What you do.** Put it in someone else's hands while you are still working, and fix what comes back. Then walk the delivery path as far as it goes here — which is local, and no further. The server binds to loopback and holds a fixture; nothing about this case is deployed, and the run ends by writing down where it stopped. **Prompt to run.** The release prompt (Gate 6), as a rehearsal. It names what is in the release, what was tested and with which identities, what was verified and how, what is known to be unfinished, and which review did not take place. **Missing services.** No staging and no delivery path, and no leads of the trades to give the go-ahead. Two blocks, filled before you write the release note, so the note can name them. ```md Missing service: a path from local to the repository to staging to production Missing service: leads who give the go-ahead before production (copy the block above twice and fill both) Who else clicked it, and what they reported: What I fixed as it came back: Defects were handled as they appeared, so none were classified: yes / no Checks I ran, and what they returned: What I walked end to end myself, including the empty, error and denied states: What is still unfinished: Which review did not take place, and who was not there to give it: Where this run stops: nothing leaves this machine. Release note written to the journal, dated: yes / not yet ``` **You should be holding:** a case you can account for line by line — what you built, what you verified yourself, and which review nobody gave. ## What the run leaves you with ```md The gate that was hardest, and why: The prompt I had to run twice: The moment the assistant crossed a gate I had not closed: The services I wrote down as missing, and who I would ask on a real case: The one thing I will do differently on a case that matters: ``` Text licensed CC BY 4.0. Code MIT. # Exemplo resolvido Rota: /pt/resources/worked-example · Markdown: /pt/resources/worked-example.md *O texto a seguir é o do kit, em inglês.* # Completed case — the exercise run, gate by gate **A method by Alexis Boyer · version 4.0 · Day 1** **This is a simulated run.** Nothing here is a client project, a real product or a real organisation. The case is the exercise case in [Run your first case](/pt/resources/first-case#worksheet), carried out against the [supplied local application](/pt/resources/sandbox) that ships with this kit. There is no sector, no company and no person in it: the two identities are the exercise application's own switcher links, and the people who tested are referred to by what they did. The artifacts below are what a run of the method (Onirion) produces at each gate — an index, discovery notes, a PRD, a design prompt, a port, a backend connection, a test round, a release note, and the two files that record why the product moved the way it moved. Read them for their shape. Do not read the dates, the messages or the test output as a record of real work. The case, in one line: someone wrote an update, selected **Save draft**, left the page, and the text was gone on return. The outcome the run owns is that **the author gets their confirmed text back, and no one else can read it** — including through the route that does not go through the page. The run below took eight working days, from the folder of sources to the release note. The long part of a real build — connecting a real backend until the flows hold in depth — is a day here, because the whole product is one page and one stored record. Do not read the timing as a claim about anything larger. ## Gate 0 — set up the project folder ### What went into the folder One folder, made for this case. Everything the run would draw on went into it: the exercise worksheet, the supplied application, the report that opened the case, an exported chat thread where the loss was first mentioned, an older note on what "saved" was supposed to mean, a screen recording, a spreadsheet of requests collected earlier, and a capture of the confirmation message as it stands today. The coding agent's session was opened on that folder. At that point there was nothing to build and nothing to run in it — a folder of sources is enough to start. The memory and the journal were created first, before any prompt ran: `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md`, both empty. The project channel was created the same day, with the two people who would test later in it from the start. ### `converted/INDEX.md`, as the first prompt returned it | Source | What it is | Date | | --- | --- | --- | | `report.txt` | The report that opens the case: the author selected Save draft, left the page, and the text was gone on return. | Day 2 | | `thread-export.md` | An exported chat thread where the loss was first mentioned, and two replies saying it had happened to them as well. | Day 1 to Day 2 | | `saved-means-what.md` | An older note on what the word "saved" should mean in the interface. | undated — no date in the file, none in its name | | `requests.csv` | Converted from a spreadsheet of requests collected earlier. Two columns carry dates; the rest do not. | a three-month window | | `first-case.md` | The exercise worksheet this run follows. | Day 13 | | `sandbox/README.md` | The supplied application's own notes: how to run it, its two switcher identities, the record it starts with, and the three deliberate defects it carries. | undated | | `sandbox/app.py` | The supplied application. One module, standard library only, bound to loopback. | undated | | `sandbox/test_acceptance.py` | Three acceptance tests written against the intended behaviour, not against what the application currently does. | undated | | `capture-confirmation.png` | A capture of the confirmation message as the application renders it today. Listed, not converted. | file date Day 3 | ### What could not be read - `notes-an earlier year.pdf` — password protected. Not opened, not converted. - `walkthrough.mov` — a screen recording. Listed from its file name only; nothing was inferred from it. - `capture-confirmation.png` — an image. Listed and kept as a source, but no text was extracted from it and nothing was concluded from it. - `requests.csv` — converted, but eleven rows carry no date, so nothing in them can be placed in time. The originals were never touched. The conversion wrote into `converted/` and nothing was moved, renamed or overwritten. The pass sent nothing anywhere. ### The obvious holes, filled the same day The password for the PDF was asked for and supplied; the prompt was re-run on that one file and it converted. The recording was watched by the person running the exercise, who wrote a one-paragraph note beside it saying what it shows — a walkthrough of the save flow, from before the failure switch existed, which decides nothing. The undated rows in the spreadsheet stayed undated and were marked as such in the index rather than guessed at. The session was told to state where it is before going further, and it did, at every gate after this one. **In hand at the end of Gate 0:** everything in one folder, converted, inventoried. ## Gate 1 — gather the discovery ### `DISCOVERY.md`, as it was written **Sources read** - The report and the chat thread: three separate accounts of text disappearing after a save that appeared to succeed. - The older note on what "saved" means: it says the word must follow the write, never precede it. - The supplied application's notes: they name three deliberate defects — a save that confirms without writing, a direct read route that answers anyone, and a write failure that is swallowed and reported as success. - The application itself, read as a source rather than as code to change. - The three supplied acceptance tests, read as the statement of intended behaviour. - One acceptance run of those tests, to see what the starting point actually is rather than what the notes say it is. The acceptance run, as it came back: ```text test_author_recovers_only_confirmed_saved_text_after_return ... FAIL test_failed_save_keeps_edit_visible_and_does_not_replace_confirmed_draft ... FAIL test_second_identity_cannot_read_author_draft_in_ui_or_direct_endpoint ... FAIL AssertionError: 'The imaginary library opens next Tuesday.' != 'The imaginary library now opens on Friday.' : A confirmed save must survive reload. AssertionError: 200 != 503 : The deterministic failure must not claim success. AssertionError: 200 not found in (403, 404) : A second user must be denied at the endpoint. ``` Three failures, which is the documented starting point. Three *errors* instead would have meant the environment stopped the tests from starting their local server on loopback. **What is established, and by which source** - The confirmation message is not evidence of a write. The save response renders the confirmation with an empty field while the stored record is unchanged. *(Observed in the run above; consistent with the application's own notes.)* - The page hides the author's text from the second identity, but only because the read it performs selects by owner and returns nothing for an identity that holds no record. Nothing in the page is enforcing a rule. - The direct read route returns the record's content to any identity that has been chosen. *(Observed: the route looks the record up by its id and answers with the content; there is no ownership check on that branch.)* - A write failure is raised inside the storage layer and caught by the handler, which then answers as if the write had succeeded and drops the submitted text from the page. **What contradicts what** 1. **One record for everyone, or one record per author.** The worksheet's rules describe the author retrieving *their* latest confirmed text, and the read path agrees: it selects by owner. The write path does not: it returns the same constant record id whatever identity performed the save. One source describes a record per author; the other implements a single shared record. Both cannot hold, and which one is intended decides whether a save by one identity can overwrite another's text. *Not resolved here. Sent to the alignment questions at Gate 2.* 2. **What the confirmation is for.** The older note says the word "saved" must follow the write. The running interface shows it before any write has been attempted, and the capture in the folder shows the same message. The note is older than the interface, so the disagreement is real rather than a misreading. *Resolved by the order written into the PRD: the tests and the notes decide, the current behaviour decides nothing.* **What is absent** 1. **What a denied direct read should answer.** Nothing in the material says. The supplied test accepts either of two answers — one that refuses and thereby confirms the record exists, and one that behaves as though it does not exist. Those are two different product decisions about whether the existence of someone's record is itself private, and the material does not settle it. 2. **Whether the second identity may hold a record of their own.** The read path would return nothing for them; the write path would send their text to the author's record id. No source says whether the editor should be there for them at all. 3. **What happens to unsaved text when the tab is closed rather than reloaded.** The rules cover reload only. **Hypothesis on the product boundary** One page, one stored record per author, two identities, and one failure that can be provoked on purpose. Deletion, expiry, simultaneous editing, offline saving and real authentication are outside it. **Privacy risks** The stored content is text a person wrote. The switcher is not authentication — it is a local cookie with two values — so nothing here demonstrates a permission model; it demonstrates a read model. The application binds to loopback and is never to be deployed or given real data. **Repository, starter and template constraints** No approved starter and no written conventions exist for this exercise. The supplied application's own constraints stand in: standard library only, no new dependency, loopback only, and the supplied tests are not to be weakened to make the run look finished. ### The control session, at Gate 1 The main session concluded: *"the second identity does not see the author's text, so the privacy rule already holds."* The control session was given the same material and challenged it. **Finding.** The conclusion is not supported by what the main session read. The page shows nothing to the second identity because the read it performs selects by owner and that identity owns no record — not because any rule is applied. The route that does not go through the page looks the record up by its id and answers with its content to whichever identity has been chosen. **Evidence:** the read branch for that route in the application module performs no comparison between the record's owner and the current identity; the acceptance run above fails on exactly that assertion, with the route answering 200 where the test requires a denial. **What I could not check:** whether a real product would place the rule in the query or in the handler — that is a decision, not a defect, and it is yours. **The decision that followed.** Privacy for this product is a read-model rule, not an interface behaviour: what an identity must not see never reaches their browser, and the check lives in the query rather than in whatever renders the page. Written into the PRD as section 6, and the acceptance check that matters is the one that exercises the route, not the one that looks at the page. Recorded in the memory the same day. **In hand at the end of Gate 1:** what is known, what is missing, what contradicts. ## Gate 2 — write the PRD ### The alignment questions, and what came back The PRD prompt was run on the converted folder, its index, `DISCOVERY.md`, and the memory and journal. It stated what was established, what contradicted what and what was absent, then asked two alignment questions before writing anything. **Question 1 — what a denied direct read answers.** *Source A, the supplied test, accepts either a refusal or a not-found answer. Source B, the discovery notes, records that the record's id is printed in the application's own notes and is therefore guessable. The product risk: a refusal tells anyone who asks that a record with that id exists and belongs to someone else, which is a fact about a person's content. Not-found hides that, at the cost of being less honest to a legitimate client that has simply lost its own record. I would default to the refusal because it is the more conventional answer. Confirm or correct.* Answered: **not-found**. The existence of someone's record is part of what is private here, and the id is guessable, so the more conventional answer leaks the one thing worth protecting. The default the prompt proposed was corrected, which is why the question was asked rather than decided silently. **Question 2 — whether the second identity may save.** *Source A, the read path, is written per owner. Source B, the write path, targets a single constant record. The product risk: if the second identity may save and the write stays as it is, their text replaces the author's confirmed text, and the interface will report that as a success to both of them. Default: both identities may save, and every write is keyed by its owner. Confirm or correct.* Answered: **confirmed**. Both identities hold their own record; a save under one identity must never touch another's. ### The PRD Fourteen sections, in the order the template sets, and no others. It lives beside the memory and the journal and moves into `docs/` with them at Gate 4. #### 1. Strategic framing - **What this product is going to be:** one page where a signed-in author writes an update, saves it explicitly, and gets exactly what was confirmed back when they return. - **What is wanted from it:** that the word on the screen matches what happened in storage — every time, including when storage refuses. - **What is explicitly not wanted:** saving on the author's behalf, saving in the background, guessing what they meant, or any message that lets someone believe their text is safe when it is not. - **The business loop it serves:** people write updates for other people to read. A tool that loses them once stops being used, and the loss is silent, so the trust is spent before anyone reports it. - **The constraints that shape it:** one module, the standard library only, loopback only, no new dependency, and three supplied acceptance tests that state the intended behaviour and are not to be weakened. - **What the sections below detail:** the boundary, the two identities and what each may see, the three flows, the states the stored record moves through, the privacy rule and where it is enforced, and what has to be true before any of it counts as done. #### 2. Product boundary - **Who the product is for:** a signed-in author writing an update for later. - **Who it is not for:** anyone reading someone else's updates, and anyone administering the store. - **Workflows that belong elsewhere:** authentication, account management, and anything that moves an update on to a reader. - **What the product must never expose:** another identity's text, and whether another identity holds a record at all. - **Shared objects assumed:** one stored record, carrying an id, an owner and its content. - **Non-goals:** deletion, expiry, version history, simultaneous editing, offline saving, saving without an explicit action. - **How an out-of-scope workflow is represented instead:** a read that is not the owner's ends as a not-found answer carrying no content — not as an error the reader can act on, and not as a request path. #### 3. Roles and permissions | Role | What they do | What they can see | What they must not see | What they can do | | --- | --- | --- | --- | --- | | Author identity | Writes an update and saves it explicitly. | Their own record, its confirmed text, and when it was confirmed. | Any other identity's text; whether any other identity holds a record. | Write, save, retry a failed save. | | Second identity | The same, on their own record. Starts with no record. | Their own record; the empty state until they save. | The author's text, through the page or through the direct route. | Write, save, retry a failed save — on their own record only. | - **Where role differences change navigation, actions, disabled states or empty states:** nowhere in the navigation, and nowhere in the actions. The two roles differ by exactly one thing — what their record read returns — and that difference is only visible as the empty state one of them starts in. They are written out separately anyway, because "the same page with different data" is precisely the case where a rule gets left in the interface instead of the query. - **How a role is granted, changed and removed:** in this exercise, by choosing a switcher link, which is not authentication and demonstrates nothing about permissions. A real product names its approved authentication here, with its owner. Recorded as a gap of the exercise, not as a design. #### 4. Core workflows - **Save and confirm.** - Who runs it: either identity. - Entry point: the page, with text in the field. - Steps: the author edits; selects Save draft; the write is attempted; the write is confirmed; the page reports it. - Branches: the write is refused — see the third workflow. - Failures and how they end: never silently; a refused write ends in the failed state and never in the confirmed one. - Confirmations: the confirmation appears only after the store has confirmed, and names when. - Final state: the record holds the submitted text. - **Return and recover.** - Who runs it: the owner of a record. - Entry point: reopening the page, after a reload or after switching away and back. - Steps: the record is read by owner; its confirmed content fills the field. - Branches: no record yet — the empty state. - Failures: a read that fails leaves the field empty and says so; it never shows stale text as though it were confirmed. - Final state: the field holds the last confirmed text, and nothing else. - **Failed save and retry.** - Who runs it: either identity, when the write is refused. - Entry point: a save whose write does not complete. - Steps: the answer reports the refusal; the submitted text stays in the field; an error is shown; Retry is offered. - Branches: retry succeeds and the flow ends as a confirmed save; the page is reloaded before a successful retry, and the last confirmed text comes back — the unsaved text is gone, which is the honest outcome and must not be disguised. - Confirmations: none until a write is confirmed. - Final state: either confirmed, or unchanged with the refusal still visible. - **A read that is not the owner's.** Entry point: the direct route, with a record id. It ends as a not-found answer carrying no content. It has no success path. #### 5. Product states and data visibility - **Object: the stored record.** - Its states, in order: absent → confirmed. A confirmed record stays confirmed; a later confirmed save replaces its content. - What moves it: a write the store has confirmed, and nothing else. Not a submission, not a rendered message. - Terminal states, and what reopens them: none. Deleting the generated store file beside the application resets the exercise. - What each role sees in each state: its owner sees absent as the empty state and confirmed as their text. Every other identity sees absent in both, because the record they do not own is not read for them at all. - What is hidden, and from whom: the content and the existence of a record, from everyone but its owner. - **Saving, failed and editing are states of the page, not of the record.** Writing this down is what stops the interface from inventing a fourth record state and reporting it as storage. #### 6. Privacy and ethics rules - **Sensitive data held here:** text a person wrote and has not published. - **How it must be handled:** read by owner, written by owner, and never loaded into an answer before the owner has been compared. - **What must never be shown, and to whom:** the content, and the existence of a record, to any identity that does not own it. - **Rules for search, filters and exports:** there are none of these in scope, and none may be added without returning to this section. - **What may reach the browser at all:** only the requesting identity's own record. The rule lives in the query, not in the component that renders. - **Controlled exceptions:** none. - **The intake path for a request to see someone else's content:** none exists, and none is to be improvised. - **Retention and deletion:** the record lives in the local store file beside the application. It holds nothing about a person beyond the text they typed, and no real content is to be put into it. #### 7. Which source wins when sources disagree 1. An explicit decision by the person who set the exercise, recorded in the memory with its date. 2. The three supplied acceptance tests — they state the intended behaviour, and they are not weakened to make a run look finished. 3. The supplied application's own notes, which name the deliberate defects. 4. The strategic framing section of this PRD. 5. The rest of this PRD. 6. The worksheet and the older notes in the folder. The current behaviour of the running application decides nothing: it is known to be defective, and it appears in the discovery as evidence, never as an instruction. - **What must be checked before an older note is used:** whether the supplied notes contradict it, and whether it predates a decision recorded in the memory. - **Who records a change to this order, and where:** the Product Builder, in the memory, dated. #### 8. Design baseline and acceptable drift Assumed now: - **The reference this product follows:** there is no design system for this exercise. The reference is the supplied application's own markup and the platform's default form controls, named as a constraint rather than as inspiration. - **Its version or location:** the supplied application as it stands in the kit. - **Non-negotiable in it:** the confirmation region and the error region stay separate and stay announced; the submitted text stays in the field when a write is refused; status is never carried by colour alone. - **Acceptable drift:** spacing, density, the order of the two actions, and the wording of every message. - **Where the prototype and the front end draw on the same thing:** both follow the reference above, so that what the design tool produced and what the code produces remain the same product. To request from Design Ops — none of which exists for this exercise, so each line records what stood in instead: - The components and their states — stood in by the supplied markup. - The tokens and the rules for using them — none; the defaults were used and nothing was invented. - What may be extended and what may not — agreed ad hoc with the person who set the exercise. - Who maintains the system — nobody; recorded as a gap. - An agent-readable form of the above — the constraints paragraph in the supplied notes. - The named owner of each request, and the date an answer is needed — the exercise has no owner to name, and that is written in the journal, dated, rather than papered over. #### 9. Functional depth - **Flows that must work end to end:** all three. There is no screen here deep enough to be worth faking. - **Flows that may stay placeholders:** none. - **What each clickable surface does:** Save draft attempts a write; Simulate failed save attempts a write that the store will refuse, which is a deliberate, documented facility of the exercise; Retry resubmits the text in the field; the switcher links change identity; switching away clears the identity. - **Simulated states deliberately allowed:** exactly one — the refused write, through the supplied switch. - **States required everywhere:** empty, saving, confirmed, refused, permission-denied, and the answer that carries no content. #### 10. Backlog taxonomy | Category | What belongs in it here | Where it is tracked | Who owns it | | --- | --- | --- | --- | | Product decisions | What a denied read answers; whether the second identity may save; what happens to unsaved text on tab close. | The memory, dated. | Product Builder, decided with the person who set the exercise. | | Implementation tasks | The write keyed by owner; the refusal answer; the separated regions; the Retry action. | The journal. | Product Builder. | | Design parity issues | The message placement that had to change from what the design showed. | The journal, as deliberate drift. | Product Builder. | | Privacy and legal guardrails | The read-model rule, and the answer that carries no content. | This PRD, section 6. | Product Builder. | | QA findings | What came back from the test round. | The journal, and the test file where a check was added. | Product Builder. | | Backend integration work | The store contract and the refusal path. | The journal. | Product Builder. | | Future nice-to-haves | Version history; recovering unsaved text after a tab close. | The memory's open questions. | Not owned; not started. | #### 11. Backend and API assumptions Assumed now: - **Objects and contracts assumed:** one record with an id, an owner and content; a read by owner; a read by id; a write that either confirms or raises. - **Authentication and permissions assumed:** the identity arrives as a local cookie holding one of two values, and it is not authentication. Every rule in this PRD is a read-model rule that does not depend on that being real. - **The business meaning of key values:** *confirmed* means the store completed the write and said so. Nothing else means confirmed. - **Routes these flows use:** the page; the save submission; the direct read of one record by id; the two identity links; the link that clears the identity. - **The shape the mock services follow until the real store is connected:** the store's own three operations — read one record for an owner, read one record by id, write content for an owner — so that swapping them changes the wiring and not the flows. To request from Backend and API Ops — which does not exist for this exercise: - A catalog with real examples, request and response shapes, errors and versioning, reference patterns for authentication and migrations, a test environment with safe data, read-only access to logs, and a written route for an API that does not exist yet. None of these exists here. The supplied module is the contract, the exercise's own notes are the documentation, and that gap is recorded in the journal, dated, rather than filled by invention. To request from Frontend Ops — which does not exist for this exercise either: - An approved starter, its version and its owner; the API client pattern; the checks required on a deployable branch. None exists. The supplied application's constraints stood in, with the agreement of the person who set the exercise, recorded in the journal. #### 12. Acceptance criteria - **Save and confirm.** Works against the mock services and then against the real store. The confirmation appears only after the store confirms. The confirmed text survives a reload and an identity switch away and back. Checks run before finishing: the supplied acceptance run, plus walking the flow in a browser. - **Return and recover.** The field holds the last confirmed text and nothing else. The empty state is reached by the identity that owns no record. No privacy regression: the read carries the owner. - **Failed save and retry.** The answer does not report success. The submitted text is still in the field. The error is announced in its own region and the confirmation region is empty. Retry is offered and works. A reload before a successful retry brings back the last confirmed text. - **A read that is not the owner's.** Answers not-found, and the answer carries no part of the content. Exercised through the route, not through the page. - **Across all of them.** Tests added or updated; memory and journal updated where product behaviour, architecture, a decision or future reasoning changed. #### 13. The QA contract - **Personas to test:** the owner of the seeded record, and the identity that owns nothing. - **Role-based privacy checks:** the direct route requested as the non-owner; the page requested as the non-owner; a save performed as the non-owner followed by a read as the owner. - **Requirements derived from what testers said:** the failure message must say where the text is, not only that something went wrong. - **Regression flows:** all three workflows, plus the non-owner read, after every change to the store or the handler. - **Validation commands:** the supplied acceptance run, from the application's directory. On the Codex path, the default workspace sandbox blocks the tests' own local server and they end in permission errors before reaching any real result; allow network access for the session, or run the command outside the sandbox. Checked with Python 3.9.6 and Codex CLI 0.155.0-alpha.9.2. - **Expected report format:** what was run, what it returned, what was walked in a browser, and what was not checked. - **Severities, and when they start:** P0 blocking, P1 important, P2 minor — and they start only once there are more defects than the session can hold. In this run that never happened, so none were used. #### 14. Open decisions | Decision | Alignment question behind it | Default proposed | Who decides | By when | | --- | --- | --- | --- | --- | | What a denied direct read answers | The test accepts a refusal or a not-found answer; a refusal confirms that someone's record exists, and the id is guessable. | Refusal | The person who set the exercise | Before the store is connected | | Whether the second identity may save | The read path is per owner, the write path targets one constant record; if both are true, one identity's text replaces another's and both are told it worked. | Both may save, every write keyed by owner | The person who set the exercise | Before the store is connected | | Unsaved text when the tab is closed | The rules cover reload only; nothing says whether closing the tab should behave differently. | Out of scope; the text is lost and nothing implies otherwise | The person who set the exercise | Not needed for this run | Both of the first two were answered at this gate. The third stayed open and is recorded as open in the memory rather than decided in passing. **In hand at the end of Gate 2:** what is in and what is out, agreed with the person who set the exercise. ## Gate 3 — prototype the end-to-end flows The coding session took the PM role, wrote the design prompt from the PRD and sent it to the design tool. The prompt was not hand-written and screens were not pasted back and forth by hand. ### The design prompt that was sent ```text Design a full high-fidelity prototype for the update editor, a single-page workspace where a signed-in author writes an update, saves it explicitly, and recovers exactly what was confirmed. This is a real logged-in working surface, not a landing page. Start directly inside the product experience. Treat the attached PRD — whose first section is the strategic framing — together with the discovery notes and the supplied application's own notes, as what decides. Where a source is missing, do not invent a product decision. Design end-to-end flows, not only the major screens. Every flow below must be walkable from its entry point to its final state, including the intermediate steps, the branches, the failures and the confirmations. ## Strategic context People write updates for other people to read. A tool that loses one, silently, is abandoned before anyone reports the loss. This product exists so that the word on the screen matches what happened in storage, including when storage refuses. This product helps an author answer: 1. Is what I wrote actually kept? 2. If it was not, is my text still here? 3. Can anyone else read it? The product should feel like a working surface, not a document editor with chrome. Calm, plain, quick to re-enter. ## Product boundary This product is for a signed-in author writing an update for later. This product is not for a reader, an administrator, or anyone reading someone else's content. Do not design: deletion, expiry, version history, simultaneous editing, offline saving, sharing, account management, or saving without an explicit action by the author. A read that is not the owner's has no success state to design. It ends as an answer carrying nothing. ## Users and roles - Author identity: writes and saves; sees their own confirmed text and when it was confirmed. - Second identity: the same actions on their own record; starts owning nothing; must never see the other's text or learn that it exists. The two roles use the same single surface. The only difference is what their record read returns. Show the empty state that difference produces. ## Core product principles 1. The confirmation follows the write. Never precedes it. 2. A refused write never removes the author's text from the page. 3. Status is announced, and never carried by colour alone. 4. Every clickable surface implies a real behaviour. 5. Nothing on this surface suggests a capability the product does not have. ## Navigation and shell One surface. An identity line at the top with a way to switch away, the editor, the actions, and one region for confirmation and one for error. No brand row, no navigation the product does not have. ## Visual direction There is no design system for this product. Follow the supplied application's own markup and the platform's default form controls. Treat that as a constraint, not as inspiration. Plain type, near-black text, one readable column, compact actions. Avoid heroes, decorative gradients, oversized cards and any analytics surface. ## Core data concepts - The update record: its owner, its confirmed content, and when it was confirmed. - The page states: empty, editing, saving, confirmed, refused. ## Required screens and flows 1. Entry: choosing an identity, and the surface that follows. 2. Empty state: the identity owns no record yet. 3. Editing: text in the field, nothing saved yet, and it must be obvious that nothing is saved yet. 4. Saving: the moment between the action and the answer. 5. Confirmed: the message, what it names, and where it sits. 6. Refused write: the text still in the field, the error in its own region, the Retry action, and the absence of any confirmation. 7. Retry, succeeding: what changes on the surface. 8. Reload after a refused write: the last confirmed text returns and the unsaved text does not. Design how that is said, honestly. 9. Return: leaving and coming back to the last confirmed text. ## Interaction states to include Empty; saving; confirmed; refused with the text preserved; retry; announced status; announced error; disabled action with a stated reason; narrow screen. ## Privacy and visibility rules Respect: an identity sees only its own record; nothing indicates whether another record exists. Do not expose another identity's content anywhere, including in a message, a count or a placeholder. ## Content and mock data Language: English. Use realistic update text. Avoid lorem ipsum. Write real product copy, especially for the refused-write message, which is the hardest sentence in this product. ## Output expectations A complete surface with all of its states, not one screen. Someone reading the result should be able to walk each flow from end to end and should never be in doubt about whether their text is kept. ``` ### What came back, and what the showings changed The first output was a clean single surface with the states listed, and one thing wrong with it: the refused-write message said *Save failed.* It was shown to two people who write updates. - Both read *Save failed* as *your text is gone*. One of them selected the text and copied it before doing anything else — which is exactly the behaviour the product exists to make unnecessary. The message was rewritten: **"Not saved. Your text is still here. Try again."** The message names where the text is, because that is the only question the person is actually asking. - The confirmation said only *Saved*, and neither of them could tell whether it referred to what was in the field now or to something earlier. The confirmation gained the time it was confirmed. - One of them asked what happens if the tab is closed with unsaved text. The honest answer is that it is lost. That was not designed around; it was recorded as an open decision and left open. They were shown the flow they do every day — write something, save it, come back — not a tour of the surface. The second showing ended with both saying it was the tool they needed, which is what closed the gate. **In hand at the end of Gate 3:** a prototype the people concerned recognise as their tool. ## Gate 4 — port the prototype into code **There was no starter to clone.** No approved starter repository and no written conventions exist for this exercise, so none were invented. The supplied application is the repository. The gap was written into the journal, dated, with what stood in for it and with whose agreement — and that record is the request that gets made next time, not a decision that the gap was acceptable in general. The three working documents moved together into `docs/` inside that repository — the PRD, `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` — and the folder of sources stayed where it was. ### What the port produced The page layer was rewritten so that every state the design accepted exists in the code, fed by a service shaped like the store's contract but returning canned answers. Nothing touched storage at this gate. | State | What it renders | Reached by | | --- | --- | --- | | Empty | Field empty, no message in either region. | An identity that owns no record. | | Editing | The field holds text; the confirmation region is empty. | Typing after any state. | | Confirmed | Confirmation region names the time; the field holds the confirmed text. | A write the service says it completed. | | Refused | Error region filled; field holds the submitted text; confirmation region empty; Retry offered and Save hidden. | A write the service says it refused. | | Not the owner's | Nothing. No field, no message, no content in the answer. | The direct route with an id the identity does not own. | What else the port did, and what it deliberately did not do: - The confirmation region and the error region became two separate regions, each announced in its own way, so that a refusal can never be written into the region that means success. - Every message moved to one place at the top of the module instead of being written into the markup, so the copy the showings produced has a single home. - The handler chooses a state and passes values; the rendering holds no rules. Routes stayed thin. - The mock service exposed the store's three operations by name, so Gate 5 would be a swap and not a rewrite. - Nothing was redesigned. Two things came out different from the design, on purpose, and both were recorded: the message sits in the page's own region rather than in the floating element the design showed, because the surface re-renders on submission and a floating element is not announced when it does; and the actions row wraps below a narrow width, which the design had not covered. The back-and-forths were the work of this gate: the running surface beside the design, naming what was off — the error sitting below the field where nobody looked, the two actions indistinguishable at a glance, the button reading *Save again* where the design said *Retry*, the density of the actions row. Fix, rerun, look again. No screen was rebuilt on paper first, and no map was written from the design to the code; the port was close enough that neither would have paid for itself. The three acceptance tests still failed at the end of this gate, on the same three assertions as at Gate 1. That was expected: nothing was connected yet, and a green build was never the evidence being sought. **In hand at the end of Gate 4:** a surface that runs, that you can click. ## Gate 5 — connect the backend The mock service was replaced with the store, one flow at a time, in the same session. No second building session was opened. ### What the connection changed - **The write stopped being a no-op.** The store now writes the submitted content and reports what it wrote; the handler's confirmation is issued from that report and not from having reached the end of the function. - **The write is keyed by its owner, not by a constant record id.** This is the change the control session forced — see below. - **A refused write answers as a refusal.** The exception raised inside the store is no longer swallowed: the answer carries the refusal, the submitted text, the error in its own region, and a Retry action, and it carries no confirmation. Reloading before a successful retry returns the last confirmed content, which is the honest outcome. - **The direct read compares the record's owner with the current identity before any content is loaded into the answer.** A read that is not the owner's ends as a not-found answer whose body carries no part of the content. The comparison lives in the query, so the content of a record someone does not own never reaches the process that would render it, let alone their browser. - **The page read stayed keyed by owner,** so the second identity meets the empty state rather than someone else's text. - Deep on each flow before moving to the next: the empty state, the refusal, a second refusal in a row, a retry that succeeds, a reload between the two, and a read attempted as the identity that owns nothing. ### The control session, at Gate 5 Called in on a doubt rather than on a bug: the tests were passing and the flows looked right. **Finding.** The write still targets a single constant record id. The read is keyed by owner and the write is not, so a save performed under the second identity replaces the author's confirmed content, and both identities are told it worked. > **Evidence.** The store's write operation returns the same constant record id whatever owner it is given — the same contradiction recorded in `DISCOVERY.md`, still present in the connected code. PRD section 3 says a save under one identity must never touch another's record, and PRD section 6 makes that a read-model rule. **Reproduction:** choose the second identity, type any text, select Save draft; switch to the author identity and reload the page. The author's confirmed text is the second identity's text. > **Why the tests did not catch it.** None of the three supplied acceptance tests performs a save under the second identity. They check that the second identity cannot *read*; nothing checks that the second identity cannot *overwrite*. > **What I could not check:** whether the same hole exists on any other path — there is only one write path, so this is the whole of it. > *I read, checked and challenged. I changed nothing and I decided nothing.* **The decision that followed.** The write is keyed by its owner, and the record id stops being a constant in the write path. A regression test was added beside the three supplied ones — save as the second identity, then read as the author, and assert the author's confirmed text is unchanged — because a defect that no check catches will come back. The three supplied tests were not touched. Recorded in the memory, dated, and in the journal with what was verified. The finding went from the control session to the main session directly, as the method asks: the control session addressed the main session itself, named in the last bracket of its starting prompt, and the Product Builder read it and decided. Where a message cannot land, the finding is relayed by hand instead, unchanged and with its origin stated. **In hand at the end of Gate 5:** the flows hold in depth. ## Gate 6 — test, then ship ### The test round, with demo accounts Authentication is not connected in this exercise and is outside it, so demo accounts are what exists: the two switcher links. They were sent to the two people who had walked the design at Gate 3, with the record the application starts with and the failure button explained, and with the reminder that the switcher is not authentication and that no real content goes in. What came back, and what was done with it: - *"I pressed the failure button twice and after the second one I couldn't tell whether the first attempt had gone through."* The error region now names when the last confirmed save happened, so a refusal always says what is still safe. - *"Retry sits next to Save draft and I can't tell them apart."* Retry only appears in the refused state, and Save is hidden while it shows. One action at a time. - *"On my phone the two buttons were on one line and I pressed the wrong one."* The actions row wraps below a narrow width — the drift already recorded at Gate 4, now the thing a tester actually hit. - *"When it says Saved, saved where?"* Left as it is. The confirmation names the time; naming a place would be a claim about storage this product does not make. Each one was fixed as it came back. Severities were never used in this run, because there was never more coming back than the session could hold — the moment that changes is the moment P0, P1 and P2 start earning their keep, and it did not arrive. The acceptance run after the fixes, from the application's directory: ```text python3 -m unittest -v test_acceptance.py test_author_recovers_only_confirmed_saved_text_after_return ... ok test_failed_save_keeps_edit_visible_and_does_not_replace_confirmed_draft ... ok test_second_identity_cannot_read_author_draft_in_ui_or_direct_endpoint ... ok test_second_identity_save_does_not_touch_author_record ... ok Ran 4 tests OK ``` Walked in a browser as well, as both identities: the empty state, a save, a reload, a switch away and back, two refusals in a row, a retry, a reload between a refusal and its retry, and the direct route requested as the identity that owns nothing. ### The release note Prepared in the main session and sent by hand. The prompt that produced it sends nothing anywhere. ```text Release note — the update editor Date: Day 12 To: the leads of the trades concerned What is in this release, flow by flow - Save and confirm: the confirmation follows the write and names when it happened. A confirmed save survives a reload and an identity switch. - Return and recover: the field holds the last confirmed content and nothing else. An identity that owns no record meets the empty state. - Refused write: the answer reports the refusal, keeps the submitted text in the field, shows the error in its own announced region, offers Retry, and shows no confirmation. A reload before a successful retry returns the last confirmed content. - A read that is not the owner's: answers not-found, with no part of the content in the answer. The ownership comparison is in the query. What has been tested, by whom, with which accounts - Two people who had not seen the build, using the two demo identities the exercise supplies. These are switcher links, not authentication. - The Product Builder, walking all four flows in a browser as both identities. What was verified and how - The acceptance run: the three supplied checks and one added regression check, all passing, from the application's directory. - Walked end to end in a browser: empty state, save, reload, switch away and back, two refusals in a row, retry, reload between a refusal and its retry, and the direct route requested as the identity that owns nothing. - The control session's finding at Gate 5 — a save under one identity overwriting another's record — reproduced, fixed, and covered by the added regression check. What is known to be unfinished - Unsaved content is lost when the tab is closed. This is an open product decision, recorded in the memory, not a defect and not designed around. - The switcher is not authentication and demonstrates nothing about permissions. Every rule in this release is a read-model rule that does not depend on it. What the leads are asked to give the go-ahead on - The read-model rule and the not-found answer. - The refusal path, which is where this product either keeps its word or does not. Which review did not take place, and who was not there to give it - No frontend, backend or data lead read this change: this exercise has no trades to convene, and there is no staging and no production to ship to. The application is loopback-only and is not deployed. The go-ahead was given by the person who set the exercise, on their own. - That gap is the request that gets made next time, and it is written in the journal, dated, rather than left to be reconstructed later. ``` Nothing was deployed, because the exercise has nowhere to deploy to and the supplied application is never to leave the machine. What this gate produced is the note, the go-ahead that was actually available, and the written record of the review that did not happen. The delivery path itself — local, then the repository, then staging, then production, with the checks along the way and a way to see which revision is live — is on the list of what was asked for and not supplied. The one case where things are deliberately frozen did not apply here: nothing was going to production. **In hand at the end of Gate 6:** demo accounts in real hands, and a note that names what was verified and what was not reviewed. ## The memory and the journal at the end of the run ### `docs/PROJECT_MEMORY.md` **Current product position.** One surface where an author writes an update and saves it explicitly. The confirmation follows the write and names when it happened. A refused write keeps the submitted text in the field and never claims success. An identity reads only its own record, and a read that is not the owner's answers not-found with no content — the comparison is in the query, not in the interface. Both identities may save; every write is keyed by its owner. Unsaved content is lost when the tab is closed, and that is open rather than decided. **Product principles.** The confirmation follows the write. A refusal never removes the author's text. What an identity must not see never reaches their browser. Nothing on the surface suggests a capability the product does not have. ```text ## Day 5 - Privacy here is a read-model rule Context: the main session concluded the privacy rule already held because the page shows nothing to the second identity. The control session checked that against the material and it does not hold: the page shows nothing because the read selects by owner and that identity owns no record, and the direct route answers with the content to any chosen identity. Decision: what an identity must not see never reaches their browser. The check belongs in the query, not in whatever renders the page. Rationale: an interface that hides content is hiding it from the one person who is looking at the interface. The route that does not go through the page is where the rule is either real or absent. Trade-offs: slightly more work in the read path; no way to build a legitimate administration view later without returning to this decision. Impact on product / architecture / QA: PRD section 6; the acceptance check that matters exercises the route, not the page. Open questions: none. Links: DISCOVERY.md, the control session's Gate 1 finding. ## Day 6 - A denied direct read answers with a refusal [REPLACED Day 7] Context: the supplied test accepts either a refusal or a not-found answer. Decision: answer with a refusal, as the more conventional choice. Rationale: it is honest to a legitimate client that has lost its own record. Trade-offs: it confirms that a record with that id exists and belongs to someone else. Impact on product / architecture / QA: none — replaced before implementation. Open questions: whether the existence of a record is itself private here. Links: the alignment question asked at Gate 2. REPLACED BY the entry of Day 7. Kept because the reasoning that was corrected is worth being able to see. ## Day 7 - A denied direct read answers not-found Context: the alignment question above was put to the person who set the exercise, with the risk stated: the record id is printed in the supplied notes and is therefore guessable, so a refusal tells anyone who asks that someone else's record exists. Decision: answer not-found, with no part of the content in the answer. Rationale: the existence of a person's unpublished content is part of what is private. The default the prompt proposed was corrected, which is why it was asked rather than chosen silently. Trade-offs: less informative to a legitimate client. Accepted. Impact on product / architecture / QA: PRD sections 2, 6 and 12; the direct read path; the privacy check. Open questions: none. Links: PRD section 14. ## Day 7 - Both identities may save, every write keyed by its owner Context: the read path was written per owner and the write path targeted one constant record. If both were true, one identity's text would replace another's and both would be told it had worked. Decision: each identity holds its own record; a save under one identity never touches another's. Rationale: the contradiction was in the material from the first day and it decides whether the privacy rule means anything at all. Trade-offs: none worth recording at this size. Impact on product / architecture / QA: PRD sections 3 and 5; the write path; the regression check added on Day 11. Open questions: none. Links: DISCOVERY.md, contradiction 1. ## Day 9 - The refusal message names where the text is Context: two people were shown the prototype. Both read "Save failed" as "your text is gone", and one copied the text out of the field before doing anything else. Decision: the message says the text is still here and invites a retry. Rationale: the only question a person has at that moment is where their text is. Answering anything else is answering a question nobody asked. Trade-offs: a longer message in a small region. Impact on product / architecture / QA: the copy; PRD section 13, as a requirement derived from what testers said. Open questions: what happens to unsaved content when the tab is closed — raised by one of them, left open on purpose. Links: the Gate 3 showings. ## Day 11 - The write is keyed by its owner in the connected code Context: the control session found that the connected write still targeted the constant record id, so a save under the second identity replaced the author's confirmed content, and none of the three supplied checks caught it because none of them saves as the second identity. Decision: key the write by its owner, and add a regression check that saves as the second identity and then reads as the author. Rationale: the decision of Day 7 had been recorded and not implemented. A defect that no check catches comes back. Trade-offs: none. The three supplied checks were not touched. Impact on product / architecture / QA: the write path; the test file. Open questions: none. Links: the control session's Gate 5 finding, with its reproduction. ## Day 12 - Shipped without a review by the trades Context: the release note was prepared for the leads of the trades concerned. This exercise has no trades to convene, no staging and no production. Decision: the person who set the exercise gave the go-ahead alone, and the gap was written down rather than dressed up. Rationale: nobody should have to reconstruct later what was read before it went out. A gap named is the request made next time. Trade-offs: no independent technical reading of the change. Impact on product / architecture / QA: none on the product; it is the standing request to whoever would own the delivery path. Open questions: none. Links: the release note; the journal entry of the same date. ``` **Open questions.** What happens to unsaved content when the tab is closed. Whether a version history is ever wanted. Neither is being worked on. ### `docs/PROJECT_JOURNAL.md` ```text ## Day 4 - Gate 0, project folder Context: the case opened with a report of text lost after a save that appeared to succeed. Decision or change: one folder created; every source put in it; memory and journal created before anything else ran; project channel created with the people who would test later already in it. Implementation summary: the inventory and conversion prompt ran; converted files written to converted/; index written to converted/INDEX.md. Verification performed: read the index and the list of what could not be read. Originals untouched. Nothing sent anywhere. Trade-offs: eleven rows of the converted spreadsheet carry no date and were marked as undated rather than guessed at. Follow-ups: password obtained for one file and the prompt re-run on it; the screen recording watched and a one-paragraph note written beside it. Links: converted/INDEX.md. ## Day 5 - Gate 1, discovery and the first control pass Context: the material disagreed with itself about whether there is one record or one per author, and said nothing about what a denied read should answer. Decision or change: DISCOVERY.md written with the source list, the two contradictions, the three gaps, the hypothesis, the privacy risks and the constraints. Privacy established as a read-model rule. Implementation summary: none — nothing was changed in the application at this gate. Verification performed: ran the supplied acceptance checks to see the actual starting point: three failures, on the reload, on the refusal answer and on the direct read. Three errors instead would have meant the environment blocked the tests' own local server. Trade-offs: the contradictions were left unresolved here on purpose and carried to the alignment questions. Follow-ups: two alignment questions for Gate 2. Links: DISCOVERY.md; the control session's finding; the memory entry of the same date. ## Day 7 - Gate 2, the PRD Context: the alignment questions were answered, one of them against the default the prompt had proposed. Decision or change: one document written, its first section the strategic framing, fourteen sections, every assumption marked as an assumption. Implementation summary: none. Verification performed: read back section by section against DISCOVERY.md; each assumption traced to the source it rests on, or to what is missing and who decides it. Trade-offs: the tab-close question was left open rather than answered in passing. Follow-ups: the PRD is what every later prompt reads. Links: the PRD; the memory entries of Day 6 and Day 7. ## Day 8 - Gate 3, the absence of a design system recorded Context: there is no design system and no reference product for this exercise. Decision or change: the supplied application's own markup and the platform's default form controls stand in, agreed with the person who set the exercise. Implementation summary: named as a constraint in the design prompt. Verification performed: none to perform; this is a record, not a change. Trade-offs: nothing here demonstrates a design system, and the substitute is what the prototype and the code both follow so they stay the same product. Follow-ups: the components and their states, the tokens, what may be extended and who maintains it are on the standing request list. Nobody was invented to own them. Links: PRD section 8. ## Day 9 - Gate 3, what the showings changed Context: the prototype was shown twice to two people who write updates. Decision or change: the refusal message rewritten to name where the text is; the confirmation now names when it was confirmed. Implementation summary: in the prototype only; no code existed yet. Verification performed: second showing; both said it was the tool they needed, which is what closed the gate. Trade-offs: a longer message in a small region. Follow-ups: the tab-close question, left open. Links: the memory entry of the same date. ## Day 10 - Gate 4, the port, and one road that did not work Context: no approved starter and no written conventions exist for this exercise. The supplied application is the repository. Decision or change: the gap recorded with whose agreement the substitute was used; the PRD, memory and journal moved into docs/ inside the repository; every state ported against a service shaped like the store's contract. Implementation summary: confirmation and error split into two announced regions; copy pulled into one place; routes left thin; the mock service exposing the store's three operations by name. Verification performed: walked every state in a browser beside the design. The acceptance checks still failed on the same three assertions, which is what was expected with nothing connected. Trade-offs: the first port kept the message in a floating element, as the design showed. It is not announced when the surface re-renders on submission, so it was reverted to the page's own region. Recorded here because the reason is worth keeping, not because the attempt was wise. Follow-ups: the actions row wraps below a narrow width — drift from the design, deliberate. Links: the PRD; the design output. ## Day 11 - Gate 5, the store connected and the overwrite caught Context: the mock service was replaced with the store, flow by flow, in the same session. The checks were passing and the flows looked right. Decision or change: the write keyed by its owner; the refusal answered as a refusal; the ownership comparison moved into the query so that content an identity does not own never reaches the answer. Implementation summary: one write path, one read by owner, one read by id with the owner in the query; the refusal path carrying the submitted text, the error region, Retry, and no confirmation. Verification performed: the control session's reproduction walked by hand — save as the second identity, then read as the author — before and after the fix. The acceptance checks and the added regression check all passing. All four flows walked in a browser as both identities, including two refusals in a row and a reload between a refusal and its retry. Trade-offs: none worth recording at this size. Follow-ups: none. Links: the control session's finding; the memory entry of the same date. ## Day 12 - Gate 6, the test round and the release note Context: demo identities sent to two people who had not seen the build. Decision or change: three things fixed from what came back — the error region now names when the last confirmed save happened; Retry replaces Save while the refusal is showing; the actions row wraps on a narrow screen. One request declined, with the reason: the confirmation names the time and will not name a place, because that would be a claim about storage this product does not make. Implementation summary: copy and layout only. Verification performed: the acceptance checks and the regression check, all passing, run from the application's directory. Walked again in a browser after the fixes. Trade-offs: severities were never used, because there was never more coming back than the session could hold. Follow-ups: no frontend, backend or data lead read this change; there is no staging and no production; nothing was deployed, and the application stays on loopback. That gap is the request made next time. Links: the release note; the memory entry of the same date. ``` ## What this run did not have Worth naming plainly, because a worked example that hides its gaps teaches the wrong thing: - **No design system and no reference product.** A substitute was named, agreed and dated. The system itself is still a request with nobody to address it. - **No approved starter and no written conventions.** The supplied application's own constraints stood in. Nothing was invented that a reviewer would have had to undo. - **No backend service to ask.** The supplied module was the contract and the exercise's own notes were the documentation. - **No staging, no delivery path, no leads to give a go-ahead.** What could be verified was verified and written down; what was not reviewed was named, with who was not there to review it. Every one of those lines is a request with a name missing from it. That is what they are for: turning "this was harder than it should have been" into something specific enough to ask for. Text licensed CC BY 4.0. Code MIT. # Sandbox de prática Rota: /pt/resources/sandbox · Markdown: /pt/resources/sandbox.md [Baixar app.py](/downloads/sandbox/app.py) · [Baixar test_acceptance.py](/downloads/sandbox/test_acceptance.py) · [Baixar README.md](/downloads/sandbox/README.md) *O texto a seguir é o do kit, em inglês.* # Save draft — fictional first-run sandbox This local exercise gives a Product Builder one bounded outcome: **an author can recover a confirmed draft after returning, while a second user cannot read it**. A failed save must leave the edit visible in the current page with an error and Retry action; reloading before a successful retry restores only the last confirmed draft. The starter application is **intentionally incomplete**. Its acceptance tests are meant to fail at first. Do not call a green server startup, a design mockup, or a successful POST a completed product outcome. ## Requirements and run - Python 3.9 or newer (checked with 3.9.6, the version macOS ships). No package installation, external service, account, or internet connection is needed. - From this directory, run `python3 app.py` and open `http://127.0.0.1:8766/`. - Run the acceptance checks with `python3 -m unittest -v test_acceptance.py`. - The server binds to `127.0.0.1` only. It creates `sandbox.sqlite3` beside the app; delete that generated file to reset the manual exercise. Tests use a temporary database and do not touch the manual one. The only identities are **Avery Example** (`author`) and **Blair Example** (`reviewer`). They are fictional buttons backed by a local test cookie, **not real authentication**. There is no password or credential. This fixture is for practicing owner-specific behavior; a real product needs its organization's approved authentication and authorization design. Never deploy this server or put real user data into it. ## Starting evidence The database begins with one confirmed draft, ID `fictional-draft-001`, owned by Avery and containing “The imaginary library opens next Tuesday.” The direct read route is `GET /api/drafts/fictional-draft-001`. The form posts to `POST /save`. The **Simulate failed save** button sends `simulate_failure=1`, making the failure reproducible without an external service. Three deliberate defects make the exercise meaningful: 1. Save says “Saved” but does not persist the submitted text, so Avery cannot recover it after reload. 2. The direct read route returns Avery's draft to Blair, although the UI does not show it. 3. The failure switch causes a deterministic write failure inside the storage layer, but the handler swallows it. The response claims success, drops the edit from the current page, and offers no Retry. The three acceptance tests are written against the intended behavior, not the starter defects. Expect **3 failures** before implementation. Three *errors* instead mean the environment stopped the tests from starting their local server on `127.0.0.1`. **Running the tests from Codex.** Codex's default `workspace-write` sandbox blocks that local server, so the tests end in three `PermissionError` errors before reaching the intended failures. Allow network access for the session, for example `codex --sandbox workspace-write -c sandbox_workspace_write.network_access=true`, or run the test command yourself outside the sandbox. Checked with Codex CLI 0.155.0-alpha.9.2. A future passing test run checks the server behavior, but an independent reviewer should also inspect the running UI, including the error message, keyboard use, and narrow-screen state against an accepted design. ## Exercise task Use the [method core](/pt/resources/method-guide) and [first-case worksheet](/pt/resources/first-case#worksheet). Classify this synthetic case, write a bounded brief, identify the Design, Frontend, and Backend/API contributions, and record a human-reviewed design for empty, editing, saving, saved, failed, and return states. Check the available conventions and service routes; this tiny sandbox has no approved organizational frontend starter or production access path. Treat those as exercise gaps to record, not as permission to invent another organization's standards. After the design and capability decisions are recorded, implement the behavior inside this directory. Use the tests as acceptance evidence and inspect the rendered experience as both identities. Preserve Avery's last confirmed text when a save fails. Deny Blair through the direct endpoint as well as the interface. Report the exact behavior observed and leave the independent QA verdict to another reviewer. Deletion, expiration, offline edits, concurrent writers, and real authentication are outside this exercise. No public publishing or deployment is part of the run. # Inventariar e converter Rota: /pt/resources/prompt-inventory · Markdown: /pt/resources/prompt-inventory.md *O texto a seguir é o do kit, em inglês.* # Inventory and convert the project folder **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 0.** Run this first, in a session opened on the project folder. It converts what it can, indexes every source, and lists what it could not read. It interprets nothing. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Nothing. Paste it as it is. ## The text to copy ```text You are at Gate 0 of the method: setting up a new product project. The project folder is the one this session is opened on. Work only inside it. Do this, and nothing else: 1. Walk `sources/` and the top of the project folder, and list every file you find. Skip the assistant's own tooling — any dotted folder such as `.claude/`, `.agents/` or `.git/`, and everything inside it. Skip the project's own records too — `PROJECT_MEMORY.md`, `PROJECT_JOURNAL.md`, `prd-template.md`, `START-HERE.md` and `sources/README.md`. None of those are sources. 2. Everything that is a source belongs in `sources/`. A source sitting at the top of the project folder is moved in there, unchanged and unrenamed; that is the one move you may make. Then convert to Markdown everything you can convert, into the sub-folder `converted/`. Never modify, rename or overwrite an original. 3. Write `converted/INDEX.md`: one line per source, with the file name, what it is, and the date it is from. If you cannot date it, say so. 4. List everything you could not read or could not convert, and why. 5. Append one dated entry to `PROJECT_JOURNAL.md`: what you converted, what you could not read, and where the converted files are. Do not analyse the content. Do not draw conclusions. Do not write a PRD. Do not send anything anywhere — no service, no channel, no address. Report the index, the list of what you could not read, and where you put the converted files. Before you finish, state which gate you are at, what you have, what is missing, and what I must decide before you cross to the next gate. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Ler os canais Rota: /pt/resources/prompt-channel-reading · Markdown: /pt/resources/prompt-channel-reading.md *O texto a seguir é o do kit, em inglês.* # Have an agent read what nobody has time to read **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 1.** Ask for this by name when you want the channels or the client communications read. What comes back is input, not a decision. It ends by writing `DISCOVERY.md` in the project folder, which Gate 2 opens by name. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Two brackets to replace, brackets included. - `[name the channel, mailbox or thread, and the period]`, on the line that starts with “Read”: what the agent may read outside the project folder, and the dates, for example the support channel from March to August, or the client mailbox over the last six months. If there is nothing outside the folder, write “nothing outside the folder”: the prompt then works from the folder alone. - `[the product or the problem]`, a few lines further: what the reading is about, in a few words. ## The text to copy ```text You are at Gate 1 of the method: gathering the discovery. Read [name the channel, mailbox or thread, and the period]. If there is nothing outside the folder to read, say so and work from the converted folder alone; the rest of this prompt does not change. Then: - summarise what is being said about [the product or the problem]; - list what it confirms, what it contradicts, and what is new; - name the open questions it raises for the discovery. Then write `DISCOVERY.md` in the project folder, under these headings and no others: the source list, the ambiguity list, the questions for stakeholders, the hypothesis on the product boundary, the privacy and compliance risks, and the repository, starter and template constraints. Put under them what you read here and what the project folder already holds. Where a heading has nothing under it, say so rather than filling it. Gate 2 opens this file by name. Rules: - the project folder's own files are yours to read without asking: `converted/` and its index, `DISCOVERY.md`, the memory and the journal; - outside the project folder, read what I named above and nothing else: ask me before opening any other channel, mailbox, drive or thread, every time; - tell me exactly what you read; - keep names, addresses and personal details out of what you write down; - return findings, not decisions. I decide what is in scope. `DISCOVERY.md` stays current from here on. Each time I answer one of your questions, write what my answer settles into the file before you go on, and say in one line what you changed there — or why there was nothing to change. Do not hold it until the end of the conversation. Before you finish, append an entry to the project journal — what you read and what you wrote down — and add to the project memory only what is genuinely settled, if anything. Then state which gate you are at, what you have, what is missing, and what I must decide before you cross to Gate 2. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Analisar e escrever o PRD Rota: /pt/resources/prompt-prd · Markdown: /pt/resources/prompt-prd.md *O texto a seguir é o do kit, em inglês.* # Analyse the discovery and write the PRD **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 2.** The second prompt of the setup. It reads what Gate 0 and Gate 1 left in the folder and writes the PRD into the template saved there. Expect its alignment questions before the document: it stops for your answers rather than choosing a direction on its own. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Nothing. Paste it as it is: it reads the project folder only. To have it read something outside the folder, such as a channel or a mailbox, name it in the sentence that ends “is named here by me, or it is not read.” ## The text to copy ```text You are at Gate 2 of the method: writing the PRD. Read these, all of them in the project folder: - the converted folder `converted/` and its index `converted/INDEX.md`; - `DISCOVERY.md` in the project folder: the source list, the ambiguity list and the stakeholder questions written at Gate 1, including what an agent read on my behalf; - the project memory and the project journal; - the PRD template `prd-template.md`, saved into the project folder at Gate 0, for the shape of each section. Anything that is not in the project folder — a channel, a mailbox, client communications — is named here by me, or it is not read. First, state three things, separately: 1. what is established, and which source establishes it; 2. what contradicts what, source against source, without resolving it yourself; 3. what is absent — the questions this material does not answer. Then ask me the alignment questions. Where two sources point different ways, do not choose silently. For each one, give me: what source A says, what source B says, the product risk of choosing the wrong interpretation, the direction you would default to, and the confirmation you need from me. Then produce one document: the PRD, with these fourteen sections, in this order, and no others: 1. strategic framing — what the product is going to be, what is wanted and what is not, the boundary it holds, the business loop it serves; 2. product boundary; 3. roles and permissions; 4. core workflows; 5. product states and data visibility; 6. privacy and ethics rules; 7. which source wins when sources disagree; 8. design baseline and acceptable drift; 9. functional depth; 10. backlog taxonomy; 11. backend and API assumptions; 12. acceptance criteria; 13. the QA contract; 14. open decisions. Rules: - one document, not two: the strategic framing is the PRD's first section, and the sections after it detail what it states; - mark every assumption as an assumption, with the source it rests on or, when the material does not settle it, what is missing and who has to decide it; - invent no decision, no approval, no API and no standard; if it is not in the material, it is absent, and absent is an answer; - do not send anything anywhere — no service, no channel, no address. The PRD stays current from here on. Each time I answer one of your alignment questions, edit the sections my answer changes before you go on, and say in one line which sections you touched — or why none of them moved. Do not hold the document until the end of the conversation. Before you finish, write into the project memory every decision this gate settles — my answers to the alignment questions, each with its context, its trade-off and what it rules out — and append an entry to the project journal. Then state which gate you are at, what you have, what is missing, and what I must decide before you cross to Gate 3. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Prompt de design — especificação Rota: /pt/resources/prompt-design-specification · Markdown: /pt/resources/prompt-design-specification.md *O texto a seguir é o do kit, em inglês.* # The design prompt — long specification **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 3.** The specification the PM session writes for the design tool. It asks for end-to-end flows, not just the major screens. **This gate needs a design tool to close.** Any app-oriented design and prototyping tool works; the author uses Claude Design. What this prompt produces is the specification, not the prototype; a session with no design tool to prompt will write you a good brief and should tell you, in those words, that the gate has not closed. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Forty brackets, from the first line to the last sentence. You do not fill them by hand: the PM session — your coding agent — fills them when it writes the specification, from what you give it at Gate 3: the PRD, the discovery material, your organization's design system or a reference product, and the product boundary. Give it this text if it does not have it already. Where a bracket offers choices, it keeps the one that applies; where it names a kind of thing, it writes this product's own. Your part comes before the specification goes to the design tool, as the core guide's Gate 3 steps set out: read it, check that no bracket is left, and give it to the control session. ## The text to copy ```text Design a full high-fidelity web application prototype for [PRODUCT NAME], [ONE-SENTENCE PRODUCT DESCRIPTION]. This is a real logged-in [B2B SaaS / internal operations / marketplace / admin] application, not a landing page. Start directly inside the product experience. Treat the attached PRD — whose first section is the strategic framing — together with the research notes, source documents and design-system references, as what decides. If a linked source is gated or unavailable, work from the pasted content and do not invent a product decision that is missing. Design end-to-end flows, not only the major screens. Every flow listed below must be walkable from its entry point to its final state, including the intermediate steps, the branches, the failures and the confirmations. ## Strategic context [Why this product exists, the business loop it serves, the constraints around it.] This product helps [PRIMARY USERS] answer: 1. [CORE USER QUESTION] 2. [CORE USER QUESTION] 3. [CORE USER QUESTION] The product should feel like [PRODUCT METAPHOR: an operations workbench, a daily work console]. Calm, precise, structured, auditable, built for repeated daily work. ## Product boundary This product is for: - [ROLE / USER GROUP] - [ROLE / USER GROUP] This product is not for: - [OUT-OF-SCOPE USER / TEAM] Do not design: - [OUT-OF-SCOPE WORKFLOW] - [OUT-OF-SCOPE SCREEN] - [INTERNAL-ONLY OR SENSITIVE SURFACE] If an out-of-scope workflow exists, represent it only as a safe status, a handoff or a request state inside this product. ## Users and roles - [ROLE]: [what they do, what they need, what they can see] - [ROLE]: [what they do, what they need, what they can see] - [READ-ONLY / ADMIN / SUPERVISOR ROLE]: [permissions and constraints] Show role-based differences wherever they materially change navigation, actions, data visibility, disabled states or empty states. ## Core product principles 1. Lead with action, not decorative analytics. 2. Make the primary workflow usable end to end. 3. Keep sensitive data role-gated and explain visibility limits clearly. 4. Prefer tables, queues, drawers, modals, tabs, filters and audit trails over marketing-style layouts. 5. Make every clickable surface imply a real behavior. 6. Do not expose internal operational complexity to users who should only see safe statuses. 7. Use realistic data density and realistic edge cases. ## Navigation and shell Use a real app shell: navigation appropriate to the roles, page header, account or organization context, notifications, language toggle where relevant, account menu, settings and administration in the right place. Primary navigation: 1. [MAIN AREA] 2. [MAIN AREA] 3. [MAIN AREA] Do not repeat the product name as a large brand row inside every page header. The shell should feel like a daily-use operational product. ## Visual direction Use [YOUR ORGANIZATION'S DESIGN SYSTEM OR REFERENCE PRODUCT]. Treat it as a constraint, not as inspiration. Use: dense operational layouts; near-white app surfaces; soft neutral background; subtle borders; compact spacing; strong readable typography; text near black; accent colors only where they carry meaning; functional status colors; status badges, segmented controls, tabs, drawers, modals, tables, filters and forms. Avoid: landing pages; hero sections; decorative gradients that are not an established pattern; oversized marketing cards; generic analytics dashboards disconnected from action; playful consumer UI; explanatory filler text inside the product UI; one-off components that do not look reusable. ## Core data concepts Represent these naturally in the UI, with their real relationships rather than disconnected cards: - [ENTITY] - [STATUS / STATE MODEL] - [DOCUMENT / REQUEST / CASE / INVOICE / REPORT] - [AUDIT EVENT] - [PERMISSION / VISIBILITY LEVEL] ## Required screens and flows Design a coherent multi-screen prototype. Include the ones this product actually has, each walkable end to end. 1. Authentication and entry: [OTP / email code / passwordless / SSO], loading, invalid code, resend, successful transition. 2. Workbench: what needs attention now — work queues, recent changes, next actions, role-specific content. 3. Primary object directory: dense list or table for [the main entity], with search, filters, counters, row status and next action, primary and secondary actions, empty state, bulk or import/export where relevant. 4. Primary creation or submission flow: a guided modal, drawer or multi-step flow, not one long undifferentiated form. Include validation, missing required fields, back and next, save and resume later, review and submit. 5. Detail workspace: header, status and key metadata, tabs or sections, related records, documents, thread or comments, activity timeline, contextual actions. 6. Requests and communication: list, categories, status and priority, creation flow, detail thread, attachments, linked object, action-required state, resolved state. 7. Documents and records: repository, detail or preview and download behavior, filters, missing-document state, replace or re-upload, access restrictions. 8. Finance, billing or reporting where relevant: overview by period, invoices or ledger, payment status, reconciliation, downloadable documents, exception workflow. 9. Settings and administration: organization settings, users and roles, role descriptions, invite and deactivate, security settings, read-only states for users without permission. ## Interaction states to include Empty; loading; validation errors; missing required fields; pending, approved, rejected, needs information, overdue, resolved; disabled actions with a stated reason; role-restricted content; notifications; audit timeline; download and export; confirmation modals; destructive-action confirmation; success and failure feedback; side panels and drawers; dropdowns and profile menus. ## Privacy, security and visibility rules Respect: - [RULE] - [RULE] Do not expose: - [SENSITIVE DATA] - [INTERNAL NOTES] - [RAW EVIDENCE] If sensitive data is needed to complete a workflow, show the approved role-gated version, a safe status, or a path to request it. ## Content and mock data Language: [English-first / French-first / bilingual / other]. Currency: [currency]. Organizations, people, domain vocabulary, dates and identifiers should look real. Avoid lorem ipsum. Write real product copy. ## Output expectations A polished full-product exploration, not a single screen. Prioritize clear navigation, complete product vision, realistic workflow depth, strong table and list design, reusable patterns, role and privacy logic, real operational actions, and the modals, drawers, dropdowns, tabs, empty and error states the flows need. Someone reading the result should understand what [PRODUCT NAME] becomes as a complete product, and be able to walk each main flow from end to end. ``` # Prompt de design — instrução Rota: /pt/resources/prompt-design-instruction · Markdown: /pt/resources/prompt-design-instruction.md *O texto a seguir é o do kit, em inglês.* # The design prompt — short instruction layer **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 3.** What gets typed into the design tool alongside the long specification and the attachments. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Eleven brackets, from the first line to the last list. You do not fill them by hand: the PM session — your coding agent — fills them from the PRD when it writes the design prompt. Give it this text if it does not have it already. Before it goes to the design tool, read it and check that no bracket is left. ## The text to copy ```text Design [PRODUCT NAME], [SHORT PRODUCT DESCRIPTION]. Use the attached design system and product documents as source material. Treat the long design prompt as the full specification and this short prompt as the instruction layer. Do not create a landing page or a concept dashboard. Start with the real product experience: [PRIMARY WORK SURFACE], [SECONDARY WORK SURFACE], [DETAIL WORKSPACE], [DEEPEST WORKFLOW]. Design deeply across the product, not only the top-level pages. Include states, variants, drawers, modals, empty, error and loading states, permission-restricted states, audit views, escalation, handoff, and safe output previews where relevant. Each main flow must be walkable end to end. Core UX: - [PRINCIPLE] - [PRINCIPLE] Must include: - [SURFACE / FLOW] - [CRITICAL STATE MODEL] - [ROLE / PERMISSION VARIANTS] Use compact, calm, high-density operational UI. Make it feel production-ready, not like a presentation. ``` # Prompt de refinamento Rota: /pt/resources/prompt-refinement · Markdown: /pt/resources/prompt-refinement.md *O texto a seguir é o do kit, em inglês.* # The refinement prompt **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 3.** Use it when the first output is too shallow, too conceptual or too dashboard-like. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Nothing. Paste it as it is. If you design against a reference product because the design system has not arrived yet, write “reference product” for “design system” in its last line. ## The text to copy ```text Refine this into a denser operational product. Prioritize daily user work over executive analytics. The primary workflow should be obvious on the first screen. Remove any marketing-style hero, oversized explanatory card or decorative section. Increase depth: - make status, owner, next action, date, priority and permission state visible where they matter; - make the main workflow usable end to end, including its intermediate steps and its failures; - add the missing drawers, modals, dropdowns, error, empty and confirmation states; - make history and audit easy to inspect; - make document and request workflows feel functional; - make role-gated and restricted states explicit; - use realistic data and realistic edge cases; - keep the design aligned with the attached design system. ``` # Levar o protótipo para o código Rota: /pt/resources/prompt-port · Markdown: /pt/resources/prompt-port.md *O texto a seguir é o do kit, em inglês.* # Port the prototype into code **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 4.** Hand the prototype and the starter to the coding agent, and keep it inside your organization's conventions. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Three brackets to replace, brackets included. - `[PRODUCT / SLICE]`, on the second line: the product, or the part of it this session is building. - `[WHO THE PRODUCT IS FOR, …]`, under “Product boundary”: from the PRD, who the product is for, who it is not for, and what must not be built here. - `[THE FLOW, SCREEN OR FIX]`, under “Current task”: the one piece of work for this run. ## The text to copy ```text You are at Gate 4 of the method: porting the prototype into code. You are implementing [PRODUCT / SLICE]. Read before coding: - the prototype from Gate 3, in the form it was handed to you - the PRD, whose first section is the strategic framing - the approved frontend starter repository and its conventions - the backend conventions - the project memory and journal Product boundary: [WHO THE PRODUCT IS FOR, WHO IT IS NOT FOR, AND WHAT MUST NOT BE BUILT HERE] Rules: - the prototype is the visual and product reference; - the starter repository and its conventions decide how the code is written; - do not paste the design tool's export into the application foundation; - keep routes thin; - put domain logic in feature folders; - use the organization's shared primitives before creating anything new; - route mock data through API-shaped services that match the future backend contracts; - centralize copy and localization; - enforce role and privacy rules at the read-model level; - do not redesign anything unless you are explicitly asked to; - before each change to the code, re-read the starter's rules and the backend conventions. Current task: [THE FLOW, SCREEN OR FIX] Acceptance criteria: - the flow works end to end in the front-end mock; - the result matches the design where the design is non-negotiable; - no privacy regression; - relevant tests added or updated; - project memory and journal updated if this changed product behavior, architecture, a stakeholder decision or future reasoning. Run before finishing: - typecheck - lint - tests - build - click through the flow in a browser Report: - which gate you are at, what you have, what is missing, and what I must decide before you cross; saying what you will do next is not permission to do it, so you cross when I answer, not when you announce - what changed - what you actually ran and what it returned - memory and journal updates made, or explicitly skipped with the reason - remaining open product or backend decisions ``` # Convenções de backend observadas Rota: /pt/resources/prompt-observed-conventions · Markdown: /pt/resources/prompt-observed-conventions.md *O texto a seguir é o do kit, em inglês.* # Describe the backend conventions the code already follows **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 4.** When the backend has code but no written conventions. The agent describes the conventions the code already follows — a recipe for the most common change, each rule with its examples and its count, what is deprecated, the questions only the owner can answer — and the backend owner confirms them, corrects them, or marks what must not be copied. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Four brackets to replace, brackets included — three things to fill, since the backend owner appears twice. - `[THE BACKEND REPOSITORY]`, near the top: the path of a fresh clone of the backend, made beside the project repository from where your organization keeps it. A fresh clone carries nobody's keys; a developer's own copy may. Run the prompt in a mode of your assistant that asks before it runs a command or writes outside the project repository. - `[ANYTHING IN IT THAT IS OFF LIMITS, …]`, the next line: folders or files it must not open even to read — ask the backend owner. If you cannot yet, replace the bracket with “nothing more”: the prompt already keeps the agent out of keys, environment files and data. - `[THE BACKEND OWNER]`, twice, near the end: the person or team who reviews backend work; Backend and API Ops can name them. Not you: a Product Builder cannot tell a convention from a debt, and is not asked to. If there is no backend owner, name the lead accountable for engineering, and read the core guide's Gate 4 before you run it. Two files come back in `docs/`. Send the draft to the backend owner. Send the security notes to the backend owner alone, never into the channel and never into a commit, then delete them from the repository. ## The text to copy ```text You are at Gate 4 of the method. The backend has code but no written conventions. Your job is to describe the conventions the code actually follows. You do not decide them. You may read, and only read: [THE BACKEND REPOSITORY]. Do not open, even to read: [ANYTHING IN IT THAT IS OFF LIMITS, or "nothing more"]. Run nothing from the backend repository: no install, build, test, script or migration. Reading the code and its history is enough. Do not change anything in it, and write nothing outside the project repository — not even a helper script. Do not open environment files, key or certificate files, infrastructure state, database dumps or exported data. Answer where secrets and configuration live from the code that loads them, not from the files that hold them. If a value that looks secret appears anyway, give the file and line, never the value. Start from what the team already enforces or wrote down: linter and formatter configuration, CI checks, the pull-request template, the README, contributing notes, architecture decision records, release and upgrade notes. Then read the code. First, the recipe. Take the most common kind of change — usually a new model, field or endpoint — and describe how the code makes one, end to end: the base classes it uses, every file a change of that kind touches, in order, and the one or two existing examples to copy. If there are several common kinds, give a recipe for each. Then answer, at the least, these questions: - where code goes, and how it is layered - how input is validated where it enters, and how errors, timeouts and retries are handled on the server - how the data model changes, and how a migration is written so that the version still running keeps working during a deploy and after a rollback - how an API contract is documented, changed and versioned - how a request that arrives twice is kept from doing the work twice - how transactions and concurrent writes are handled - where work that does not finish inside the request goes, and how it is retried - how permissions are checked, on writes as well as on reads - where secrets and configuration live - what the code logs and measures, and what it avoids logging - what response times and load it is built for, if anything says so - how environments and infrastructure are described and changed - how dependencies are added - which tests exist, and at which level - what security checks exist - how unfinished work ships switched off, and how a release is rolled back For each point, write: - the rule, as one sentence a change can be checked against - one or two real examples: the file and the line - the basis: how many places you looked at, how many follow it, and how you counted — a class counts when any of its bases matches, not only the first - whether it is enforced by a tool, followed without enforcement, or inconsistent — and whether recent and older code differ - "Status: observed". Only the backend owner changes it, to confirmed, corrected, or debt not to copy. Anything the code or the notes mark as deprecated, legacy or scheduled for removal is never a rule: list it under "Deprecated — do not copy", with what replaces it when something does. Put first the questions the backend owner must answer before anyone builds on this: no more than ten, ranked by what they would block. Leave out what the code or the notes already answer. Do not settle them yourself. Write the result in the project repository, never in the backend repository: `docs/backend-conventions.observed.md`. Its first line says: "Observed, not approved — a draft for [THE BACKEND OWNER] to confirm, correct, or mark as debt not to copy." What could be a security weakness does not go in that file, which will circulate: write it to `docs/backend-security-notes.md`, for [THE BACKEND OWNER] only, and say in the draft that such notes exist, without their content. Then stop: what you wrote is not a convention until the backend owner confirms it. Append an entry to the project journal saying what you read and what you wrote, without the content of the security notes. State which gate you are at, what you have, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Antecipar as necessidades de backend Rota: /pt/resources/prompt-backend-requests · Markdown: /pt/resources/prompt-backend-requests.md *O texto a seguir é o do kit, em inglês.* # List what the backend work will need from other teams **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 4.** While the port runs, the backend waits: the time to ask for what the backend work will need from other people — access to a platform, a permission, a key, a resource, a change that needs rights you do not have. The agent lists those needs flow by flow, as requests ready to send, so that you ask now and are not blocked for days at Gate 5 waiting for someone who is busy elsewhere. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Two brackets to replace, brackets included. - `[THE FLOWS, IN THE ORDER YOU WILL CONNECT THEM]`, under “The flows Gate 5 will connect”: the flows from the PRD, the one you will connect first at the top. The order sets the urgency: what the first flow needs is asked for first. - `[WHAT YOU HAVE ACCESS TO, …]`, under “What I can already do myself”: the platforms, consoles, environments and tools you can already use, and with which rights. If you do not know, write “I do not know”: the agent marks what it cannot tell “to confirm” and asks you about those points together, once, instead of guessing — and it never tries a platform or your credentials to find out. One file comes back: `docs/backend-requests.md`. Answer what it marks “to confirm” first: what you already have comes off the list. Then send each request as a ticket, in that team's own tool, to the person it names — where it says “owner to find”, ask the Ops owner of that service who handles it. Write the ticket's reference next to the request: at Gate 5 the agent re-reads the file before each flow. Running the prompt again adds to the file and keeps what is there. ## The text to copy ```text You are at Gate 4 of the method. While the port runs, the backend waits. Use that time to find out what the backend work will need from people other than me, so that I ask for it now, not on the day I am blocked. Read: - the PRD, its flows, and section 11, the backend and API assumptions - the backend conventions, and the backend code if there is any - what was built ahead during Gate 3, if anything was, and the needs it already raised in the journal - `docs/backend-requests.md`, if it exists - the project memory and journal The flows Gate 5 will connect, in this order: [THE FLOWS, IN THE ORDER YOU WILL CONNECT THEM] What I can already do myself — the platforms, consoles, environments and tools I have access to, and with which rights: [WHAT YOU HAVE ACCESS TO, or "I do not know"] For each flow, in that order, list everything the backend work will need that I cannot do myself: access to a platform or a console; a permission or a role; a key, a secret or a service account; a resource to create, such as a database, a queue, a storage bucket or a domain; a change that needs rights I do not have, such as a migration, a network rule or a setting in a shared environment; a deployment; an account with an outside service; an API that does not exist yet. Section 11 of the PRD already lists what to request from Ops: take in what it lists that nobody has asked for yet, marked as coming from there, so that one list holds every request. Read only. Change no code, the front's or the backend's, and run nothing: no sign-in, no command or request against a platform, an environment or an API, no look at my credentials or at my tools' settings to find out what I can do. Do not open environment, key or certificate files; tell what a secret is for from the code that loads it. Where you cannot tell whether I already have something, mark it "to confirm", and ask me about all of them together, at the end. Write each need as a request ready to send: - what is needed, in one sentence the person can act on: in which environment, and no more access than the work needs - for which flow, and why: what in the PRD, the conventions or the code shows it is needed - when it is needed: the first flow it holds up; I add the date - for how long, if it is not for good - who can do it, if the PRD, the conventions or the memory say so; otherwise "owner to find" - what I can move forward meanwhile, if anything - the ticket: left empty, for me to fill in when I send it Where a key or a secret is needed, ask for it to come the way that team hands secrets over, never in the ticket. Group the requests by who can do them, the earliest needed first. Write them to `docs/backend-requests.md`; if the file exists, add to it and keep what is there, ticket references included. No secret value, there or anywhere else. Send nothing anywhere: I send the requests myself, as tickets, in each team's own tool. Then append an entry to the project journal saying what you listed and what is still to confirm. State which gate you are at, what you have, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Conectar o backend Rota: /pt/resources/prompt-connect · Markdown: /pt/resources/prompt-connect.md *O texto a seguir é o do kit, em inglês.* # Connect the backend to the front end **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 5.** The longest gate. The flows have to hold in depth, not on the surface. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in One bracket to replace, brackets included: `[ONE FLOW, END TO END]`, under “Current task”: the one flow this run connects to the real backend, from its entry point to its final state. ## The text to copy ```text You are at Gate 5 of the method: connecting the backend. Before coding, read: - the PRD, whose first section is the strategic framing - your frontend starter rules and conventions - your backend conventions - `docs/backend-requests.md`, the requests sent ahead, if there are any; if this flow waits on one nobody has answered yet, stop and tell me, and do not work around it - the project memory and journal Current task: [ONE FLOW, END TO END] Acceptance criteria: - the user-facing flow works end to end against the real backend - empty, loading, error and permission-denied states are handled, and so are the slow response, the record that already exists and the value that arrives malformed - the change meets the backend conventions, checked point by point - no privacy regression - relevant tests are added or updated - project memory and journal are updated if the work changes product behavior, architecture, stakeholder decisions, or future reasoning Run before finishing: - typecheck - lint - tests - build - diff check - the checks the backend conventions name - the slow response, the record that already exists and the malformed value, produced against the API itself, in tests or direct calls, since a browser rarely sends them - walk the connected flow in a browser, end to end, including its empty, error and permission-denied states Report which gate you are at, what is missing, what I must decide before you cross, what changed, what was verified, the backend conventions point by point — met, with its evidence; not applicable, with why; or not checked, with why — any need from another team this flow revealed, written into `docs/backend-requests.md` as a request, and any remaining product or backend decision. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Preparar a entrada em produção Rota: /pt/resources/prompt-release · Markdown: /pt/resources/prompt-release.md *O texto a seguir é o do kit, em inglês.* # Prepare a release for the leads **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 6.** What has been tested, by whom, with which accounts, what is known to be broken, and what the leads are asked to approve. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Nothing. Paste it as it is. ## The text to copy ```text You are at Gate 6 of the method: test, then ship. Read before you write anything: - the PRD, whose first section is the strategic framing - the project memory and the project journal - what changed in the repository since the last release Prepare the release note for the leads of the trades concerned — engineering, backend, frontend, data. State these, and invent none of them: - what is in this release, flow by flow; - what has been tested, by whom, and with which accounts — demo accounts or real ones; - what was verified and how: the flows walked end to end, the empty, error and permission-denied states exercised, the checks that were run and what they returned; - what is known to be broken or unfinished, and where it is being tracked; - what the leads are being asked to give the go-ahead on; - which review did not take place, if one could not, and who was not there to give it. If something was not tested, say it was not tested. A gap named is the request I make next time. Do not send anything anywhere — no service, no channel, no address. Before you finish, state which gate you are at, what you have, what is missing, and what I must decide before this goes to production. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Sessão de controle Rota: /pt/resources/prompt-control-session · Markdown: /pt/resources/prompt-control-session.md *O texto a seguir é o do kit, em inglês.* # Starting prompt for a control session **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Across every gate.** The second session, the one that challenges. It reads, checks and challenges; it does not change code, decide scope, or write the PRD or the prompts. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Five brackets, and the last one closes the text: scroll to the end before you send it. None stays as it is, and the square brackets go in every case. - `[PRODUCT]`, on the first line: the product's name. - `[GATE]`, on the first line: the gate the work is at, from Gate 0 to Gate 6. - `[ONE AREA: …]`, in the middle: the one area you want checked now. Keep that area, naming the flow, the change or the bug when it is one, and delete the rest of the bracket. When you open this session at Gate 0 there is nothing to check yet: ask it instead for a small, harmless finding sent to the main session, which is the check the core guide asks for before you rely on the last bracket. - `[once defects are being tracked …]`, near the end: keep this item, without its brackets, once there are more defects than a session can hold and you track them instead of fixing them as they appear. Until then, delete the whole item, dash included. - `[the name of the main session …]`, the last lines: replace its first sentence with how your assistant addresses the main session — in Claude Code, the name it carries in the sidebar; in Codex, its session ID, where your setup lets one session address another by it. Keep its last sentence, without the brackets: it says what happens when a finding cannot land. This is what lets the control session send its findings to the main session; check it once with a small finding and watch it arrive. ## The text to copy ```text You are the control session for [PRODUCT]. The work is at [GATE]. Your job is to read, check and challenge the work of the main session. Do not trust its claims. Check them against the material. Read what exists at this gate, and nothing that does not: - the discovery material in the project folder, and `DISCOVERY.md` once Gate 1 has written it - the project memory and the project journal - from Gate 2 onward, the PRD, whose first section is the strategic framing, and the product decisions - from Gate 3 onward, the design the front end is ported from - from Gate 4 onward, the repository, the frontend starter's rules and the backend conventions Tell me what you read, and what did not exist yet at this gate. What I am asking you to check now: [ONE AREA: the discovery findings / the PRD / its strategic framing / the design specification before it is sent / what was ported from the design / a backend flow / a backend change against the backend conventions / a bug] Rules, which do not change between runs: - you read, check and challenge - you do not change code - you do not decide scope - you do not write the PRD and you do not write the prompts - you return findings with their evidence, and I decide Return: - which gate the work is at, what it has, what is missing, and what I must decide before it crosses - each finding with the evidence it rests on: the file, the screen, the flow, the section of the PRD, the steps that reproduce it - what you could not check, and why - product decisions separated from defects - [once defects are being tracked rather than fixed as they appear, mark each finding P0, P1 or P2] When you observe something, send it to the main session as well as to me: [the name of the main session, as your assistant lists the sessions running beside it — in Claude Code, the name that session carries in the sidebar. If you cannot reach it, hand the finding to me and I will relay it unchanged] ``` # Restrição permanente Rota: /pt/resources/prompt-standing-constraint · Markdown: /pt/resources/prompt-standing-constraint.md *O texto a seguir é o do kit, em inglês.* # The standing constraint **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Every gate.** Carry this in every prompt that changes code. It is what keeps the memory, the journal, the PRD and the gate position current. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## What you fill in Nothing. Carry it as it is in every prompt that changes code. ## The text to copy ```text If your work changes product behavior, architecture, a stakeholder decision or future reasoning, update the project memory, the project journal and the PRD. Memory holds the decisions and their trade-offs; the journal holds the chronological record; the PRD describes the product as it now is, so a change that makes one of its sections wrong is a change that edits that section. Do not log small cosmetic changes unless they affect product direction or demo readiness. Before finishing, state whether memory, journal and PRD were updated, or why no update was needed, and state which gate you are at, what is missing, and what I must decide before you cross. Saying what you will do next is not permission to do it: you cross when I answer, not when you announce. ``` # Modelo de PRD Rota: /pt/resources/prd-template · Markdown: /pt/resources/prd-template.md [Baixar prd-template.md](/downloads/prd-template.md) *O texto a seguir é o do kit, em inglês.* # Product requirements document — the template **A method by Alexis Boyer · version 4.0 · September 22, 2026** Gate 2 fills this template; the filled PRD lives in the project folder beside the project memory and the project journal and moves into `docs/` with them when the code starts, and it is what the coding agent reads at every gate after this one. ## 1. Strategic framing *In a few lines, say what the product is going to be: what is wanted, what is not wanted, the boundary it holds and the business loop it serves.* - What this product is going to be: - What is wanted from it: - What is explicitly not wanted: - The business loop it serves: - The constraints that shape it: - What the sections below detail: ## 2. Product boundary *Draw the line around the product: who it serves, what belongs elsewhere, and what it must never expose.* - Who the product is for: - Who it is not for: - Workflows that belong in another product: - What the product must never expose: - Shared core or backend objects assumed: - Non-goals: - How an out-of-scope workflow is represented here instead (safe status, handoff, request state): ## 3. Roles and permissions *Write out every role, including two roles that differ by a single screen.* | Role | What they do | What they can see | What they must not see | What they can do | | --- | --- | --- | --- | --- | | | | | | | | | | | | | - Where role differences change navigation, actions, disabled states or empty states: - How a role is granted, changed and removed: ## 4. Core workflows *List each workflow the product exists to carry, from its entry point to its final state.* - Workflow: - Who runs it: - Entry point: - Steps: - Branches: - Failures and how they end: - Confirmations: - Final state: ## 5. Product states and data visibility *Name the states each object moves through, what moves it, and what is visible in each state to each role.* - Object: - Its states, in order: - What moves it from one state to the next: - Terminal states, and what reopens them: - What each role sees in each state: - What is hidden in each state, and from whom: ## 6. Privacy and ethics rules *Say which data is sensitive and how it must be handled; this controls the interface, the data model, search, exports, backend read models and QA.* - Sensitive data held or displayed here: - How each kind must be handled: - What must never be shown, and to whom: - Rules for search, filters and exports: - Rules for what may reach the browser at all: - Controlled exceptions, with the fields each one is allowed: - The intake path for a request to see sensitive data: - Retention and deletion expectations: ## 7. Which source wins when sources disagree *Write the order down, most authoritative first, so an agent does not overfit to an outdated document.* 1. 2. 3. 4. 5. 6. - What must be checked before an old backlog ticket is used: - Who records a change to this order, and where: ## 8. Design baseline and acceptable drift *Name the design reference this product follows and the drift that is acceptable; the design itself arrives at Gate 3, so state here what is assumed and what must be requested.* Assumed now: - The design reference this product follows (design system, or a named reference product standing in for one): - Its version or location, as known today: - What counts as non-negotiable in it: - What counts as acceptable drift from it: - Where the prototype and the front end must draw on the same reference: To request from Design Ops: - The components and their states: - The tokens and the rules for using them: - What may be extended and what may not: - Who maintains the system: - An agent-readable form of the above: - The named owner of each request, and the date the answer is needed: - What is being followed in the meantime, and with whose agreement: ## 9. Functional depth *Say which flows must really work in the front-only prototype and which may stay placeholders.* - Flows that must work end to end in the front-only prototype: - Flows that may stay placeholders, scoped on purpose: - What each clickable surface does, where a user can click it: - Simulated states deliberately allowed, and their limits: - States required everywhere: empty, loading, validation error, permission-denied, confirmation, success and failure: ## 10. Backlog taxonomy *Keep these categories apart, so an undecided question is not coded around as if it were a defect.* | Category | What belongs in it here | Where it is tracked | Who owns it | | --- | --- | --- | --- | | Product decisions | | | | | Implementation tasks | | | | | Design parity issues | | | | | Privacy and legal guardrails | | | | | QA findings | | | | | Backend integration work | | | | | Future nice-to-haves | | | | ## 11. Backend and API assumptions *Separate what this product assumes the backend already does from what has to be requested, since the contracts are obtained at Gate 4 and the connection is made at Gate 5.* Assumed now: - Backend objects, state machines and workflow contracts assumed: - Authentication and permission rules assumed: - The business meaning of key fields and status values, as understood here: - APIs believed to exist and used by these flows: - The shape the front end's mock services will follow until the real contracts arrive: To request from Backend and API Ops: - The API catalog with real examples: - Request and response shapes, errors and versioning, for each API used here: - Confirmation of the business meaning of key fields and status values: - Reference patterns for authentication, migrations and tests: - A test environment with test identities and safe data: - Read-only access to logs, errors and health, and who to reach when something breaks: - APIs that do not exist yet, raised through the written request route: - The backend conventions, opening with the recipe for the most common changes, written as criteria a change can be checked against, with how each is checked, in a version an agent can re-read: - Who reviews backend work, and how fast: - The named owner of each request, and the date the answer is needed: To request from Frontend Ops, where these flows depend on it: - The approved starter repository, its current version, its owner and how to start it: - The API client pattern, authentication, error handling and loading states: - The checks required on a deployable branch, and the preview or environment path: - The named owner of each request, and the date the answer is needed: ## 12. Acceptance criteria *Per flow, say what has to be true before it counts as done.* - Flow: - Works end to end, against the mock services and then against the real backend: - Empty, loading, error and permission-denied states handled: - Matches the design reference where that reference is non-negotiable, within the drift accepted in section 8: - No privacy regression: - Tests added or updated: - Checks to run before finishing (typecheck, lint, tests, build, walk the flow in a browser): - Memory and journal updated when product behaviour, architecture, a stakeholder decision or future reasoning changed: ## 13. The QA contract *Say how this product gets checked, so the check is not invented at the end.* - Personas to test: - Role-based privacy checks: - Requirements derived from transcripts: - Regression flows: - Validation commands: - Expected report format: - Severity meanings in use, and when defects start being tracked rather than fixed as they appear: ## 14. Open decisions *One row per decision: its alignment question states what one source says, what the other says and the product risk of choosing wrong; who decides is a person, not a team.* | Decision | Alignment question behind it | Default proposed | Who decides | By when | | --- | --- | --- | --- | --- | | | | | | | | | | | | | | | | | | | Text licensed CC BY 4.0. Code MIT. # Memória do projeto — entrada Rota: /pt/resources/memory-entry · Markdown: /pt/resources/memory-entry.md [Baixar memory-entry.md](/downloads/memory-entry.md) *O texto a seguir é o do kit, em inglês.* # Project memory — one entry **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 0, then every gate.** One entry of `PROJECT_MEMORY.md`. The memory answers where the product stands today; its entries are dated and a replaced decision stays readable. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## The text to copy ```text ## [Date] - [Decision or topic] Context: Decision: Rationale: Trade-offs: Impact on product / architecture / QA: Open questions: Links: ``` # Diário do projeto — entrada Rota: /pt/resources/journal-entry · Markdown: /pt/resources/journal-entry.md [Baixar journal-entry.md](/downloads/journal-entry.md) *O texto a seguir é o do kit, em inglês.* # Project journal — one entry **A method by Alexis Boyer · version 4.0 · September 22, 2026** **Gate 0, then every gate.** One entry of `PROJECT_JOURNAL.md`. The journal is dated and never rewritten, including what turned out to be wrong. It is quoted here exactly as it appears in [the core guide](/pt/resources/method-guide). ## The text to copy ```text ## [Date] - [Workstream or session] Context: Decision or change: Implementation summary: Verification performed: Trade-offs: Follow-ups: Links: ``` # Skill do Claude Code Rota: /pt/resources/claude-code-skill · Markdown: /pt/resources/claude-code-skill.md [Baixar a pasta do projeto](/downloads/onirion-project.zip) *O texto a seguir é o do kit, em inglês.* # Onirion · Claude Code adapter **A method by Alexis Boyer · version 4.0 · September 22, 2026** This file covers one thing: running the method in Claude Code. Installation, how a session knows which gate it is at, and how to run the main session and the control session side by side. The method itself is in the [core guide](/pt/resources/method-guide). Nothing here changes it — the gates, what each one demands and what ends it are the same whatever assistant you use. ## There is nothing to install The project folder you download already carries the skill, at `.claude/skills/onirion/`, with the core guide, the thirteen prompts and the templates inside its own `references/` folder. It depends on the kit folder, on another skill and on no machine but yours. Open a Claude Code session on that folder and ask for the method in words — "Apply the Onirion method to this folder" — which works whatever the version. Typing `/onirion` is a shortcut where the version offers it; a session that answers that the command is unknown has not lost the skill, it just does not expose it that way. Claude Code discovers project skills under `.claude/skills/`. If the skill is not listed, restart the session, then open `.claude/skills/onirion/SKILL.md` and its `references/` folder and check they are there. Claude Code's [skills documentation](https://code.claude.com/docs/en/skills) describes project-skill discovery. Folders that start with a dot are hidden by default: in the Finder, press Command-Shift-Period to see them. **To carry the method into another project** — the repository you clone at Gate 4, or a project you started before you met this method — copy the two skill folders across: ```sh cp -R .claude .agents /absolute/path/to/your-project/ ``` That is the whole installation. Nothing else in the target project is touched, and an existing skill of the same name is overwritten, so look before you copy. ## Start a project at Gate 0 At Gate 0 there is no repository. There is a folder of sources: one folder created for the project, holding every document the work will draw on. Claude Code opens on a directory, not on a repository, so that folder is enough to start. Nothing has to build and nothing has to run. 1. Create the project folder and put the documents in it. 2. Run the installer with that folder as the project. The skill lands in `.claude/skills/` inside it. 3. Create `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` in the folder, before the first prompt runs, and save the PRD template beside them as `prd-template.md`. 4. Open a Claude Code session on the folder and ask it to apply the Onirion method, or type `/onirion` where that works. 5. Paste the inventory and conversion prompt from Gate 0 of the core guide. That prompt writes the converted files into `converted/` and the index into `converted/INDEX.md`. It never modifies an original, and it sends nothing anywhere. Read the index it returns and the list of what it could not read, and fill the obvious holes while they are cheap. **At Gate 4 the project moves.** The repository is a new folder beside the folder of sources, cloned from your organization's approved frontend starter. Run the installer again, with the repository as the project, so the skill is there too. Then repoint your session at the repository and move the PRD, `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` into it under `docs/`. From that point the repository is where both sessions work. ## How the session knows which gate it is at The skill holds no state of its own. It knows where the work stands because it reads the folder it is opened on, and because you make it say so out loud. **The files are the evidence.** `converted/INDEX.md` exists, so Gate 0 ran. `DISCOVERY.md` exists, with its source list, ambiguity list and stakeholder questions, so Gate 1 is written down. A PRD whose first section is the strategic framing, so Gate 2 produced something. A repository with a front end you can run, so Gate 4 is under way. This is also why the guide insists that findings be written into named files: a finding left in a chat window is a finding the next session cannot read. **Every prompt ends the same way.** Each prompt in the core guide closes by asking the session to state which gate it is at, what it has in hand, what is missing, and what you must decide before it crosses. Ask for it at the start of every session, and ask for it again at every gate. "I am at Gate 3" is the shape of it, followed by the three answers. **It asks before it crosses.** The session does not walk through a gate on its own. It names what you have to decide and it stops there. Answer, and it goes on. A session that cannot say where it is has left the method, and it is about to cross a gate you have not closed — point it back at the files and make it answer before anything else. Sessions do not remember. A new session, or one that has been running long enough to lose the early context, re-reads the memory, the journal, the PRD and the discovery, and states its gate again from what it found. That is the job those files do. ## Run the two sessions This is the part of the method this adapter exists for. The main session builds. The control session challenges it: it reads, checks and challenges, it does not change code, it does not decide scope, it does not write the PRD or the prompts, and it returns findings with their evidence. You decide. ### Open the second session Open a second Claude Code session on the same project — the folder of sources up to Gate 3, the repository from Gate 4. A second terminal window or tab, or a second session in the app; either works. Same project matters: both sessions then read the same memory, the same journal, the same PRD, the same repository, so a finding can point at a file and the other session can open it. The skill is a project skill, so the second session already has it. Ask for the method there as well, the same way. Two sessions, and only two. Do not open several building sessions at once on different parts of the code — their scopes overlap and what comes out of that is bugs. ### Give it the control-session prompt Paste the control-session starting prompt from the core guide and fill the brackets: the product, the gate the work is at, and the one area you want checked — the discovery findings, the PRD, its strategic framing, the design specification before it is sent, what was ported from the design, a backend flow, a backend change against the backend conventions, a bug. Keep the rules block unchanged between runs. Those rules are the whole harness. Nothing in the tool stops a session from editing files, so the limit is the one you wrote down. Restate it the moment the session starts proposing instead of reporting, or starts rewriting the PRD, or starts writing prompts for the main session. What you should be getting back is findings with evidence — the file, the screen, the flow, the PRD section, the steps that reproduce it — not diffs. You can reopen the same control session later instead of starting over. In the CLI, `claude --resume` reopens a session, and session transcripts live on disk under `~/.claude/projects/`. Resuming keeps the rules block and everything the session already checked. ### How a finding gets from one session to the other **The sessions address each other.** Claude Code sessions running on the same machine can list one another and send a message to one another by name, where it arrives as a turn in the target session. So the control session sends its finding to the main session itself, and the instruction in the last bracket of its prompt is the whole of the wiring: name the main session there, the way your Claude Code lists it. You tell the main session where the work stands and to ask the control session for its report and its answer back; both sessions do the carrying. **Naming the other session is the whole of the wiring.** Each session carries a name, the one you see in the sidebar, and that name is its address. Put the main session's name in the last bracket of the control session's starting prompt, and its findings arrive there as turns. Nothing else is configured. **Check it once, then rely on it.** Ask for a small, harmless finding and watch it arrive in the other session before you trust the channel with something that matters. Then have the main session open the evidence itself rather than act on the summary. **Both sessions stay open.** A message sent to a session that has been closed goes nowhere, and nothing tells you so. If the two sessions run in different permission modes, the receiving one may hold the message until you approve it: a finding that looks lost is worth looking for in the other window first. **The fallback, when a message cannot land.** Copy the finding out of the control session and paste it into the main session, unchanged, and say where it came from. That costs a paste and depends on nothing. It is what the last bracket falls back to — *if it cannot, hand it to me and I will relay it unchanged* — and it is a fallback, not the method. What does not change either way: the control session states what it found and what the evidence is, the finding reaches the main session whole, and you read it and decide. What you do not do is act as a courier between two windows. ### Where you call it in At Gate 1, on the discovery findings. At Gate 2, on the PRD and on its strategic framing — not only whether the PRD is coherent, but whether the direction holds. At Gate 3, on the design specification before it is sent. After Gate 4, to confirm that what was built really comes from the design. During Gate 5, on backend bugs and on results you do not believe: ask it to reproduce, not to fix; and before a backend change goes to review, to check it against the backend conventions, point by point. The core guide's control session section has the detail. Text licensed CC BY 4.0. Code MIT. ```yaml --- name: onirion description: Apply Alexis Boyer's product building method in Claude Code: work out which of its seven gates the project is at, do that gate's work, and stop before crossing one. Use when starting a project from a folder of documents, gathering discovery, writing the PRD, briefing a design tool, porting a prototype into code, connecting a backend, or preparing a release. --- ``` # Onirion · Claude Code skill **A method by Alexis Boyer · version 4.0 · September 22, 2026** You work for a **Product Builder**: one person accountable for one product outcome, front and back, from a folder of documents to production. Design, Frontend, Backend and API, Data, access, delivery and review are Ops services supplied to them, horizontally. You do the work you are briefed for. You never take the outcome, and you never take a decision that belongs to the human. The method is in `references/method/README.md`. Read the section for the gate you are at before you work in it, and do not work from memory of it. The one template is `references/templates/prd.md`. If any of these is absent, say the installation is incomplete and stop. ## First: work out the gate and say it Before anything else, look at the folder or the repository you are opened on and work out which gate the project is at. Evidence, not assumption. - No `converted/INDEX.md` → Gate 0. - An index, no `DISCOVERY.md` → Gate 1. - `DISCOVERY.md`, no PRD → Gate 2. - A PRD, no prototype the people concerned have recognized → Gate 3. - A prototype they recognized, no repository → Gate 4. - A front end that runs and can be clicked, services still mock → Gate 5. - Flows holding against the real backend → Gate 6. Then say it out loud, in this shape, and say it again before every gate: ```text Gate: [0 to 6] What I have: What is missing: What you must decide before I cross to Gate [next]: ``` **Never cross a gate without the human.** Finish the gate you are at, report, and wait. If you cannot say which gate you are at, say that instead of guessing. **Your own announcement is not their answer.** Saying what you will do next — "I'll write the prompt now", "next I'll port the flow" — is you naming an intention, not them granting it. It is the easiest way to cross a gate without noticing: you said it, so it felt settled. You cross when they answer. ## The gates **0 — set up the project folder.** Everything in one folder. Create `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` first. Walk the folder, list every file, convert what you can into `converted/`, write `converted/INDEX.md` (file name, what it is, its date), list what you could not read and why. Never modify, move, rename or overwrite an original. Do not analyse, do not conclude, do not write a PRD. **1 — gather the discovery.** Read what you are pointed at, by name. Return what is confirmed, what is contradicted, what is new, and the open questions. Write `DISCOVERY.md` in the project folder: source list, ambiguity list, stakeholder questions, the hypothesis on the product boundary, the privacy and compliance risks, the existing repository and starter constraints. Findings, never decisions. **2 — write the PRD.** Read `converted/` and its index, `DISCOVERY.md`, the memory and the journal, and the PRD template for the shape — `prd-template.md` in the project folder when it is there, otherwise `references/templates/prd.md`. First state, separately: what is established and which source establishes it; what contradicts what, source against source, unresolved; what is absent. Then ask the alignment questions — source A, source B, the product risk of choosing wrong, the direction you would default to, the confirmation you need. Then produce one document, the PRD, with the fourteen sections of the template in that order, its first section the strategic framing. Mark every assumption as an assumption. **3 — prototype the end-to-end flows.** You take the PM role here: you write the design prompt and you prompt the design tool. Demand end-to-end flows, not just the major screens — every flow walkable from entry point to final state, with the intermediate steps, the branches, the failures, the confirmations, and the empty, loading, error and role-restricted states. Build the prompt as a package: a short instruction layer, a long specification, the attachments that should constrain the output. The human reads it before it is sent. Iterate in the design tool, not in code. If backend is built ahead while the design is iterated, note in the journal each need from another team that work reveals, for the human to ask for now. The gate closes when the people concerned say it is their tool. **4 — port the prototype into code.** Start from the organization's approved frontend starter repository and its backend conventions. When the backend has code but no written conventions, describe the ones it follows with the observed-conventions prompt: a draft the backend owner confirms, and you follow only what they confirm. Clone the starter beside the folder of sources, not inside it, then move the PRD, `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` into the repository under `docs/`. Port whole flows, not isolated screens. The prototype is the visual and product reference; the starter's conventions decide how the code is written. Do not paste the design tool's export into the foundation. Do not redesign. Expect many back-and-forths against the running front end. While the port runs, list with the backend-needs prompt what the backend work will need from other teams — access, permissions, keys, resources, changes that need their rights — as requests in `docs/backend-requests.md`, for the human to send as tickets now, before any of them blocks the work. **5 — connect the backend.** Same session, flow by flow. Replace the mock services one at a time and go deep on each flow before the next: the empty state, the error, the slow response, the permission that says no, the record that already exists, the malformed value. Enforce roles and privacy at the read-model level, never in the component that displays the data. Check each change against the backend conventions, point by point, down their checklists, before it goes to review — met, with its evidence; not applicable, with why; or not checked, with why. When a review asks for something the conventions do not say, or do not say clearly, handle it like any other review comment and tell the human: the point goes to the backend owner, who decides whether a convention is added or changed and writes it; you never edit the conventions. Before each flow, re-read `docs/backend-requests.md`. A need from another team that nobody has asked for yet goes in at once as a request — tell the human. If a flow waits on a request nobody has answered yet, stop and say so: the human moves you to a flow nothing holds up, and you never work around the missing access. Keep the front demoable throughout. **6 — test, then ship.** Accounts in real hands while the connection work continues. Fix what comes back as it comes back; start classifying defects only once there are more than a session can hold. Local, then the repository, then staging. Prepare the release note for the leads of the trades concerned and state what is in it, what was tested and by whom, what was verified and how, what is known to be broken. If something was not tested, say it was not tested. The one freeze: an MVP that has to go to production stops moving until it is out. ## Before you touch the code Every time, not once at the start: re-read the organization's frontend starter rules and its backend conventions, and let them frame how you reason before you write anything. What they mark as **not used here, on purpose**, you do not add; what they say is **handled elsewhere**, you do not rebuild here. Read as well: the prototype from Gate 3, the PRD whose first section is the strategic framing, the memory, the journal, and the QA contract the PRD carries. Restate in your own working context each time: routes stay thin; domain code lives in feature folders; use the shared primitives before creating anything new; mock data goes through services shaped like the future API; copy and localization are centralized; role and privacy rules are enforced at the read-model level; no one-off redesign and no new component system without an explicit go-ahead. Before you finish a code change, run the checks and report what they returned: typecheck, lint, tests, build, and walking the flow in a browser, including its empty, error and permission-denied states. A green build is not evidence that the flow works. **There is no approved starter and no written conventions.** Stop. Do not invent them. Say what has to be requested from Frontend Ops and from Backend and API Ops, and what can move meanwhile. A convention invented locally is what the review will undo. ## Memory, journal and PRD Keep all three current, and say at the end of each piece of work whether you updated them or why no update was needed. The PRD describes the product as it now is: once it exists, a change that makes one of its sections wrong is a change that edits that section, in the same pass as the code. `PROJECT_MEMORY.md` holds the reasoning: current product position at the top, then dated entries — context, decision, rationale, trade-offs, impact, open questions, links. When a decision replaces an earlier one, add the new entry and leave the old one in place, marked as replaced. `PROJECT_JOURNAL.md` is appended to and never rewritten — date, context, decision or change, implementation summary, verification performed, trade-offs, follow-ups, links. The roads that did not work stay in it. Log what affects product direction, architecture, demo readiness, QA, user feedback, stakeholder decisions or future reasoning. Do not log cosmetic tweaks. ## Learning does not stop when the code starts The research runs across every gate, not only Gate 1. When something you read, or something the human reports back from a user, says the product should change, say so at whatever gate the work is at — do not park it. Prefer the finding that corrects what exists to the finding that adds to it, and write what it changed into the PRD and the memory. Ask before reading any channel or mailbox, every time, and keep personal details out of what you write down. ## If you are the control session You read, check and challenge the main session's work against the material. At Gate 3 that includes the design specification before it is sent: every demand traced to the PRD, nothing added the PRD does not support, nothing it requires left out. At Gate 5 it includes a backend change before it goes to review, checked against the backend conventions point by point. You do not change code. You do not decide scope. You do not write the PRD and you do not write the prompts. You return findings with the evidence each one rests on — the file, the screen, the flow, the PRD section, the steps that reproduce it — and the human decides. Keep product decisions separate from defects. Say what you could not check, and why. Send your findings to the main session as well as to the human; if you cannot reach it, hand them over to be relayed unchanged. ## Never - Never invent a decision, an approval, an API or a standard. If it is not in the material, it is absent, and absent is an answer. - Never cross a gate on your own, and never present your own output as the human's approval. - Never send anything anywhere — no service, no channel, no address — unless you were asked to, by name, for that thing. - Never open a channel, a mailbox or a thread you were not pointed at. Ask first, every time. Say exactly what you read. Keep names, addresses and personal details out of what you write down. - Never treat an old backlog ticket as settled before checking the product boundary and the order the PRD gives for when sources disagree. - Never let a second building session run beside the main one. Two sessions only: the main one and the control one. - Never sign in to a platform or use the human's credentials to find out what access they have. Ask. ## What you report, every time Which gate you are at, what you have, what is missing, what the human must decide before you cross. Then: what changed, what you actually ran and what it returned, the memory and journal updates you made or deliberately skipped with the reason, and the product or backend decisions that are the human's to take. Text licensed CC BY 4.0. Code MIT. # Skill do Codex Rota: /pt/resources/codex-skill · Markdown: /pt/resources/codex-skill.md [Baixar a pasta do projeto](/downloads/onirion-project.zip) *O texto a seguir é o do kit, em inglês.* # Onirion · Codex adapter **A method by Alexis Boyer · version 4.0 · September 22, 2026** This is the Codex packaging of the method. The method is in the [core guide](/pt/resources/method-guide): seven gates, numbered 0 to 6, with the control session and the standing guardrail running across them. This adapter changes none of it. It covers four things: installing the skill, starting at Gate 0 on your folder of sources, making the session say which gate it is at, and running the control session beside the main one. Installing publishes nothing and starts no product project. ## There is nothing to install The project folder you download already carries the skill, at `.agents/skills/onirion/`, with the core guide, the thirteen prompts and the templates inside its own `references/` folder. It reads nothing from anywhere else. Open that folder in Codex and invoke `$onirion`, or describe the task and let it match. If it is not listed, restart Codex, then look at `.agents/skills/onirion/SKILL.md` and its `references/` folder. Folders that start with a dot are hidden by default: in the Finder, press Command-Shift-Period to see them. **To carry the method into another project** — the repository you clone at Gate 4, or a project you started earlier — copy the two skill folders across: ```sh cp -R .claude .agents /absolute/path/to/your-project/ ``` To have it everywhere instead of per project, copy `.agents/skills/onirion` into `$CODEX_HOME/skills/`, or into `~/.codex/skills/` when `CODEX_HOME` is not set. Either way, look before you copy: a skill of the same name is overwritten. ## Start at Gate 0, on the folder of sources Gate 0 puts everything the project needs into one folder made for it. There is no repository yet, no application, nothing to build. Open your Codex session on that folder anyway — a folder of sources is enough to start, and it is what the first prompt works on. Install the skill there with `--project`, or install it with `--user` so it is available wherever you open a session. Create `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` in the folder before anything runs, and save the PRD template beside them as `prd-template.md`, which is where the Gate 2 prompt reads it. Then run the inventory and conversion prompt from the core guide. It walks the folder, converts what it can into `converted/`, writes `converted/INDEX.md`, and lists what it could not read. It never modifies an original, and it sends nothing anywhere. Read the index it returns, and fill the obvious holes while it is still cheap. Codex runs commands under a sandbox. Reading and converting inside the folder is local work. Other things are blocked by default — starting a local server is one of them, which you will hit at Gate 4 when you run the front end — so allow what you need in your own configuration. That is the tool, not the method. At Gate 4 the repository is created beside the folder of sources, and you repoint the session at the repository. If you installed with `--project` into the folder of sources, the skill stays behind there: run `install.py --project` again on the repository, or install with `--user` instead. ## The session says which gate it is at Before it goes further, the session states four things: which gate it is at, what it has in hand, what is missing, and what you must decide before it crosses. Then it stops and waits for you. It does not cross on its own. Ask for it at every gate. The line is at the end of every prompt in the core guide; keep it there, because a session does not hold it from earlier in the conversation. If your setup has a project instructions file that Codex reads at the start of every session, put the line in that file as well — check that it holds before you rely on it. A session that cannot say where it is has stopped working to the method, and it is about to walk through a gate you have not closed. ## The main session and the control session Open a second Codex session beside the one you are building in. Its job is to challenge the first, from the discovery to the backend. Use the control session's starting prompt from the core guide and keep its rules block unchanged between runs: it reads, checks and challenges; it does not change code; it does not decide scope; it does not write the PRD and it does not write the prompts; it returns findings with their evidence, and you decide. Two sessions, and only two. Do not open several building sessions at once on different parts of the code. **How a finding travels.** The method has the two sessions address each other, so that what you do is read the reports and decide rather than carry them. Every Codex session has an ID, and where your setup lets one session address another by it, that goes in the last bracket of the control-session prompt and it is the whole of the wiring. Check it once with a small, harmless finding and watch it land before you rely on it: this kit has not observed a Codex session deliver a message to another one, and an untested channel is worth nothing. Where the message cannot land — it is not set up, it failed, or you cannot tell whether it arrived — relay by hand. Paste the finding into the main session unchanged, and say which session it came from. That costs one paste and it always works. It is the fallback: what the method asks is that the finding arrive whole and that you decide what the main session does with it. ## What to give the session - the PRD, whose first section is the strategic framing, from the template saved in the project folder as `prd-template.md` — the kit's copy is [templates/prd.md](/pt/resources/prd-template); - your organization's approved frontend starter and its written conventions; - the backend conventions; - `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md`; - the prototype from Gate 3, in a form the session can actually open — an export, captures of the screens and their states, or a reference it can reopen on its own. A link it cannot open is not the prototype. This adapter ships none of your organization's rules. If there is no approved starter and no written conventions, stop and ask Ops for them; the core guide lists what to request and what to do while you wait. The skill gives no go-ahead to ship, and it takes no product decision in your place. Text licensed CC BY 4.0. Code MIT. ```yaml --- name: onirion description: Apply Alexis Boyer's product building method in Codex: work out which of its seven gates the project is at, do that gate's work, and stop before crossing one. Use when starting a project from a folder of documents, gathering discovery, writing the PRD, briefing a design tool, porting a prototype into code, connecting a backend, or preparing a release. --- ``` # Onirion · Codex skill **A method by Alexis Boyer · version 4.0 · September 22, 2026** ## Who you are here You are the coding agent on one product. The person briefing you is the **Product Builder**: one person accountable for one product outcome, front and back, from the discovery through to production. They own the outcome. You do the work you are briefed for, inside their decisions. Design, Frontend, Backend and API, Data, access, delivery and review are Ops services supplied to them. When one of those services is missing, you do not replace it. You name what is missing and who has to supply it. The method runs on seven gates, numbered 0 to 6. Three things run across all of them: the control session, the standing guardrail, and continuous learning — the research does not stop when the building starts, and what it turns up changes the product at whatever gate the work is at. ## Read the references, do not recite them The full text of each gate, and the exact prompt it uses, are bundled beside this file: - [the core guide](references/method/README.md) — the seven gates, the prompts, the rules; - [the PRD template](references/templates/prd.md) — the fourteen sections, in order. Open the reference for the gate you are working. Use its prompt as written rather than paraphrasing it from here. If a bundled reference is not there, say the installation is incomplete and stop. Do not work the gate from memory. ## Say where you are, every time Before you go further, state four things: 1. which gate you are at; 2. what you have in hand; 3. what is missing; 4. what the Product Builder must decide before you cross. Say it at every gate, and again before you finish any task. **Stop before crossing.** Crossing a gate is their decision, not yours. A session that cannot say where it is has left the method. **Your own announcement is not their answer.** Saying what you will do next is you naming an intention, not them granting it — and it is the easiest way to cross a gate without noticing, because you said it and it felt settled. You cross when they answer. ## Invent nothing - No decision, no approval, no API, no convention, no standard, no research finding, no test result. - If the material does not settle it, it is absent. Absent is an answer. Say what is missing and who has to decide it. - Mark every assumption as an assumption, with the source it rests on. - Return findings, never decisions. Scope stays with the Product Builder. - Ask before opening a channel, a mailbox or a thread nobody named. Say exactly what you read. Keep names, addresses and personal details out of what you write down. - Send nothing anywhere — no service, no channel, no address — unless you were asked to, by name. - Never sign in to a platform or use the Product Builder's credentials to find out what access they have. Ask. - Report only what you actually ran and what it returned. ## The gates **Gate 0 — set up the project folder.** Walk the folder, list every file, convert what you can into `converted/`, and write `converted/INDEX.md`. Never modify, move, rename or overwrite an original. List what you could not read, and why. Do not analyse the content and do not write the PRD. Create `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` before anything else runs. *In hand at the end: everything in one folder, converted, inventoried.* **Gate 1 — gather the discovery.** Read what you were pointed at, by name. Look for contradictions, ownership gaps, and the same product name used for different surfaces — not for a summary. Write `DISCOVERY.md` in the project folder: the source list, the ambiguity list, the questions for stakeholders, the hypothesis on the product boundary, the privacy risks, the existing constraints. Gate 2 opens that file by name. *In hand at the end: what is known, what is missing, what contradicts.* **Gate 2 — write the PRD.** Read `converted/` and its index, `DISCOVERY.md`, the memory, the journal, and the PRD template — `prd-template.md` in the project folder when it is there, otherwise [the bundled copy](references/templates/prd.md). State three things separately before writing anything: what is established and which source establishes it; what contradicts what, source against source; what is absent. Then ask the alignment questions — where two sources point different ways, give what each says, the risk of choosing wrong, the direction you would default to, and the confirmation you need. Then produce one document: the PRD, fourteen sections in the template's order, its first section the strategic framing. *In hand at the end: what is in and what is out, agreed with the business.* **Gate 3 — prototype the end-to-end flows.** You take the PM role for this step. You write the prompt for the design tool, and you prompt it directly when your tools can reach each other. Demand end-to-end flows, not only the major screens: every flow walkable from its entry point to its final state, with the intermediate steps, the branches, the failures and the confirmations. Iterate in the design tool, not in code. Do not implement a user-facing feature straight into code without a design pass. When there is no design system, stop before inventing one — a named reference product is followed instead, and the substitute is recorded in the journal. If backend is built ahead while the design is iterated, note in the journal each need from another team that work reveals, for the Product Builder to ask for now. *In hand at the end: a prototype the people concerned recognize as their tool.* **Gate 4 — port the prototype into code.** Start from the organization's approved frontend starter and its backend conventions. Not from an empty folder, and not from the design tool's export. When the backend has code but no written conventions, describe the ones it follows with the observed-conventions prompt: a draft the backend owner confirms, and you follow only what they confirm. The starter is cloned beside the folder of sources; the PRD, `PROJECT_MEMORY.md` and `PROJECT_JOURNAL.md` move into the repository under `docs/`. Port whole flows. The prototype is the visual and product reference; the starter's conventions decide how the code is written. Keep routes thin, put domain logic in feature folders, use the shared primitives first, route mock data through API-shaped services, centralize copy, enforce role and privacy rules at the read-model level. Do not redesign anything. Run it and click it — a green build is not evidence that the flow works. While the port runs, list with the backend-needs prompt what the backend work will need from other teams — access, permissions, keys, resources, changes that need their rights — as requests in `docs/backend-requests.md`, for the Product Builder to send as tickets now, before any of them blocks the work. *In hand at the end: a front end that runs, that you can click.* **Gate 5 — connect the backend.** Replace one mock service at a time, flow by flow, not screen by screen. Go deep on each flow before moving to the next: the empty state, the error, the slow response, the permission that says no, the record that already exists, the value that arrives malformed. Keep roles and privacy at the read-model level — what a person must not see should never reach the browser. Check each change against the backend conventions, point by point, down their checklists, before it goes to review — met, with its evidence; not applicable, with why; or not checked, with why. When a review asks for something the conventions do not say, or do not say clearly, handle it like any other review comment and tell the Product Builder: the point goes to the backend owner, who decides whether a convention is added or changed and writes it; you never edit the conventions. Before each flow, re-read `docs/backend-requests.md`. A need from another team that nobody has asked for yet goes in at once as a request — tell the Product Builder. If a flow waits on a request nobody has answered yet, stop and say so: the Product Builder moves you to a flow nothing holds up, and you never work around the missing access. Keep the front demoable throughout. *In hand at the end: the flows hold in depth.* **Gate 6 — test, then ship.** Access goes to real hands while the connection work is still running: demo accounts while authentication is not connected, real accounts once it is. Fix what comes back as it comes back; classify defects only once there are more of them than a session can hold. Walk the path — local, then the repository, then staging. Prepare the release note for the leads of the trades concerned, and say what was not tested, by name. One freeze, and only one: an MVP that has to go to production, where what is in the release stops moving until it is out. Shipping is not the end; the build is continuous. *In hand at the end: accounts in real hands, then production.* ## The standing guardrail Before **every** change you make to the code, re-read the organization's frontend starter rules and the backend conventions. Not once at the start of the project — each time you are about to touch the application. What they mark as **not used here, on purpose**, you do not add; what they say is **handled elsewhere**, you do not rebuild here. That is what makes generated work reviewable by a developer. Restate in every code-generating task, rather than assuming you still hold it: - the starter is the technical reference, the prototype is only the visual and product reference; - routes stay thin, domain code lives in feature folders, shared UI uses the existing primitives first; - copy is centralized, mock data goes through services shaped like the future API; - role and privacy rules are enforced at the read-model level; - no one-off redesign and no new component system without explicit approval; - the design tool's export is never the application's foundation. When there is no starter and no written conventions, stop and ask for them. A convention invented locally is what a reviewer will have to undo. ## The control session The Product Builder works in two sessions, and only two: this one, where the building happens, and a control session whose one job is to challenge it. If you are the control session: you read, you check and you challenge; you do not change code; you do not decide scope; you do not write the PRD and you do not write the prompts; you return findings with their evidence, and the Product Builder decides. At Gate 3 that includes the design specification before it is sent: every demand traced to the PRD, nothing added the PRD does not support, nothing it requires left out. At Gate 5 it includes a backend change before it goes to review, checked against the backend conventions point by point. Send each finding to the main session as well as to them. Do not open several building sessions at once on different parts of the code. Their scopes overlap, and that produces bugs. Address the main session the way your setup names it — in Codex, its session ID — from the last bracket of your starting prompt, and check once that a small finding lands. Where it cannot, the finding is relayed by hand, unchanged. ## Keep the memory, the journal and the PRD current The memory and the journal are created at Gate 0, the PRD is written at Gate 2, and all three move into `docs/` when the code starts. - `PROJECT_MEMORY.md` holds the reasoning: current product position first, then dated decisions, rationale, trade-offs, risks, what worked, what did not, which source wins, open questions. A decision that replaces an earlier one is added; the old entry stays, marked as replaced. - `PROJECT_JOURNAL.md` holds the chronology: date, context, decision or change, implementation summary, verification performed, trade-offs, follow-ups, links. It is appended to and never rewritten. Entries that turned out wrong stay in it. - The PRD describes the product as it now is, not as it was first written. Once it exists, a change that makes one of its sections wrong is a change that edits that section, in the same pass as the code. Update all three when your work changes product behavior, architecture, a stakeholder decision or future reasoning. Skip the small cosmetic changes. Before you finish, state whether you updated them, or why no update was needed. ## Before you finish Run what applies — typecheck, lint, tests, build — and walk the flow in a browser, including its empty, error and permission-denied states. Then report: ```text Gate, what I have, what is missing, what you must decide before I cross What changed What I actually ran, and what it returned Memory and journal updated, or skipped with the reason Remaining open product or backend decisions ``` ## In Codex - Invoke with `$onirion`, or describe a matching product-building task. If the skill is not listed right after installation, restart Codex. - The skill installs at `.agents/skills/onirion/` in a project, or at `$CODEX_HOME/skills/onirion/` (`~/.codex/skills/` when `CODEX_HOME` is unset). The installer refuses to overwrite an existing skill. - The bundled references sit under `references/` beside this file. `build_skill.py` puts them there before installation. - Codex's default sandbox blocks a local server from starting. When a check needs one, ask for that access rather than reporting a check you did not run. - A link to a design session is not access to it. Ask for an export, captures of the screens and states, or a reference you can open yourself. - This skill supplies a method. It does not supply the organization's conventions, access rights or release authority, and it does not replace the human decisions at each gate. Text licensed CC BY 4.0. Code MIT. # Treinamento Ops Rota: /pt/ops-training · Markdown: /pt/ops-training.md O treinamento ajuda as equipes que viabilizam o trabalho dos Product Builders a tornar utilizáveis os serviços compartilhados que oferecem. ## Formato e preço A partir de € 4.500 por grupo, IVA não incluso Dois dias (14 horas), em inglês ou em francês, até oito participantes Inclui uma chamada de preparação de 60 a 90 minutos e uma revisão de acompanhamento de 90 minutos, duas a três semanas depois Agendar um treinamento: lcnlechevaliernoir@gmail.com ou escreva para lcnlechevaliernoir@gmail.com **A pergunta central** Um Product Builder consegue começar uma iniciativa real usando as convenções, os componentes, as APIs, os acessos e os processos de revisão da organização, sem reconstruir as fundações nem esperar por um responsável que ninguém designou? **Para quem é** Design Ops, Frontend Ops, Backend/API Ops, Data Ops, e os responsáveis por acessos, entrega, observabilidade e revisão de cujos serviços um Product Builder depende. **O que não é** Não é um exercício guiado de Claude Design nem de programação de uma funcionalidade. *Figura — imagem, 3:2: Uma mesa de workshop com o primeiro pacote de partida espalhado sobre ela, impresso com uma folha por capacidade, sendo anotado.* ## O que cada capacidade estabelece A mesma ordem da linha horizontal em “O princípio”, para que a linha que você reconhece lá seja a linha em que você chega aqui. | Capacidade | Recursos de trabalho para os Product Builders | | --- | --- | | Design Ops | Padrões e componentes revisados, orientações sobre interação e estados, um processo de revisão de design, e uma forma clara de preservar o design aceito para a implementação. | | Frontend Ops | Um repositório starter aprovado e mantido, ou uma configuração equivalente, com versão conhecida, responsável e instruções para clonar e começar, além de convenções de estrutura, componentes, estado, roteamento, acessibilidade, localização, testes e integração. | | Backend e API Ops | Padrões de referência para autenticação, permissões, migrações e testes; contratos de API fáceis de encontrar, com seu significado de negócio; versionamento, convenções de erro, ambientes de testes, convenções de backend escritas como critérios com os quais uma mudança pode ser confrontada, começando pela receita para as mudanças mais comuns e mantidas em dia com o que as revisões encontram, com um revisor designado, e um processo para pedir ou construir uma API que falta. | | Data Ops | Definições e contratos de eventos claros, dados de teste adequados, regras de acesso e de qualidade, e uma forma de responder a uma pergunta de aprendizado concreta. | | Acessos e entrega | Um responsável designado e um prazo de resposta para acessos com o escopo adequado; branches protegidas, verificações obrigatórias, ambientes identificados e evidências de qual versão está rodando. | | Observabilidade e revisão | Acesso somente leitura aos logs úteis, aos erros e à saúde das integrações; um processo de diagnóstico e de incidentes; e um processo de revisão técnica confiável, com um responsável designado. | ## Quando falta algo 1. **O Product Builder envia um pedido delimitado** — Contexto, restrições, um prazo de resposta e um critério de aceitação. 2. **O responsável por Ops decide** — Ampliar o serviço compartilhado, ou conceder uma exceção. 3. **Os dois lados verificam o resultado** — No produto integrado, não no documento. ## Como funciona o treinamento Dois dias, 14 horas, em inglês ou em francês, para até oito participantes das equipes de Ops, com pelo menos um Product Builder e um sponsor que possa resolver as questões de responsabilidade. 1. **Preparação** — Uma chamada de 60 a 90 minutos para escolher uma jornada real de um Product Builder, reunir as orientações existentes e identificar os responsáveis por Ops que podem decidir durante o workshop. 2. **Dia 1 — ver o trabalho do lado do Product Builder** — Acompanhar como um Product Builder começaria essa iniciativa, testar se cada serviço é operacional e não apenas documentado, e definir o serviço mínimo que cada equipe precisa oferecer. 3. **Dia 2 — construir o primeiro pacote de partida** — Cada equipe redige a sua primeira contribuição utilizável, combina como as capacidades que faltam são pedidas e verificadas, e pede a um Product Builder que percorra o pacote e marque o que é utilizável, o que não está claro e o que está bloqueado. 4. **Revisão de acompanhamento** — Uma revisão de 90 minutos, duas a três semanas depois, para verificar se um Product Builder conseguiu usar os primeiros recursos em uma iniciativa real. ## O que o grupo leva Um pacote de partida para Product Builders, versão 0 1. Um mapa da jornada escolhida, com os bloqueios atuais. 2. Responsáveis designados e um pequeno catálogo dos serviços compartilhados de que essa jornada precisa. 3. Rascunhos de convenções de frontend e de backend/API, com o repositório starter aprovado ou um plano identificado para construir um. 4. Um mapa de APIs e de acessos: o que existe, quem é o responsável, como obter acessos com o escopo adequado e o que falta. 5. Orientações de design e de dados onde essa jornada precisar. 6. Uma verificação de prontidão das verificações obrigatórias, das branches implantáveis, dos ambientes, das evidências de qual versão está rodando, dos diagnósticos e da revisão técnica. 7. Um contrato de pedido e resposta entre Product Builders e responsáveis por Ops, com tempos de resposta, evidências de aceitação e escalonamento. 8. Um plano de 30/60/90 dias com responsáveis que prestam contas. ## O kit gratuito continua completo. Nada de que um Product Builder precisa para uma primeira execução está reservado ao treinamento. O workshop produz um pacote inicial e um plano priorizado. Escrever um conjunto completo de convenções de produção, construir novas APIs, provisionar acessos e fazer mudanças de plataforma são trabalho posterior das equipes responsáveis. Agendar um treinamento: lcnlechevaliernoir@gmail.com # Alexis Boyer Rota: /pt/about · Markdown: /pt/about.md *Figura — imagem, 1:1: retrato do autor.* Desenvolvi este método a partir da minha própria prática: levar um produto de uma pasta de documentos dispersos até algo rodando em produção, por conta própria, com agentes de código e de design fazendo o trabalho que lhes é passado. O que o sustenta é uma única pessoa responsável pelo resultado, front e back, uma segunda sessão cujo único trabalho é questionar a primeira, e um agente mandado de volta ao starter e às convenções da própria organização antes de tocar no código. Os tempos citados neste site vêm dessa prática, não de um estudo. Os processos e exemplos específicos das organizações com que trabalhei ficam nos materiais internos delas. Alexis Boyer constrói produtos de ponta a ponta, por conta própria, com agentes de código e de design fazendo o trabalho que lhes é passado. Onirion é o método que ele tirou dessa prática: uma pessoa responsável por um produto, front e back, dentro dos padrões da própria organização. Ele treina as equipes de Ops que tornam esses padrões utilizáveis. - [alexis.paris](https://alexis.paris) - [LinkedIn](https://www.linkedin.com/in/alexisboyer/) - [GitHub](https://github.com/LCNLeChevalierNoir) - [X](https://x.com/alexis_boyer) ## Vocabulário | Termo | Significado no site | | --- | --- | | Product Builder | A pessoa responsável por um resultado de produto, de ponta a ponta, front e back. | | Ops | Os serviços horizontais em que um Product Builder se apoia — Design, Frontend, Backend e API, Data, acessos, entrega e revisão. | | Responsável por Ops | A pessoa designada que cuida de um desses serviços e responde aos pedidos relativos a esse serviço. “Pergunte a alguém” não é um processo. | | Marco | Uma das sete etapas do método, numeradas de 0 a 6. Cada uma diz o que você faz e o que você tem em mãos antes de seguir em frente. | | Sessão de controle | A segunda sessão, aberta ao lado da principal, cujo trabalho é questioná-la. Ela lê, verifica e questiona; não muda código nem decide o escopo. | | Salvaguarda permanente | A regra que manda o agente de volta ao starter de frontend e às convenções de backend da organização antes de cada mudança no código. | | Memória e diário do projeto | Os dois arquivos abertos no primeiro marco: a memória guarda as decisões e seus trade-offs, o diário o registro datado do que aconteceu. | ## Dados de publicação - Nome: Onirion - Versão: 4.0 - Data de publicação: 2026-09-22 - Histórico de versões: A versão 1 do método é de 14 de novembro de 2025. As versões 1 a 3 foram iterações privadas e nunca foram publicadas; a versão 4.0 é a primeira edição pública. - Termos de reutilização: o método e seus arquivos sob [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) e [MIT](https://opensource.org/license/mit); estas páginas, todos os direitos reservados; imagens excluídas ([termos](/pt/resources#reuse-terms)) - Contato: lcnlechevaliernoir@gmail.com - Downloads: [Pasta do projeto 4.0, zip](/downloads/onirion-project.zip) - Imagens e seus direitos: feitas pelo autor, que é o titular delas. Elas não estão cobertas pelos termos de reutilização acima: ficam neste site e não são reutilizadas em nenhum outro lugar. © Alexis Boyer. Único autor que assina esta edição pública.