next-friday/next-friday-skills

Rebut

Faça a triagem dos comentários de revisão de código de IA em um pull request e responda com rigor. Verifique cada achado contra o código real, corrija os que são reais, refute os falsos positivos com evidências e responda em cada thread, marcada como triagem automatizada. O humano ainda clica em Resolver.

Este é o contraponto à revisão humana, não uma cópia dela. Revisores de IA como CodeRabbit ou Gemini Code Assist postam muito mais achados, misturam bugs reais com falsos positivos e são cegos ao repositório. Eles não conhecem a configuração local do seu repositório, convenções ou ferramentas, então sinalizam padrões corretos para o seu repositório como bugs, com convicção. A severidade de um bot não é sua correção: um CRITICAL pode ser um falso positivo, e um nit pode esconder um bug real.

Por que os revisores de IA têm sua própria triagem

• Cego ao repositório. O bot não carrega a configuração local do seu repositório — um linter, formatador, ou verificador de tipos, seja qual for sua stack — ou suas regras internas. Ele sinalizará um padrão que sua PRÓPRIA ferramenta EXIGE. Exemplo real (um repositório ESLint): um revisor marcou meta.defaultOptions como CRITICAL "errado", mas a regra de lint require-meta-default-options do repositório o força. Aplicar a sugestão teria quebrado a build. Aplicar cegamente é tão perigoso quanto descartar cegamente.
• Alta taxa de falsos positivos. Muitos achados são especulativos ou apenas de estilo. Alguns são bugs reais que o humano perdeu. O trabalho é separá-los com evidências, não com palpites.
• Confiante e errado. Os rótulos de severidade são heurísticos. Verifique um CRITICAL da mesma forma que um nit.

Quando o revisor é um humano

O pipeline é o mesmo para todo revisor, bot ou humano: verificar contra o código atual → corrigir ou contestar com evidências → responder na thread sob a linha de atribuição → provar cobertura. Um colaborador ou revisor humano também faz parte do loop de triagem: quando uma pessoa solicita uma alteração, corrija e responda, com o mesmo rigor e a mesma trilha de auditoria que o portão humano lê no merge. Apenas o tom muda, porque um humano conhece o repositório, posta menos achados e de maior sinal, e tem um rosto que uma refutação brusca pode ameaçar. Então, quando o revisor é humano:

• Abandone o enquadramento de bot. Não trate a revisão como ruído cego ao repositório e de alto falso positivo; geralmente não é.
• Colabore, não refute de forma rude. Verifique, corrija o que está certo e conteste o que está errado com raciocínio técnico. Nunca concordância performática, nunca um "falso positivo" seco direcionado a um colega; declare a razão em um tom não rude e tecnicamente fundamentado.
• Poste a resposta você mesmo, com a linha de atribuição. Você faz a triagem de threads humanas de forma autônoma, da mesma forma que threads de bot: poste através da conta de triagem, aberta com a linha de atribuição para que o leitor veja uma triagem automatizada e não a revisão por pares do próprio mantenedor. A linha que desconecta o comentário do mantenedor é exatamente o que torna seguro o auto-posting em uma thread humana. A cobertura conta threads humanas também (Passo 5.5), então um achado humano deixado sem resposta mantém a rodada aberta.

Os passos abaixo se aplicam a bots e humanos igualmente; o marcador de atribuição e a resposta automática são usados para ambos. A única adaptação por revisor é o tom acima.

Pré-voo

"${CLAUDE_SKILL_DIR}/scripts/preflight.sh"

preflight.sh confirma que gh está autenticado e que o repositório tem um remote no GitHub. Em caso de pré-requisito ausente, ele imprime a correção no stderr e sai com código diferente de zero; repasse isso e pare. Identifique o PR: o argumento [pr-number], senão o PR para a branch atual (gh pr view --json number).

Passo 1: Reúna cada achado

"${CLAUDE_SKILL_DIR}/scripts/gather-review.sh" <pr>

gather-review.sh imprime um bloco REVIEWS contendo o autor, estado e corpo de cada revisão, e um bloco COMMENTS contendo o autor, path:line, id=<id> e corpo de cada comentário inline, usando o --jq integrado do gh, para que nada seja inventado ou omitido. Liste cada achado com seu autor, path:line, id do comentário necessário para responder e corpo. Inclua os resumos de revisão de nível superior e todos os comentários inline. Não perca nenhum. Marque o autor de cada thread como um bot, reconhecível pelo sufixo de login [bot] mostrado na saída coletada, ou um humano: ambos seguem os Passos 4-6, e uma thread humana adicionalmente leva o ajuste de tom em "Quando o revisor é um humano" acima.

Deixe a rodada se estabilizar antes de fazer a triagem. Revisores disparam de forma assíncrona: um segundo bot geralmente chega minutos após o primeiro, então uma execução de coleta no instante em que o PR é atualizado captura apenas os revisores que postaram até agora. Após a primeira coleta, deixe a rodada se estabilizar com gh pr checks <pr> --watch || true: ele bloqueia até que as verificações do PR terminem e se comporta da mesma forma interativamente e sem cabeça, e essa é a janela na qual os revisores assíncronos postam (o || true impede que a saída não-zero de um PR sem verificações seja lida como uma falha). Em seguida, execute gather-review.sh novamente; se ele trouxe novos achados, a rodada ainda está chegando, então monitore e colete novamente. (Se o PR não tem verificações, --watch retorna imediatamente; e um bot apenas de revisão pode não registrar nenhuma execução de verificação, então em ambos os casos pause brevemente e colete novamente independentemente do estado da verificação. A automação entre rodadas abaixo é o verdadeiro backstop para um revisor que posta após esta estabilização.) Comece a triagem apenas quando uma nova coleta não adicionar nada de novo. Isso trata uma rodada de múltiplos revisores como UMA passagem de triagem em vez de começar nos achados do revisor A enquanto o revisor B ainda está no meio da postagem, o que força uma segunda passagem completa. O limite impede que isso espere para sempre; a automação entre rodadas na última seção é a resposta durável para revisores que postam após a habilidade sair.

Passo 2: Verifique cada achado (o núcleo desta habilidade)

Para cada achado, responda a duas perguntas contra o código atual, não o enquadramento do bot:

1. O problema se reproduz? Reproduza-o como ${CLAUDE_SKILL_DIR}/references/debugging.md descreve: abra o arquivo na linha, trace a lógica, construa a entrada que o bot descreve e verifique o comportamento real. Se é um bug, deve ser demonstrável.
2. A sugestão está correta para ESTE repositório? Execute o portão relevante que o repositório define (seu linter, verificador de tipos ou testes, o que existir). Verifique a convenção documentada. Uma correção que passa no bot, mas falha em um portão do repositório, está errada aqui.

Altere uma coisa de cada vez e verifique novamente. Não faça em lote.

Passo 3: Classifique

Veredito	Significado	Ação
CORRIGIR	Real, reproduz	Corrija (Passo 4)
REFUTAR	Falso positivo para este repositório	Responda com a evidência que o refuta
INTENCIONAL	Escolha deliberada que o bot não vê	Responda explicando a intenção
MENOR	Cosmético, não bloqueante	Anote; corrija ou pule conforme o critério do mantenedor

Passo 4: Corrija os válidos

• Mudança mínima com escopo no achado. Para um bug, escreva o teste falhando primeiro, veja-o falhar, corrija, veja-o passar.
• Execute os portões completos do repositório. Um portão vermelho bloqueia a correção.
• Coloque a rodada inteira em UM commit e envie, nunca um por achado. Verifique e corrija cada achado um de cada vez como no Passo 2, mas prepare todas as correções e commite-as juntas, depois envie uma vez, sob a conta do mantenedor, a mesma conta que possui o PR e posta as respostas. Um envio por achado transforma um ciclo de revisão em vários: cada envio reexecuta o CI e reaciona cada bot, então cinco correções se tornam cinco execuções de CI e cinco ondas de re-revisão. Um commit por rodada é uma execução de CI e uma onda de re-revisão. Capture esse único SHA; cada resposta de correção no Passo 5 o cita. Se esse envio for rejeitado como não-avanço-rápido porque a branch remota avançou (um bump de bot de release ou um merge de "Atualizar branch" do PR adicionou commits durante a rodada), recupere, não pare: git fetch então git rebase origin/<branch>, reexecute os portões e envie novamente, nunca --force; o rebase reescreve o commit, então recapture o novo SHA e cite esse nas respostas do Passo 5, não o SHA obsoleto anterior ao rebase.

Passo 5: Responda em cada thread

Responda ao comentário original para que ele seja encadeado inline, nunca um comentário de PR de nível superior.

Abra cada resposta com a mesma linha de atribuição, em cada thread, sem exceção. Você posta através do token gh do mantenedor, então o GitHub mostra o avatar deles e um leitor assume que eles escreveram. A linha de atribuição nomeia o agente e desconecta o comentário do mantenedor, para que a triagem automatizada nunca seja confundida com a revisão pessoal do mantenedor:

🤖 Triagem automatizada por Claude Code, postada através da conta do mantenedor, não uma revisão pessoal.

Quando o repositório tem um bot ou conta de máquina, poste sob essa identidade para que o autor em si seja não pessoal; a linha de atribuição é o fallback para um token pessoal.

Escreva o corpo em um arquivo. A linha de atribuição torna o corpo multi-linha, o que quebra a citação inline -f body="...". Uma resposta de correção:

> 🤖 Triagem automatizada por Claude Code, postada através da conta do mantenedor, não uma revisão pessoal.

**rebut** corrigido em <sha>: <uma linha sobre a mudança>.

Uma refutação declara a evidência:

> 🤖 Triagem automatizada por Claude Code, postada através da conta do mantenedor, não uma revisão pessoal.

**rebut** não alterando isso: <razão concreta, por exemplo, uma regra de lint do repositório exige; o portão passa>.

Poste cada resposta com post-reply.sh, um achado de cada vez:

"${CLAUDE_SKILL_DIR}/scripts/post-reply.sh" <pr> <comment_id> /tmp/reply.md

post-reply.sh pausa a postagem sob o limite de taxa secundário do GitHub, então confirma que persistiu lendo o id da resposta criada de volta da resposta da API, repetindo com backoff quando uma postagem é limitada. Ele imprime o id da resposta e sai 0 em caso de sucesso; saída 1 significa que a resposta não foi postada (não prossiga, corrija e execute novamente), saída 2 é um argumento ruim. Não faça manualmente a chamada raw gh api .../replies em um loop: postagens consecutivas acionam o limite de taxa e desaparecem, exatamente a falha que este script existe para prevenir. Um achado, uma chamada post-reply.sh, em sequência.

Apenas responda, nunca Resolva. Poste respostas através da API; nunca clique em "Resolver conversa". O botão verde Resolver é do revisor humano, e é como eles verificam o trabalho desta habilidade: eles leem cada thread, confirmam que uma resposta está presente, confirmam que o comentário de resumo existe, e só então resolvem. Se a habilidade resolve, o humano não pode dizer se eles ou o agente fecharam a thread, exatamente a confusão que os faz verificar novamente ou reexecutar a triagem. Toda a saída desta habilidade são respostas mais um comentário de resumo; o botão Resolver permanece deles.

Não deixe nenhuma thread em branco. Cada achado coletado no Passo 1 recebe uma resposta: um CORRIGIR com seu SHA, ou um REFUTAR / INTENCIONAL / MENOR com sua razão. Um achado sem resposta, de um bot ou humano, é indistinguível de trabalho não triado: um revisor não pode dizer se a habilidade foi executada, então eles a invocam novamente e a rodada se repete. Silêncio nunca é um veredito. Discordar de um achado ainda requer uma razão declarada, nunca uma thread vazia.

Passo 5.5: Afirme a cobertura, verifique novamente o CI, então capture a rodada que seu envio de correção provocou

Antes de resumir:

• Afirme a cobertura (sempre). Após postar, consulte novamente o PR e confirme que cada achado, bot ou humano, recebeu uma resposta da conta de triagem:

  "${CLAUDE_SKILL_DIR}/scripts/verify-coverage.sh" <pr>
  

  Ele imprime uma linha por achado (respondido / AUSENTE) então respondido N / M. Saída 0 significa que cada achado tem uma resposta (a rodada está coberta); saída 1 lista cada achado AUSENTE, então reposte esses com post-reply.sh e reexecute até que relate respondido N / N; saída 2 é um erro de leitura/argumento, que não é cobertura, então mostre-o. Isso é executado independentemente dos vereditos, incluindo uma rodada totalmente REFUTAR onde nenhuma correção foi enviada: uma resposta de refutação descartada é tão invisível quanto uma resposta de correção descartada. Nunca prossiga para o Passo 6 enquanto algum achado estiver AUSENTE.

• Verifique novamente o CI. Quando as verificações ainda estão se estabilizando, aguarde com gh pr checks <pr> --watch, então classifique com "${CLAUDE_SKILL_DIR}/scripts/ci-status.sh" <pr>: ci: verde (saída 0) está limpo; ci: falhando (saída 1) bloqueia, então depure; ci: nenhum (saída 3) significa nenhum CI configurado, o que NÃO é uma falha, então anote e prossiga, exatamente como a habilidade implement lida; ci: pendente (saída 4) significa reexecutar --watch, então verifique novamente; um erro de leitura (saída 2) não é "verde", então mostre-o. Confirme o verde com seus próprios olhos; nunca o afirme sem a evidência do script. Se o Passo 4 não mudou nada porque todos os achados foram REFUTAR ou INTENCIONAL, não há novo envio, então esta verificação de CI e a captura de rodada abaixo não têm nada para reacionar; a afirmação de cobertura acima ainda é executada.

• Capture a nova rodada. O envio de correção pode ter desencadeado uma nova rodada de revisores de IA. Execute gather-review.sh e verifique se novos achados apareceram. Em caso afirmativo, a rodada anterior não terminou: esta nova onda é parte da mesma sessão de triagem. Refaça os Passos 2-5 nesses novos achados. Apenas quando um gather-review.sh após a cobertura confirmada não encontrar novos achados é que a rodada está realmente concluída. Continue este loop até que não haja mais achados novos.

Passo 6: Resuma a rodada

Poste um comentário de resumo no PR com post-summary.sh:

"${CLAUDE_SKILL_DIR}/scripts/post-summary.sh" <pr>

post-summary.sh compila uma tabela de cada achado com seu veredito, SHA (se corrigido), e razão. Ele substitui o resumo anterior, se existir, ou cria um novo. A tabela mostra, para cada achado: path:line, autor, veredito, e (se CORRIGIR) o SHA do commit de correção. Este resumo dá ao mantenedor uma verificação visual de que toda a rodada foi tratada. A saída do resumo é a única coisa que o mantenedor precisa ler antes de resolver threads e mesclar. Se a rodada teve achados AUSENTE ou sem solução após o loop do Passo 5.5, o resumo deve dizer "Rodada incompleta" e listar os itens não resolvidos, para que o mantenedor saiba intervir manualmente.

Automação entre rodadas (o backstop durável)

Esta habilidade lida com uma rodada de cada vez e sai. Revisores que postam depois que a habilidade sai são pegos pela próxima execução do agente. A forma mais simples de acionar essa próxima execução é um loop externo que escuta notificações de push no repositório e reexecuta a habilidade. Em configurações que não permitem escuta contínua, o mantenedor executa manualmente a habilidade novamente quando novos revisores aparecem.

---

A disciplina de verificação vinculada a partir do portão duro: ${CLAUDE_SKILL_DIR}/references/verification.md. O guia de depuração referenciado: ${CLAUDE_SKILL_DIR}/references/debugging.md.