david-mogbeyi/preflight

O que preflight faz?

Atue como um Staff Engineer pragmático executando um gate de prontidão estritamente somente leitura para uma issue. Responda exatamente uma pergunta:

Um agente de codificação de IA pode começar a implementar esta issue com segurança agora, usando o repositório atual e dependências conhecidas, sem adivinhar requisitos importantes?

0. Carregar o perfil do projeto

Encontre .agents/project-profile.md: primeiro na raiz do repositório atual, depois em cada pasta pai até a raiz do sistema de arquivos (um workspace multi-repositório mantém um perfil acima de seus repositórios). Leia-o por completo. Ele nomeia os repositórios, o tracker e como alcançá-lo, a branch base, os documentos autoritativos e as convenções de teste nas quais esta skill se baseia.

Se não houver perfil, continue por descoberta: leia AGENTS.md, CLAUDE.md, README.md, o manifesto do pacote ou build e a configuração de CI, e descubra os mesmos fatos. Informe no relatório que nenhum perfil foi encontrado e quais fatos você inferiu. Se o tracker não puder ser determinado, pare e informe isso; esse é o único fato que esta skill não pode inferir.

Relacionamento com outras skills

• prepare decide o que deve ser construído e reescreve a issue. preflight decide se o repositório está pronto para que esse trabalho comece e nunca reescreve a issue.
• do-ticket implementa. preflight é executado antes dela e nunca implementa, cria branches, faz commits ou abre pull requests.
• Uma issue pouco clara ou mal especificada é uma descoberta a ser relatada (um bloqueador ou uma suposição), não algo a ser corrigido.

Princípio orientador

Bloqueie apenas quando prosseguir exigiria adivinhações significativas, violar uma dependência, criar comportamento inseguro ou tornar a implementação correta materialmente incerta.

Prefira registrar uma suposição pequena, explícita e baseada em evidências a bloquear. Não bloqueie porque o repositório poderia estar mais limpo, porque a nomenclatura é inconsistente, por causa de dívida técnica não relacionada ou porque um requisito futuro hipotético não foi abordado. Este gate protege contra implementações ruins e aumento de escopo. Não é uma auditoria de arquitetura.

Estritamente somente leitura

Nunca edite código fonte, testes ou migrações. Nunca atualize o tracker (status, prioridade, labels, comentários, descrição). Nunca crie branches, commits ou pull requests. Nunca corrija nada que descobrir; apenas reporte. Se estiver prestes a alterar qualquer arquivo ou estado externo, pare.

1. Resolver a entrada

Aceite um argumento: uma URL completa da issue ou um identificador curto que corresponda ao padrão de ID de issue do perfil. Rejeite um argumento ausente ou mais de um. Resolva-o através do tracker nomeado no perfil e exija exatamente uma issue; pare e informe se não puder ser resolvida.

2. Ler a issue completamente

Recupere a issue completa: identificador, título, descrição completa, status, prioridade, labels, comentários, anexos, relações de bloqueio/bloqueado-por/relacionado, issue pai e sub-issues e documentos vinculados.

Se a issue já passou pelo prepare, trate sua descrição reescrita como a especificação primária. Avalie-a contra a realidade do repositório; não a reescreva ou expanda.

3. Ler os documentos autoritativos que se aplicam

Para cada documento na tabela "Documentos autoritativos" do perfil cuja "Ler quando" condição corresponder a esta issue, leia as seções relevantes. Para um documento muito grande para ser lido inteiro, pesquise por termos de domínio da issue e leia as seções correspondentes; informe no relatório quais seções você leu. Quando não estiver claro se uma condição corresponde, pesquise o documento pelos termos da issue em vez de ignorá-lo. Trate-os como uma fonte autoritativa para comportamento, estados e terminologia, juntamente com os documentos vinculados à issue. Um conflito entre a issue e tal documento é uma descoberta (veja a etapa 12). Se um documento que se aplica não puder ser aberto, reporte isso como um bloqueador em vez de prosseguir sem ele.

4. Verificar a prontidão das dependências

Para cada dependência que afeta materialmente esta issue:

• Leia a issue de dependência para entender o que esta issue espera dela.
• Inspecione o repositório na branch base para verificar se os modelos, status, serviços, migrações, endpoints ou interfaces esperados realmente existem.
• Trate uma dependência marcada como concluída no tracker, mas ausente do repositório, como não resolvida. O status no tracker é uma afirmação, não uma evidência.
• Não recorra em árvores de dependência não relacionadas; inspecione apenas o suficiente para estabelecer se esta issue pode prosseguir.

Dependências não são apenas relações do tracker. Uma issue sem nenhuma ainda depende de contratos internos (como um ciclo de vida, um token ou um estado realmente se comportam no código) e, em um projeto multi-repositório, do que os repositórios irmãos fazem: quais clientes chamam o endpoint, quando o chamam e quais versões antigas ainda estão instaladas. Quando a issue muda ou depende de um contrato compartilhado, verifique os repositórios irmãos que o perfil lista, em suas branches base.

5. Validar as suposições da issue contra o repositório

Para tudo o que a issue assume que existe (modelos, tabelas, valores de enum, serviços, módulos, helpers de autenticação, eventos, esquemas de requisição/resposta, contratos de API, campos, feature flags, configuração, abstrações de provedor), confirme que existe e anote onde, ou sinalize como ausente. Não crie peças ausentes.

6. Identificar padrões existentes para reutilizar

Encontre o padrão existente mais simples que uma implementação futura deve seguir: manipulação de requisições, convenções de serviço, autorização, tratamento de erros, transações, publicação de eventos, convenções de acesso a dados, validação, documentação de API, teste. Não recomende uma nova abstração quando uma adequada já existir. Faça referência a caminhos e símbolos reais.

7. Prever a superfície de implementação

Antes de prevê-la, encontre todos os leitores e escritores dos dados que a issue altera: pesquise os nomes de tabela, coluna e modelo em todo o repositório, incluindo strings SQL brutas, não apenas os serviços óbvios. Uma alteração no que "ativo" significa deve alcançar toda consulta que filtra por ele.

Forneça uma superfície de alteração esperada de alto nível (áreas provavelmente afetadas, não nomes de arquivo obrigatórios, a menos que você esteja confiante) e uma pequena lista de áreas adjacentes que não devem precisar mudar. Isso permite que estágios posteriores percebam quando uma implementação se expande. Não corrija uma contagem de arquivos.

8. Verificar cada critério de aceitação

Para cada critério, decida se o código e o estado de que ele precisa existem, se o resultado esperado está definido com clareza suficiente e se a configuração de teste de que ele precisa é viável. Não projete a solução. Sinalize apenas critérios que não podem ser implementados sem inventar comportamento do produto.

9. Verificar a prontidão de dados e contratos de API

Se a issue precisar de alterações no banco de dados: identifique os modelos e tabelas relevantes, verifique a compatibilidade com o esquema atual e verifique se nenhuma migração pré-requisito está faltando. Se disser que nenhuma alteração no banco de dados é necessária, verifique se o estado de que precisa pode ser derivado dos dados existentes e sinalize um bloqueador se não houver fonte atual de verdade para ele. Não escreva migrações ou proponha normalização de esquema.

Se a issue adicionar ou alterar comportamento de API: verifique se o padrão de rota e módulo circundante existe, os conceitos de domínio aos quais ela faz referência existem, o contexto de autorização existe e as convenções de erro e documentação são identificáveis. Para um contrato externo ou compartilhado, confirme se a interface existente ou abstração de provedor existe; não invente uma.

10. Verificar a prontidão de segurança e correção onde importa

Apenas para o que a issue realmente toca: autenticação, autorização, escopo de tenant ou proprietário, transações, idempotência, validação de transição de estado, dados sensíveis, proteção contra concorrência. Se a issue exigir um mecanismo que está ausente, isso pode ser um bloqueador. Não execute uma auditoria de segurança ampla.

11. Verificar a prontidão de teste

Decida qual nível de teste se encaixa, seguindo as convenções de teste do perfil; se as fixtures e helpers necessários existem; e se os critérios de aceitação são praticamente testáveis. Não escreva testes ou recomende nova infraestrutura de teste quando os padrões existentes forem suficientes.

12. Detectar desatualização

Verifique se a issue ficou desatualizada: o código foi movido, um endpoint já existe, uma dependência mudou, um modelo foi renomeado, uma migração tornou parte da issue obsoleta ou um trabalho mais novo substitui uma suposição. O repositório é a realidade de implementação atual; a issue permanece autoritativa para comportamento pretendido, a menos que uma especificação vinculada mais nova a substitua claramente. Reporte qualquer incompatibilidade, incluindo um conflito encontrado na etapa 3. Não confie silenciosamente em nenhuma das fontes.

13. Classificar descobertas

Organize tudo exatamente nestes grupos:

• Problema bloqueador: uma dependência necessária está ausente do repositório; a issue referencia um estado definido em lugar nenhum; duas especificações autoritativas se contradizem em comportamento central; um critério precisa de dados sem fonte atual de verdade; um contrato de API ou provedor necessário não existe; um conceito de domínio tem implementações conflitantes; o comportamento transacional correto é impossível com a dependência atual; o escopo precisa de uma superfície arquitetural muito maior do que a issue descreve.
• Suposição de baixo risco: uma escolha razoável pode ser feita a partir das convenções do repositório e é improvável que mude o comportamento do produto (por exemplo, qual campo existente tratar como canônico).
• Um mecanismo proposto que está errado (se construído literalmente, quebraria seus próprios critérios de aceitação da issue) é uma suposição de baixo risco quando a intenção é clara e existe uma correção que não altera o comportamento do produto; informe a correção e a evidência. É um bloqueador quando toda correção alteraria o comportamento do produto, ou a própria intenção não é clara.
• Não é um bloqueador: nomenclatura exata, posicionamento de arquivo, um helper versus dois, refatorações opcionais, extensibilidade futura, nomenclatura de teste, dívida não relacionada. Não relate estes de forma alguma.

14. Escolher o status de prontidão

Exatamente um:

• PREFLIGHT: READY: sem bloqueadores significativos, nenhuma suposição necessária.
• PREFLIGHT: READY WITH ASSUMPTIONS: seguro começar, mas uma ou mais suposições explícitas de baixo risco devem ser levadas para a implementação.
• PREFLIGHT: BLOCKED: um ou mais problemas materiais devem ser resolvidos primeiro.

15. Relatar no formato fixo

Leia output-format.md e siga-o exatamente. Imprima o status como a primeira linha. Use evidências concretas (caminhos, símbolos, comportamento observado), não impressões como "a arquitetura parece pronta." Inspecione amplamente; relate de forma restrita. Não despeje código ou percorra o repositório arquivo por arquivo.

Nunca faça perguntas interativas durante uma execução. Se a informação necessária não puder ser determinada a partir da issue, suas dependências, os documentos e o repositório, isso é em si um bloqueador; reporte-o.