GitHub Deep Review
Revise como Peter: alta confiança, evidência em primeiro lugar, ciente do código e disposto a dizer "não comprovado" quando o rastro é fraco. O objetivo não é um resumo genérico. O objetivo é entender a classe do bug, encontrar a causa real se possível, decidir a melhor correção após ler código suficiente e apontar se uma refatoração maior melhoraria o design.
Início
Use gh, não navegação web, para referências do GitHub:
gh issue view <n> --json number,title,state,author,body,comments,labels,updatedAt,url
gh pr view <n> --json number,title,state,author,body,comments,reviews,files,commits,statusCheckRollup,mergeStateStatus,headRefName,headRepositoryOwner,url
gh pr diff <n> --patch
Para PRs, colete o contexto do autor por padrão, a menos que o autor seja Peter (steipete ou uma conta obviamente de propriedade do Peter). Use o fluxo de trabalho local em ~/Projects/agent-scripts/skills/github-author-context/SKILL.md e inclua um pequeno bloco Contexto do autor: próximo ao topo da revisão quando o autor não for Peter.
Após merge/rejeição/fechamento/revisão, use o mesmo fluxo de trabalho de contexto do autor para anexar uma nota de contribuidor apenas quando a interação criar sinal durável para revisões futuras.
Para revisão local do repositório, inspecione também:
git status --short --branch
git fetch origin
git log --oneline --decorate -20
rg "<símbolo/erro/config/endpoint chave>"
Se o repositório tiver instruções locais, skills de issue/PR, listas de documentação, orientações de teste ou runbooks de mantenedor, leia-os antes de decidir.
Contrato de Revisão
Sempre responda estas perguntas, explicitamente:
- URL/ref: número da issue ou PR e superfície afetada.
- Qual é o bug ou comportamento que está sendo corrigido?
- Podemos identificar a causa raiz? Se sim, onde no código e por quê. Se não, qual evidência está faltando.
- Para regressões, quem/o que a introduziu e quando? Inclua proveniência de commit/PR quando rastreável por histórico limitado; diga desconhecido em vez de adivinhar.
- A correção atual/proposta é a melhor correção possível após ler o código adjacente?
- Uma refatoração maior melhoraria a correção, clareza ou manutenibilidade futura?
- Que prova existe: testes, reprodução ao vivo, verificações de CI, documentação, documentação/código-fonte de dependências, comportamento atual/distribuído.
- O que permanece arriscado ou não verificado.
Profundidade de Leitura de Código
Leia além do primeiro arquivo modificado. Siga o caminho de chamada real:
- ponto de entrada -> validação/interpretação -> roteamento/despacho -> módulo proprietário -> auxiliar compartilhado -> limite de persistência/rede/tempo de execução
- configuração/esquema/documentação -> uso em tempo de execução -> caminho de correção/doctor/migração
- código proprietário de provedor/canal/plugin -> costura genérica do núcleo, apenas se vários proprietários precisarem dela
- testes ao redor da superfície modificada mais testes de regressão adjacentes
Quando o comportamento depender de uma dependência, leia a documentação/código-fonte/tipos upstream ou o contrato atual do pacote antes de assumir.
Prefira fonte atual e prova executável em vez de comentários de issues. Trate comentários desatualizados, CI antigo e comportamento de versões antigas como dicas até serem verificados novamente.
Proveniência
Para revisões de bugs/regressões, inclua uma resposta Proveniência: compacta quando possível:
- Use
git log -S/-G,git blame, PRs/issues vinculados e testes. - Separe autor, committer/mergedor e autor do PR atual quando forem diferentes.
- Formule como
introduzido por,tornado visível poroucarregado adiante por. - Inclua confiança:
claro,prováveloudesconhecido. - Para funcionalidades, documentação, refatorações ou bugs não rastreáveis, escreva
N/Aou diga qual evidência está faltando.
Padrão de Qualidade de Correção
Boas correções geralmente:
- vivem no limite de propriedade onde o bug pertence
- preservam o comportamento público/compatível com versões anteriores, a menos que a issue seja sobre removê-lo
- adicionam um teste de regressão na menor costura significativa
- evitam casos especiais amplos, migrações ocultas, sentinelas semânticas e IDs de provedor/canal no núcleo genérico
- atualizam documentação/changelog quando o comportamento visível ao usuário muda
- falham claramente em caminhos de tempo de execução e reparam através de caminhos de doctor/migração quando esse é o contrato estabelecido
Aponte quando uma correção é apenas no nível do sintoma. Se uma refatoração ligeiramente maior tornar o invariante óbvio e reduzir bugs futuros, recomende-a. Se a refatoração aumentar o risco sem melhorar a classe do bug, diga isso.
Forma da Revisão de PR
Lide com descobertas ao revisar um PR. Descobertas precisam de referências de arquivo/linha/símbolo e um modo de falha concreto. Evite comentários vagos do tipo "considere".
Se não houver problemas bloqueantes:
- diga que não foram encontrados problemas bloqueantes de correção
- liste a prova mais forte verificada
- nomeie risco residual/lacunas de teste
- responda se o design é a melhor forma disponível
Não aprove, comente, feche, faça merge, faça push ou publique a menos que o usuário tenha solicitado essa ação.
Forma da Revisão de Issue
Para bugs/issues:
- Reconstrua o cenário do relator e a versão/superfície afetada.
- Verifique se o
mainatual já corrige isso. - Reproduza ou crie uma prova local/ao vivo mínima quando possível.
- Se claro, identifique a causa raiz e a correção proposta.
- Se resolvido no
main, apenas comente/fechar quando o usuário solicitar; inclua prova e o commit/PR canônico se conhecido.
Se a reprodução não for viável, diga exatamente o que a impede e qual evidência tornaria a decisão confiável.
Template de Saída
Use esta forma quando o usuário perguntar "o que é isso", "esta é a melhor correção" ou "o que corrigimos":
Ref: #123 / PR #456
Superfície: <runtime/CLI/provedor/canal/documentação>
Bug: <uma ou duas frases>
Causa: <caminho de código + confiança>
Proveniência: <introduzido/tornado visível/carregado adiante por commit/PR/data, ou N/A/desconhecido>
Melhor correção: <o que deve mudar e por quê>
Refatoração: <sim/não, forma específica>
Prova: <testes/ao vivo/CI/fonte/documentação de dependência>
Risco: <incerteza restante>
Seja conciso, mas não pule a decisão de causa/correção/refatoração/prova.