Revisando um pull request contra o ticket
A última barreira antes de um pull request estar pronto. Ela responde a uma pergunta — este diff entrega o ticket, dentro da arquitetura? — e a responde com base em duas fontes que estão acima do gosto do revisor: os critérios de aceitação e a arquitetura de referência.
Esta revisão lê e relata. Ela não edita: uma revisão que corrige o que encontra destrói a evidência do que estava errado, e ninguém aprende o padrão.
Última de três fases, após TICKET-ANALYSIS.md e IMPLEMENTATION-PHASE.md. WORKFLOW.md mostra como elas se encaixam e como instalá-las.
Conteúdo
- Estabelecer o que está realmente sendo revisado
- Critérios de aceitação primeiro
- A passagem arquitetural
- A passagem de teste
- Severidade e o veredito
- Modos de falha
- Checklist
1. Estabelecer o diff
Faça o diff do branch contra o branch base real do repositório, não contra uma suposição sobre qual é esse branch. Revise cada arquivo alterado; um arquivo ignorado por parecer entediante é onde a mudança de configuração se esconde.
Anote o que o diff toca que o ticket não mencionou. Essa lista é uma entrada para as seções §2 e §5, ainda não é uma constatação.
2. Critérios de aceitação primeiro
Pegue os critérios de aceitação um por um e, para cada um, nomeie o código que o satisfaz e o teste que o prova. Ambos, ou não está satisfeito.
- Um critério com código e sem teste é não comprovado.
- Um critério com um teste e sem código é um teste que afirma o framework.
- Um critério que você não consegue localizar é a constatação mais importante e supera todas as observações de estilo na revisão.
Depois, a outra direção: mudanças sem nenhum critério por trás delas. Algumas são legítimas — uma correção dentro do código que já estava sendo alterado (IMPLEMENTATION-PHASE.md §2). O resto é aumento de escopo, e é mais barato nomear aqui do que explicar após o lançamento.
3. A passagem arquitetural
Percorra a checklist de conformidade para as camadas que o diff toca. As descobertas que mais valem são aquelas que uma build bem-sucedida não pode mostrar:
- P2 — qualquer coisa com formato de domínio adicionada ao kernel compartilhado: uma entidade, DTO, enum, conjunto de dados de seed, constante de preço, string voltada ao usuário.
- P3 — uma leitura ou gravação entre contextos; um segundo serviço acessando o banco de dados do serviço proprietário.
- P4 — esquema alterado sem uma migration, ou uma migration que não é portável entre provedores.
- P5 — um segredo, chave ou string de conexão no código-fonte, configuração ou comentário; configuração lida de outro lugar que não o ambiente.
- P8 — uma nova dependência que falha na inicialização em vez de degradar, ou uma ausente do endpoint de saúde e do banner de inicialização.
- P9 / P10 — fiação embutida em
Program.cs; um ponto de extensão adicionado como classe base em vez de uma interface registrada no DI. - P11 — uma forma externa alcançando o domínio não traduzida.
- P15 — um novo caminho sem traces, métricas ou logs.
SERVICE-API-PATTERNS.md— um endpoint fora dos grupos de confiança, uma lista sem limite, um corpo de erro não uniforme, uma chamada de saída sem timeout explícito, uma gravação indeterminada repetida.- Segurança — qualquer coisa recém-exposta publicamente recebe a passagem de
SECURITY-REVIEW.mdantes de ser enviada, não depois.
Um desvio que o pull request registra como uma decisão com um motivo não é uma constatação. O mesmo desvio, silencioso, é um — essa distinção é o trabalho do P14.
4. A passagem de teste
Leia os corpos dos testes. A contagem de testes, de arquivos e a estrutura de pastas não provam nada; uma auditoria em 14 de agosto de 2026 de um conjunto de 447 testes descobriu que aproximadamente 45% eram placeholders ou protegidos para nunca afirmar nada, e nada disso era visível externamente (P13).
- Cada novo teste está na camada que contém a lógica, ou um navegador está substituindo um validador?
- Ele afirma um resultado, ou que um botão foi clicado?
- Há um teste de regressão para cada caminho existente que o diff toca, ou apenas testes para o novo branch?
- Ele atende aos critérios por teste — independente,
data-testid, sem sleeps, sem credenciais de produção (TESTING-STRATEGY.md§6)? - Algum novo ponto de entrada de teste é executado por um contexto de CI (§9)?
5. Severidade e o veredito
Classifique cada constatação e classifique-a pela consequência, em vez de por quão fácil é descrevê-la:
| Nível | O que significa |
|---|---|
| Bloqueante | Um critério de aceitação não foi atendido ou comprovado; um princípio foi violado sem decisão registrada; um segredo foi exposto; um teste foi enfraquecido ou excluído para ficar verde |
| Deve corrigir | Correto, mas fora do padrão: camada de teste errada, cobertura de regressão ausente, uma suposição não registrada, documentação que a mudança tornou falsa |
| Considerar | Verdadeiramente opcional. Mantenha esta seção curta — uma longa enterra as duas primeiras |
Finalize com o veredito que a barreira do diagrama precisa, declarado claramente: este pull request entrega o ticket e está dentro da arquitetura? Uma de três respostas — validado; validado com as constatações não bloqueantes listadas; ou não validado, com as constatações bloqueantes nomeadas. "Parece bom, alguns comentários" não é um veredito.
6. Modos de falha
| Sintoma | Causa |
|---|---|
| A revisão aprova um diff que perde um requisito | A passagem começou pelo código em vez dos critérios de aceitação |
| A revisão é uma lista de opiniões de estilo | As passagens arquitetural e de teste foram ignoradas porque a build estava verde — que é exatamente o que elas verificam |
| Uma suíte verde é tratada como evidência | Os corpos dos testes nunca foram lidos; a contagem e a estrutura foram confiadas em seu lugar |
| As constatações são todas relatadas com o mesmo peso | Nenhuma classificação de severidade, então a constatação bloqueante fica abaixo de uma correção de nome |
| A mesma violação se repete entre pull requests | As constatações foram corrigidas pelo revisor em vez de relatadas, então o padrão nunca foi aprendido |
| Um desvio é relatado que o autor já havia justificado | As decisões registradas do pull request não foram lidas antes da revisão |
7. Checklist
- Diff feito contra o branch base real do repositório; cada arquivo alterado lido
- Cada critério de aceitação mapeado para o código que o satisfaz e o teste que o prova
- Mudanças sem nenhum critério por trás delas identificadas e classificadas
- Checklist de conformidade percorrida para cada camada que o diff toca
- Decisões registradas lidas primeiro, para que desvios justificados não sejam relatados como constatações
- Qualquer coisa recém-pública recebeu a passagem de revisão de segurança
- Corpos dos testes lidos, não contados; camada, afirmações de resultado, cobertura de regressão e os critérios por teste verificados
- Constatações classificadas como bloqueante / deve corrigir / considerar
- Um veredito explícito dado contra o ticket
- Nada editado durante a revisão
Gerado a partir de docs/delivery/PR-REVIEW.md por scripts/build-marketplace.mjs. Não edite este arquivo: altere o documento de origem ou sua entrada em catalog/marketplace.catalog.json e execute novamente o gerador.