Gates de Qualidade

Dois gates guardam a qualidade. Um Planning Review de nível de spec antes do código. Um gate de assay por ticket conforme o código de cada ticket é entregue. 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.

Como o Loop de Planning Funciona

O Planning Review não é uma checagem única de passa/falha. É um loop de controle. A IA decompõe sua intenção. O gate avalia. Se o score está abaixo do threshold, você recebe findings específicos — não “tente novamente” mas “estes 3 tickets não têm critérios de aceitação” e “sua descrição menciona rate limiting mas nenhum ticket endereça isso.” Você refina. O gate avalia novamente. O loop se repete até que a spec esteja sólida.

Nenhum código é escrito durante todo este processo. O plano é validado antes de uma única linha de implementação.

Diga ao seu agente:

~~ Rode o planning review para esta especificação ~~

O review avalia cinco dimensões de scoring:

Cada dimensão pontua de 0-100. O score geral é a média ponderada. Se o score atinge ou excede o limite global de prontidão (thresholds.global, default: 80, configurável em Padrões de Qualidade), a especificação avança para ready.

Se falhar, os findings dizem exatamente o que corrigir. Corrija. Rode o review novamente. Este é o loop de controle externo — o que garante que seu plano é sólido antes dos agentes começarem a implementar.

🔬 Para engenheiros: Este é o mesmo loop de controle descrito em Fundamentos de Engenharia, aplicado um nível acima. O sinal de referência é sua intenção. O comparador é o Planning Review. A planta é a decomposição da IA. O sinal de erro são os findings. O threshold é a zona de aceitação. Veja Padrões de Qualidade para tunar o controlador.

Gate 2 — O Gate de Assay por Ticket

Executa dentro de complete_work_session, toda vez que um ticket é completado. Avalia se o código entregue daquele ticket corresponde ao que o ticket pediu. Não há um review separado de nível de spec depois que todos os tickets estão done — a qualidade é verificada ticket a ticket, conforme o trabalho é entregue.

A pergunta que ele responde: “O agente realmente construiu o que este ticket pediu, no padrão de qualidade que definimos?”

Um ticket pode ser marcado como done pelo agente e ainda falhar no seu assay se critérios de aceite não foram atendidos, arquivos não foram entregues, ou cobertura de testes está faltando — caso em que ele não avança para done até que os achados sejam endereçados.

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 Assay por Ticket

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

Critérios de Aceite — Todos os critérios de aceite do 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 ao ticket? (Configurável — pode ser obrigatório, recomendado ou desabilitado.)

Testes — Resultados de teste foram submetidos para o ticket, se ele os exige? 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): O trabalho avança. O Planning Review move a spec para ready. O assay por ticket marca o ticket como done; quando todo ticket está done, a especificação está done.

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 gate novamente. Nada volta ao ponto zero — o Planning Review mantém a spec no corredor de planejamento, e um assay que falha faz voltar apenas o ticket que ficou aquém.

Por Que Dois Gates ao Invés de Um

Um único review de fim de execução capturaria problemas — mas só depois que agentes já gastaram tokens implementando um plano ruim ou empilhando tickets sobre um quebrado. O Planning Review captura problemas estruturais antes de qualquer código ser escrito, e o assay por ticket captura problemas de execução no momento em que cada ticket é entregue.

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 assay por ticket 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

Os gates são configuráveis no nível do projeto: você pode ajustar os thresholds de prontidão por camada e quão rigorosamente evidências são exigidas. Essas são configurações do validator do projeto, gerenciadas pelo painel, não chaves do configure (o configure aceita apenas as cinco chaves planas documentadas na referência da CLI).

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 dos padrões de qualidade com todas as opções
• Ciclos de Vida — Como gates se conectam aos dois lifecycles
• Estados da Especificação — Transições de estado disparadas por resultados de gates