O que Explicar Este PR faz?
Lê um pull request do GitHub, entende o que ele altera e escreve uma explicação em linguagem simples. Publica como um comentário no PR para que revisores tenham contexto instantâneo.
Etapa 1: Verificar Configuração
Confirme que o gh está autenticado:
github auth status
Se não estiver autenticado: gh auth login e siga as instruções.
Confirme a entrada. O usuário deve fornecer um dos seguintes:
- Uma URL de PR do GitHub (ex.:
https://github.com/owner/repo/pull/123) - Um número de PR no repositório atual (ex.:
#123) - A palavra "atual" para usar o PR da branch atual
Se não houver entrada, pergunte: "Qual PR devo explicar? Compartilhe a URL, o número do PR ou diga 'atual' para a branch ativa."
Etapa 2: Buscar Contexto do PR
Obter metadados do PR:
github pr view PR_URL_OR_NUMBER --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft
Se isDraft for true, informe ao usuário: "Este PR ainda é um rascunho. A explicação é baseada no estado atual."
Obter o diff:
github pr diff PR_URL_OR_NUMBER
Se o diff tiver mais de 400 linhas, leia o resumo --stat e as primeiras 200 linhas do diff:
github pr view PR_URL_OR_NUMBER --json files
github pr diff PR_URL_OR_NUMBER | head -200
Obter comentários existentes (para evitar repetir o que já está lá):
github pr view PR_URL_OR_NUMBER --json comments --jq '.comments[].body' 2>/dev/null | head -20
Etapa 3: Escrever a Explicação
Escreva dois parágrafos. Leia cada regra antes de escrever.
Parágrafo 1: O que faz (técnico)
- Uma frase por alteração principal
- Nomeie os arquivos, funções ou sistemas específicos que mudaram
- Declare o antes/depois se o diff deixar claro
- Inclua números concretos se presentes no diff (linhas removidas, tabelas excluídas, endpoints adicionados)
- Voz ativa, presente do indicativo
Exemplo:
Substitui o cache de sessão em memória em auth.middleware.ts por um cache baseado em Redis (src/cache/redis.ts). Adiciona os métodos get, set e invalidate ao novo módulo Redis e envolve UserService.getById() com um TTL de 5 minutos. Remove o cache baseado em Map que era limitado a um único processo e causava desvios de sessão em várias instâncias.
Parágrafo 2: Por que é importante (impacto no negócio/produto)
- Quem se beneficia e como
- Qual problema isso resolve ou qual risco reduz
- Se as mensagens de commit contiverem um "porquê", use esse contexto
- Se não houver um "porquê" claro no diff ou commits, omita este parágrafo em vez de adivinhar
Exemplo:
Usuários acessando o endpoint /api/me sob carga estavam recebendo dados de sessão inconsistentes entre instâncias do servidor, causando erros 401 intermitentes. Esta alteração torna o estado da sessão consistente em todas as instâncias e reduz a carga no banco de dados eliminando uma consulta por requisição autenticada.
Regras para ambos os parágrafos:
- Sem travessões — use vírgula ou ponto final
- Sem enchimento: "este PR", "esta alteração", "como você pode ver"
- Sem resultados inventados. Apenas declare impactos que são diretamente visíveis no diff ou nas mensagens de commit
- Se o PR for uma refatoração pura sem mudança de comportamento, diga isso explicitamente: "Refatora X para Y sem nenhuma mudança no comportamento observável."
- Menos de 150 palavras no total
Etapa 4: Auto-Verificação
Antes de publicar, verifique:
- O parágrafo 1 nomeia arquivos ou funções específicos do diff
- Nenhuma métrica ou resultado inventado
- Sem travessões
- Sem frases de enchimento
- Menos de 150 palavras no total
- Se não existir um "porquê" claro, o parágrafo 2 é omitido em vez de adivinhar
Corrija qualquer violação antes de publicar.
Etapa 5: Publicar como Comentário no PR
Apresente a explicação ao usuário. Pergunte: "Pronto para publicar isso como comentário no PR, ou gostaria de editar primeiro?"
Após confirmação, passe o corpo via stdin para lidar com crases, aspas e quebras de linha com segurança:
github pr comment PR_URL_OR_NUMBER --body-file - << 'EOF'
EXPLANATION_HERE
EOF
Após publicar: "Comentário adicionado. Veja em: [url da Etapa 2]"
Se o usuário disser "apenas saída", apresente a explicação em um bloco de código para copiar e colar manualmente sem publicar.