Fechando o desalinhamento do PRD encontrado numa revisão de código

O Greenhouse tem um documento de PRD que é anterior à maior parte da implementação. É a especificação que escrevi antes de qualquer código existir, e como qualquer especificação que fica ao lado de uma base de código por alguns meses, ela começou a se desalinhar do que o app realmente faz. A mesma revisão completa do app que revelou a prateleira de colheita invisível apontou quatro pontos onde o documento e o código discordavam. Este registro é sobre fechar essas pendências.

Nenhum desses era um bug. Todos eram lugares onde eu tinha tomado uma decisão real no código e nunca voltado para atualizar o parágrafo que costumava descrever a questão em aberto.

Os arquivos-espelho nunca disseram que seriam sobrescritos

O Greenhouse mantém o SQLite como fonte da verdade para o estado de um projeto, e então escreve um arquivo project.md ou idea.md simples na pasta do projeto para que os dados continuem legíveis mesmo que você nunca mais abra o app. O PRD tinha deixado em aberto se edições nesse arquivo seriam mescladas de volta no banco, ou se o banco simplesmente prevaleceria. Na prática, construí uma regeneração de mão única meses atrás: toda escrita relevante reescreve o arquivo do zero. Nunca registrei essa decisão, e pior, o próprio arquivo não dava nenhuma pista de que editá-lo à mão era inútil. Então adicionei uma linha no topo dos dois arquivos: Auto-generated by Greenhouse. Edits here will be overwritten. Mudança pequena, mas é a diferença entre perder uma edição silenciosamente e saber, desde o início, para não fazê-la.

Dois parâmetros que costumavam ser um só

O PRD descrevia a cota de sementes (um empurrão para capturar um lote inicial de ideias) e o aviso de estoque baixo (um empurrão para capturar mais quando você está ficando sem) como se fossem dois valores configuráveis separados. Em algum ponto do caminho eu os uni: o aviso de estoque baixo simplesmente dispara quando a sua contagem de itens utilizáveis cai abaixo da cota de sementes. Um parâmetro, dois comportamentos. O documento não tinha acompanhado essa mudança, então reescrevi o item de estoque baixo para dizer explicitamente que o limite dele é a cota de sementes, e não algo que você configuraria separadamente.

Uma regra sem explicação do porquê ela existe

O assistente de onboarding percorre as regras centrais do Greenhouse como um conjunto de cartões, cada um com uma razão de uma linha para sua existência. Não havia cartão para o temporizador de dormência do vault: um projeto guardado no vault silenciosamente volta para revisão depois de 14 dias, e até agora nada avisava o usuário que isso ia acontecer. Um dia ele simplesmente aparecia como um aviso “Rescue or Keep” sem nenhum contexto. Adicionei um quinto cartão explicando isso. Esse mesmo componente de passo a passo também funciona como um diálogo “por que essas regras?” acessível pelo rodapé do dashboard, então a correção aparece nos dois lugares de graça.

Uma afirmação que o dashboard não sustenta de fato

A seção de fluxo diário afirmava que o dashboard “reflete o que foi feito hoje.” Isso só é verdade para a captura. O app rastreia se você registrou uma nova ideia hoje, mas não rastreia se você revisou uma ideia madura ou trabalhou num projeto ativo hoje, ele só mostra o que está atualmente maduro para essas ações, independentemente de quando você tocou nelas pela última vez. Reescrevi a afirmação para bater com o que o código realmente faz, em vez de deixar crescer silenciosamente uma dívida de funcionalidade em cima de uma frase que ninguém releu.

Lição

Um PRD que não é atualizado junto com o código para de ser documentação e passa a ser um registro histórico do que você pretendia construir. Nenhum desses quatro itens foi difícil de corrigir depois de encontrado, o trabalho todo foi perceber que eles tinham se desalinhado. Vale a pena uma passada periódica, especialmente depois de qualquer issue que muda comportamento sem uma edição correspondente na documentação no mesmo commit.