babysit-pr

Babá de PR (Pull Request)

Objetivo

Ficar de olho em um PR persistentemente até que um destes resultados finais ocorra:

• O PR é mesclado ou fechado.
• Surge uma situação que requer ajuda do usuário (por exemplo, problemas de infraestrutura de CI, falhas instáveis repetidas após o orçamento de repetição ser esgotado, problemas de permissão ou ambiguidade que não pode ser resolvida com segurança).
• Marco opcional de handoff: o PR está atualmente verde + mergeável + sem revisões pendentes. Trate isso como um estado de progresso, não como uma parada do observador, para que comentários de revisão que cheguem tarde ainda sejam exibidos prontamente enquanto o PR permanecer aberto.

Não pare apenas porque um único snapshot retorna idle enquanto os checks ainda estão pendentes.

Entradas

Aceite qualquer um dos seguintes:

• Nenhum argumento de PR: infira o PR da branch atual (--pr auto)
• Número do PR
• URL do PR

Fluxo de Trabalho Principal

1. Quando o usuário pedir para "monitorar"/"observar"/"cuidar" de um PR, inicie o modo contínuo do observador (--watch), a menos que você esteja intencionalmente fazendo um snapshot de diagnóstico único.
2. Execute o script do observador para capturar o estado do PR/revisão/CI (ou consuma cada snapshot transmitido de --watch).
3. Inspecione a lista actions na resposta JSON.
4. Se diagnose_ci_failure estiver presente, inspecione os logs de execução com falha e classifique a falha.
5. Se a falha for provavelmente causada pela branch atual, corrija o código localmente, faça commit e push. Não corrija testes instáveis aleatórios, infraestrutura de CI, interrupções de dependências, problemas de runner ou outras falhas não relacionadas à branch.
6. Se process_review_comment estiver presente, inspecione os itens de revisão publicados exibidos e decida se deve resolvê-los.
7. Se um item de revisão for acionável e correto, corrija o código localmente, faça commit, push e, em seguida, resolva o thread de revisão associado apenas quando permitido pela política de mutação de estado do GitHub abaixo.
8. Não poste respostas a comentários/threads de revisão de autores humanos, a menos que o usuário confirme explicitamente a resposta exata. Se um item de revisão humano não for acionável, já foi resolvido ou não for válido, exiba o item e a resposta recomendada ao usuário em vez de responder no GitHub.
9. Se a falha for provavelmente instável/não relacionada e retry_failed_checks estiver presente, execute novamente os jobs com falha com --retry-failed-now.
10. Se tanto feedback de revisão acionável quanto retry_failed_checks estiverem presentes, priorize o feedback de revisão primeiro; um novo commit reativará o CI, então evite executar novamente checks instáveis no SHA antigo, a menos que você adie intencionalmente a alteração de revisão.
11. Em cada loop, procure por novos feedbacks de revisão antes de agir com base em falhas de CI ou estado de mergeabilidade, em seguida, verifique a mergeabilidade / status de conflito de merge (por exemplo, via gh pr view) junto com o CI.
12. Após qualquer push ou nova execução, retorne imediatamente ao passo 1 e continue a verificar o SHA/estado atualizado.
13. Se você estava usando --watch antes de pausar para corrigir/fazer commit/push, relance --watch na mesma volta imediatamente após o push (não espere o usuário invocar novamente a skill).
14. Repita a verificação até que stop_pr_closed apareça ou um bloqueador que exija ajuda do usuário seja alcançado. Um PR verde + sem revisões pendentes + mergeável é um marco de progresso, não um motivo para parar o observador enquanto o PR ainda estiver aberto.
15. Mantenha a propriedade do terminal/sessão: enquanto a babá estiver ativa, continue consumindo a saída do observador na mesma volta; não deixe um processo --watch destacado em execução e termine a volta como se o monitoramento estivesse completo.

Comandos

Snapshot único

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --once

Observação contínua (JSONL)

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --watch

Acionar ciclo de repetição instável (apenas quando o observador indicar)

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr auto --retry-failed-now

Alvo de PR explícito

python3 .codex/skills/babysit-pr/scripts/gh_pr_watch.py --pr <numero-ou-url> --once

Classificação de Falhas de CI

Use comandos gh para inspecionar execuções com falha antes de decidir repetir.

• gh run view <run-id> --json jobs,name,workflowName,conclusion,status,url,headSha
• gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs -X GET -f per_page=100
• gh api repos/<owner>/<repo>/actions/jobs/<job-id>/logs > /tmp/codex-gh-job-<job-id>-logs.zip
• gh run view <run-id> --log-failed como fallback após a execução geral do workflow estar completa

gh run view --log-failed tem escopo de execução de workflow e pode não expor logs de jobs com falha até que a execução geral termine. Para diagnóstico mais rápido, primeiro verifique os jobs da execução e, assim que um job específico falhar, busque os logs desse job diretamente do endpoint de logs de jobs do Actions. O observador inclui uma lista failed_jobs com o job_id e logs_endpoint de cada job com falha, quando o GitHub expõe um.

Prefira tratar falhas como relacionadas à branch quando os logs dos jobs com falha apontarem para código alterado (compilação/teste/lint/typecheck/snapshots/análise estática nas áreas tocadas).

Prefira tratar falhas como instáveis/não relacionadas quando os logs mostrarem problemas transitórios de infra/externo (timeouts, falhas de provisionamento de runner, interrupções de registro/rede, erros de infraestrutura do GitHub Actions).

Não tente corrigir falhas instáveis/não relacionadas alterando testes, scripts de build, configuração de CI, pins de dependência ou código adjacente à infraestrutura, a menos que os logs conectem claramente a falha à branch do PR. Para falhas instáveis/não relacionadas, execute novamente apenas quando o observador recomendar retry_failed_checks; caso contrário, aguarde ou pare para ajuda do usuário.

Se a classificação for ambígua, realize uma tentativa de diagnóstico manual antes de escolher repetir.

Leia .codex/skills/babysit-pr/references/heuristics.md para uma lista de verificação concisa.

Tratamento de Comentários de Revisão

O observador exibe itens de revisão de:

• Comentários de issue do PR
• Comentários de revisão inline
• Envios de revisão (COMMENT / APPROVED / CHANGES_REQUESTED)

Aja apenas em feedbacks publicados. Ignore envios de revisão no estado PENDING do GitHub e comentários inline anexados a essas revisões pendentes. Não marque feedback de revisão pendente como visto; ele deve ser elegível para ser exibido após o revisor enviar a revisão.

Ele intencionalmente exibe feedback do bot revisor Codex (por exemplo, comentários/revisões de chatgpt-codex-connector[bot]) além do feedback do revisor humano. A maioria do ruído de bot não relacionado ainda deve ser ignorado. Por segurança, o observador só exibe automaticamente autores de revisão humanos confiáveis (por exemplo, OWNER/MEMBER/COLLABORATOR do repo, mais o operador autenticado) e bots de revisão aprovados, como o Codex. Em um arquivo de estado do observador novo, feedback de revisão publicado existente não resolvido pode ser exibido imediatamente (não apenas comentários que chegam após o início do monitoramento). Isso é intencional para que comentários de revisão já abertos não sejam perdidos.

Quando você concorda com um comentário e ele é acionável:

1. Corrija o código localmente.
2. Faça commit com codex: address PR review feedback (#<n>).
3. Faça push para a branch head do PR.
4. Após o push bem-sucedido, resolva o thread de revisão do GitHub associado apenas quando permitido pela política de mutação de estado do GitHub abaixo.
5. Retome a observação no novo SHA imediatamente (não pare após relatar o push).
6. Se o monitoramento estava sendo executado no modo --watch, reinicie --watch imediatamente após o push na mesma volta; não espere o usuário pedir novamente.

Não poste respostas automaticamente para comentários/threads de revisão do GitHub de autoria humana. Se você discorda de um comentário humano, acredita que ele não é acionável/já foi resolvido ou precisa responder a uma pergunta, relate o item ao usuário com uma resposta sugerida e aguarde confirmação explícita antes de postar qualquer coisa no GitHub. Se o usuário aprovar uma resposta, prefixe-a com [codex] para que fique claro que a resposta é automatizada e não do usuário humano. Se o observador posteriormente exibir sua própria resposta aprovada porque o operador autenticado é tratado como um autor de revisão confiável, trate esse item de autoria própria como já tratado e não responda novamente. Se um comentário/thread de revisão de código já estiver marcado como resolvido no GitHub, trate-o como não acionável e ignore-o com segurança, a menos que novo feedback de acompanhamento não resolvido apareça.

Política de Mutação de Estado do GitHub

Você pode ler qualquer estado de PR necessário para monitoramento. Escritas devem obedecer a esta política.

Você pode fazer push de PRs para atualizar o código sob revisão ou para forçar novas execuções de CI, conforme descrito acima.

Você pode resolver threads de comentários de revisão do humano que solicitou a babá ou do bot de revisão Codex. Ao resolver, deixe um comentário prefixado com [from Codex]: e explique quais alterações você fez e qual commit as inclui. Não toque em threads de revisão se outros humanos, além do usuário que solicitou a babá, participaram.

Antes de fazer qualquer alteração, busque o estado do PR você mesmo, em vez de confiar na saída do script do observador de PR.

A menos que explicitamente solicitado, não:

• comente em threads de revisão de outros humanos, comunique-se com o usuário no chat
• resolva threads de revisão de humanos que não sejam o usuário
• interaja com outros humanos que não sejam o usuário
• marque PRs como rascunhos ou prontos para revisão
• feche ou reabra PRs

Em geral, nunca aja no GitHub de maneiras que tornariam difícil saber se você ou o usuário fez algo visível para outros humanos. Em caso de dúvida, peça esclarecimento ao usuário no chat.

Regras de Segurança do Git

• Trabalhe apenas na branch head do PR.
• Evite comandos git destrutivos.
• Não mude de branch a menos que seja necessário para recuperar o contexto.
• Antes de editar, verifique se há alterações não commitadas não relacionadas. Se houver, pare e pergunte ao usuário.
• Após cada correção bem-sucedida, faça commit e git push, depois execute novamente o observador.
• Se você interrompeu uma sessão --watch ativa para fazer a correção, reinicie --watch imediatamente após o push na mesma volta.
• Não execute vários processos --watch simultâneos para o mesmo PR/arquivo de estado; mantenha uma sessão de observador ativa e reutilize-a até que ela pare ou você a reinicie intencionalmente.
• Um push não é um resultado final; continue o loop de monitoramento a menos que uma condição de parada estrita seja atendida.

Mensagens de commit padrão:

• codex: fix CI failure on PR #<n>
• codex: address PR review feedback (#<n>)

Padrão de Loop de Monitoramento

Use este loop em uma sessão Codex ativa:

1. Execute --once.
2. Leia actions.
3. Primeiro, verifique se o PR agora está mesclado ou fechado; se sim, relate esse estado final e pare de verificar imediatamente.
4. Verifique o resumo do CI, novos itens de revisão e status de mergeabilidade/conflito.
5. Diagnostique falhas de CI e classifique como relacionadas à branch vs instáveis/não relacionadas. Se a execução geral ainda estiver pendente, mas failed_jobs já incluir um job com falha, busque os logs desse job e diagnostique imediatamente, em vez de esperar a execução completa do workflow. Corrija apenas quando a falha for relacionada à branch.
6. Para cada item de revisão exibido de outro autor, corrija/commit/push se for acionável, depois resolva-o apenas quando permitido pela política de mutação de estado do GitHub acima. Se não for acionável, já foi resolvido ou exigir uma resposta por escrito, exiba-o ao usuário com uma resposta sugerida em vez de postar automaticamente. Se um snapshot posterior exibir sua própria resposta aprovada, trate-a como informacional e continue sem responder novamente.
7. Processe comentários de revisão acionáveis antes de repetições instáveis quando ambos estiverem presentes; se uma correção de revisão exigir um commit, faça push e pule a repetição de checks com falha no SHA antigo.
8. Repita checks com falha apenas quando retry_failed_checks estiver presente e você não estiver prestes a substituir o SHA atual por um commit de correção de revisão/CI. Não faça alterações de código para instabilidades não relacionadas ou falhas de infraestrutura apenas para deixar o CI verde.
9. Se você fez push de um commit, resolveu um thread de revisão elegível ou acionou uma repetição, relate a ação brevemente e continue verificando (não pare). Se um comentário de revisão humano precisar de uma resposta escrita no GitHub, pare e peça confirmação antes de postar.
10. Após um push de correção de revisão, reinicie proativamente o monitoramento contínuo (--watch) na mesma volta, a menos que uma condição de parada estrita já tenha sido alcançada.
11. Se tudo estiver passando, mergeável, não bloqueado por aprovação de revisão necessária e não houver itens de revisão não resolvidos, relate que o PR está atualmente pronto para ser mesclado, mas mantenha o observador em execução para que novos comentários de revisão sejam exibidos rapidamente enquanto o PR permanecer aberto.
12. Se bloqueado por um problema que requer ajuda do usuário (interrupção de infra, repetições instáveis esgotadas, solicitação de revisor pouco clara, permissões), relate o bloqueador e pare.
13. Caso contrário, durma de acordo com a cadência de verificação abaixo e repita.

Quando o usuário pedir explicitamente para monitorar/observar/cuidar de um PR, prefira --watch para que a verificação continue autonomamente em um único comando. Use snapshots --once repetidos apenas para depuração, teste local ou quando o usuário pedir explicitamente uma verificação única. Não pare para perguntar ao usuário se deve continuar verificando; continue autonomamente até que uma condição de parada estrita seja atendida ou o usuário interrompa explicitamente. Não devolva o controle ao usuário após um push de correção de revisão apenas porque um novo SHA foi criado; reiniciar o observador e reentrar no loop de verificação faz parte da mesma tarefa de babá. Se um processo --watch ainda estiver em execução e nenhuma condição de parada estrita foi alcançada, a tarefa de babá ainda está em andamento; continue transmitindo/consumindo a saída do observador em vez de encerrar a volta.

Cadência de Verificação

Mantenha a verificação de revisão agressiva e continue monitorando mesmo depois que o CI ficar verde:

• Enquanto o CI não estiver verde (pendente/executando/na fila ou falhando): verifique a cada 1 minuto.
• Depois que o CI ficar verde: continue verificando na cadência base enquanto o PR permanecer aberto para que comentários de revisão recém-postados sejam exibidos prontamente, em vez de esperar por um backoff longo de estado verde.
• Redefina a cadência imediatamente sempre que algo mudar (novo commit/SHA, alterações de status de check, novos comentários de revisão, alterações de mergeabilidade, alterações de decisão de revisão).
• Se o CI parar de ficar verde novamente (novo commit, nova execução ou regressão): permaneça na cadência base de verificação.
• Se qualquer verificação mostrar que o PR foi mesclado ou fechado: pare de verificar imediatamente e reporte o estado final.

Condições de Parada (Estritas)

...