Gates de Qualidade

Dois gates guardam a qualidade. Planning Review antes do código. Implementation Review depois do código. Ambos produzem pontuações, ambos devem passar. Nada é entregue sem aprovação.

Os Dois Gates

Gate 1 — Planning Review

Executa antes de qualquer código ser escrito. Avalia se sua especificação está pronta para implementação.

A pergunta que ele responde: “Se eu entregar este plano aos agentes agora, eles terão tudo que precisam para implementá-lo corretamente?”

Uma especificação pode ser detalhada e ainda falhar no Planning Review se dependências são circulares, tickets não têm critérios de aceite, ou áreas funcionais inteiras estão faltando na decomposição.

Gate 2 — Implementation Review

Executa depois que todos os tickets são completados. Avalia se o código entregue corresponde à especificação original.

A pergunta que ele responde: “Os agentes realmente construíram o que a especificação pediu, no padrão de qualidade que definimos?”

Uma especificação pode ter todos os tickets marcados como done e ainda falhar no Implementation Review se critérios de aceite não foram atendidos, arquivos não foram entregues, ou cobertura de testes está faltando.

Dimensões de Pontuação

Cada gate avalia múltiplas dimensões e produz uma pontuação por dimensão. A pontuação geral é uma média ponderada. O limite padrão de aprovação é 80.

Dimensões do Planning Review

Completude — Todo épico tem tickets? Todo ticket tem título, descrição, passos e critérios de aceite? Existem épicos vazios ou tickets stub sem conteúdo acionável?

Pontuação 90: Todos os tickets têm passos e critérios de aceite. Um ticket não tem descrição mas tem contexto suficiente no título e passos. Pontuação 60: Múltiplos tickets são stubs — apenas título, sem passos, sem critérios de aceite. Agentes teriam que adivinhar o que construir.

Dependências — O grafo de dependência é válido? Existem referências circulares? Todos os links cross-epic resolvem corretamente? Existem tickets órfãos que deveriam ter dependências mas não têm?

Pontuação 95: DAG limpo, sem ciclos, todas as referências cross-epic resolvem. Caminho crítico é computável. Pontuação 50: Dependência circular detectada entre dois tickets. Três tickets referenciam dependências que não existem.

Cobertura — A decomposição cobre tudo descrito na especificação? Existem goals ou requirements mencionados na descrição que nenhum ticket endereça?

Pontuação 85: Todos os requirements declarados têm tickets correspondentes. Um caso extremo mencionado na descrição (“bloqueio de conta após 5 tentativas falhas”) não tem ticket dedicado mas é coberto como passo em outro ticket. Pontuação 55: A especificação menciona “rate limiting” na descrição mas nenhum épico ou ticket endereça isso.

Qualidade do Ticket — Tickets são atômicos e implementáveis? Ou são épicos vagos disfarçados de tickets? Os passos descrevem ações concretas ou objetivos abstratos?

Pontuação 90: Tickets são pequenos, focados, com passos de implementação concretos como “Criar classe JwtService em src/auth/jwt.service.ts.” Pontuação 45: Um único ticket diz “Implementar o sistema inteiro de autenticação” sem passos. Isso é um épico, não um ticket.

Critérios de Aceite — Os critérios de aceite são específicos e verificáveis? Um agente pode objetivamente determinar se cada critério foi atendido? Ou são declarações vagas como “deve funcionar bem”?

Pontuação 88: Critérios como “Tokens são assinados com algoritmo RS256” e “Tokens inválidos retornam 401 com mensagem de erro.” Pontuação 40: Critérios como “A autenticação deve ser segura” e “Boa experiência do usuário.”

Dimensões do Implementation Review

Conclusão de Passos — Todos os passos de implementação em cada ticket foram marcados como concluídos?

Critérios de Aceite — Todos os critérios de aceite em cada ticket foram satisfeitos?

Entrega de Arquivos — Todas as criações, modificações e exclusões de arquivos esperadas foram realmente realizadas?

Evidência Git — Commits e/ou pull requests estão vinculados aos tickets? (Configurável — pode ser obrigatório, recomendado ou desabilitado.)

Testes — Resultados de teste foram submetidos para tickets que os exigem? Os testes passaram?

💡 Cada dimensão pode ser habilitada/desabilitada independentemente na configuração de Padrões de Qualidade do seu projeto. Você pode desabilitar evidência git para prototipagem ou exigir output verboso de testes para specs de produção.

Como a Pontuação Funciona

Cada dimensão produz uma pontuação de 0 a 100. A pontuação geral do gate é uma média ponderada de todas as dimensões ativas. O limite padrão de aprovação é 80, mas você pode configurar por projeto.

Aprovado (≥ limite): A especificação avança para a próxima fase. O Planning Review move a spec para ready. O Implementation Review move para reviewed.

Reprovado (< limite): O gate produz um relatório detalhado de feedback. Não é rejeição cega — cada dimensão reprovada inclui achados específicos:

• Quais tickets estão sem critérios de aceite
• Quais dependências são circulares ou não resolvidas
• Quais arquivos eram esperados mas não foram entregues
• Quais critérios de aceite não foram satisfeitos

O feedback é acionável. Corrija os achados, execute o review novamente. A spec não volta ao ponto zero — ela permanece na fase atual e você endereça as lacunas.

ℹ️ maxReviewAttempts (padrão: 3) limita quantas vezes um review pode ser refeito antes de exigir intervenção manual. Isso previne loops infinitos de review em especificações fundamentalmente falhas.

Por Que Dois Gates ao Invés de Um

Um único review pós-implementação capturaria problemas — mas só depois que agentes já gastaram tokens implementando um plano ruim. O Planning Review existe para capturar problemas estruturais antes de qualquer código ser escrito.

Pense assim: Gate 1 valida a planta. Gate 2 valida a construção. Você não começaria a construir sobre uma planta com cômodos faltando.

Na prática, o Planning Review captura:

• Tickets muito vagos para agentes implementarem sem adivinhar
• Dependências faltando que fariam agentes construir na ordem errada
• Lacunas de cobertura onde a descrição da spec promete algo que nenhum ticket entrega
• Problemas estruturais como épicos vazios ou tickets duplicados

O Implementation Review captura:

• Tickets marcados como done mas com passos incompletos
• Critérios de aceite que não foram realmente atendidos
• Arquivos que deveriam ter sido criados mas não foram
• Evidência de testes faltando

Configurando os Gates

Ambos os gates são configuráveis no nível do projeto. Você pode ajustar limites, habilitar/desabilitar dimensões individuais e controlar quão rigorosamente evidências são exigidas.

Exemplos rápidos:

# Aumentar o limite do planning para specs de produção
specforge configure planningConfig.readinessThreshold 85
 
# Desabilitar evidência git para prototipagem
specforge configure implementationConfig.gates.git_evidence false
 
# Exigir output verboso de testes
specforge configure implementationConfig.testEvidence verbose

Para a referência completa de configuração, veja Padrões de Qualidade.

Orientação Prática

Começando? Mantenha os padrões. Limite 80 é equilibrado — rigoroso o suficiente para capturar problemas reais, leniente o suficiente para não bloquear você em lacunas menores.

Prototipando? Baixe o limite para 60-70 e desabilite evidência git. Velocidade importa mais que cerimônia. Você sempre pode re-executar reviews depois com configurações mais rigorosas.

Specs de produção? Aumente o limite para 85-90, exija evidência git e use evidência de teste discretizada. É aqui que os gates se pagam — um problema capturado no review vale horas de debugging em produção.

Equipes grandes? Cobertura de blueprint se torna crítica. Com múltiplas pessoas contribuindo para uma spec, o Planning Review captura inconsistências entre contribuidores que o review manual não percebe.

Veja Também

• Padrões de Qualidade — Referência completa de ReviewConfig com todas as opções
• Ciclos de Vida — Como gates se conectam aos três ciclos
• Estados da Especificação — Transições de estado disparadas por resultados de gates