branch-review-tracker

Branch review tracker

Uma revisão de um branch que é corrigida ao longo de várias rodadas. Cada rodada re-revisa o branch e atualiza uma página: uma lista numerada de problemas, cada um com um status e um popup de Detalhes que fornece a evidência, o commit responsável e os locais a serem observados.

A página é um Artefato do claude.ai e é o registro da revisão. É somente leitura para os espectadores: apenas Claude altera um status, conforme a revisão e as correções progridem. Uma nova sessão é retomada a partir do pequeno context.json da página, não da conversa ou de arquivos locais.

O rastreador mantém três arquivos:

• index.html: a página, uma cópia de assets/tracker.html;
• issues.json: todos os problemas e o registro da sessão;
• context.json: as notas de retomada e um índice dos problemas para a próxima sessão, o prompt que a inicia e a pequena lista do que aguarda o usuário, que é a única parte que a página mostra.

1. Perguntar o que revisar

Reúna candidatos primeiro e, em seguida, pergunte tudo em uma única chamada AskUserQuestion. Pule uma pergunta cuja resposta veio com a invocação, por exemplo, um número de PR ou URL.

git for-each-ref --sort=-committerdate --count=6 --format='%(refname:short)' refs/heads
git symbolic-ref --short refs/remotes/origin/HEAD      # a base padrão
git log --format=%s <base>..<target> | grep -oE '[A-Z]+-[0-9]+' | sort -u
gh pr list --head <target> --json number,url,title     # ou: glab mr list --source-branch <target>

Pergunta	Opções
Branch de destino	o branch head do PR se um PR foi fornecido; caso contrário, os três branches locais mais recentemente atualizados, que não sejam o base
Branch base	o branch padrão do remoto (Recomendado), depois outros branches de longa duração, se houver
Ticket	IDs encontrados no nome do branch e nos assuntos de seus commits; Nenhum ticket

O usuário sempre pode digitar outro valor. Faça a pergunta do ticket depois que o branch for conhecido, ou derive suas opções do destino mais provável.

2. Verificar o ambiente

Execute o script de pré-verificação e mostre sua tabela ao usuário:

<esta skill>/scripts/preflight --target <branch> [--base <base>] [--ticket <id>]

Ele verifica o repositório, ambos os refs, o checkout do usuário, se o branch local corresponde ao head do PR, o PR no host, filtros de checkout que podem impedir git worktree e as CLIs que a revisão usa. Código de saída 2 significa um bloqueador; 1 significa apenas avisos. Ele não verifica as ferramentas de build do projeto: essas pertencem às skills auxiliares do projeto.

O script busca ambos os branches. Ele obtém a base da origin, onde está atual, e o destino do clone, onde o autor pode tê-lo enviado. Revise em relação aos refs que ele imprime. Se ele avisar que o branch local difere do head do PR, revise o head do PR: leia-o com git show <sha>:<caminho> em vez de fazer checkout.

Em seguida, verifique as ferramentas desta sessão, que um script não pode ver, e adicione-as à tabela:

Necessário para	Ferramenta	Sem ela
a revisão	skill code-review, ou a ferramenta Agent	bloqueador
a página	ferramenta Artifact	mantenha os arquivos no scratchpad e forneça seus caminhos ao usuário após cada rodada; avise sobre isso
o contexto do ticket, e postagem de tickets	Ferramentas Atlassian (getJiraIssue, createJiraIssue)	revise sem ele; avise sobre isso
os comentários e verificações do PR	gh ou glab, autenticados	revise apenas o branch; avise sobre isso

Em seguida, procure as skills auxiliares do projeto, conforme descrito em "Skills auxiliares" abaixo, e adicione uma linha por auxiliar à tabela: encontrada, com seu nome, ou ausente, com o que a revisão deixará de ter.

Pare em um bloqueador e diga o que está faltando. Nos avisos, diga o que a revisão não cobrirá e prossiga.

Se o ticket puder ser lido, busque seu resumo e status. Escreva um status entre parênteses após o id: PROJ-123 (em andamento).

3. Primeira rodada

1. Revisar. Invoque code-review em <destino> contra <base>, ou no número do PR. Diga ao revisor para ler outros commits com git show <rev>:<caminho> e nunca fazer checkout de nada no diretório do usuário.

2. Revisar a prosa, conforme descrito em "A revisão de prosa" abaixo. code-review procura por defeitos no código e não cobre isso.

3. Verificar cada descoberta, conforme descrito em "Verificando descobertas" abaixo. Um problema só vai para a página após esta etapa. Uma descoberta que não sobrevive a ela é descartada antes de ser listada ou, uma vez listada, definida como dismissed com seu motivo.

4. Classificar cada problema.

   • O commit responsável: git log -S'<símbolo>' <base>..<destino>, ou git blame -s <destino> -- <caminho>.
   • Se a base também o possui: git show <base>:<caminho>. Um problema que a base já possui recebe "commitRole": "Pre-existing on" e "commit": "<base>". Não é uma regressão do branch, mas ainda pode bloquear o merge quando o branch o piora, por exemplo, expondo mais dados através dele.
   • arquivo:linha para cada localização, no commit revisado.

5. Escrever o rastreador no scratchpad da sessão, em uma pasta nomeada após o branch (/ substituído por -):

   • index.html: uma cópia de assets/tracker.html, com __TITLE__ substituído pelo nome da página. O nome é o tópico do branch em duas a quatro palavras, seguido por "Revisão", como Revisão de Autorização de Chave de API.
   • issues.json e context.json, conforme descrito em "Os arquivos de dados" abaixo.

6. Validar ambos os arquivos. O validador verifica o esquema, se cada localização existe no commit revisado e se o índice em context.json corresponde aos problemas:

   python3 -I <esta skill>/scripts/validate-issues.py <dir>/issues.json --repo <repositorio>
   

7. Publicar com a ação de publicação da ferramenta Artifact, file_path definido como <dir>/index.html, files definido como {"issues.json": "<dir>/issues.json", "context.json": "<dir>/context.json"}, icon: "checklist" e uma description de uma frase. Escreva a URL retornada em ambos os arquivos ("artifact"), republicar e forneça o link ao usuário.

4. Rodadas posteriores

Execute uma rodada quando o usuário disser que o branch foi atualizado ou pedir uma re-revisão.

1. Confirmar que o branch mudou. Compare o head do PR, ou o ref de destino, com reviewed e veja git reflog -3 --date=iso <destino>. Um push pode chegar atrasado e o branch local do usuário pode ficar atrás do PR. Se nada mudou, diga e pare.
2. Buscar a base (git fetch origin <base>). Se a base mudou, anote e compare o branch com git range-diff <base-antiga>..<tip-antiga> <base-nova>..<tip-nova>.
3. Ver o que mudou:
   • git range-diff <base>..<revisado> <base>..<destino> mostra quais commits foram reescritos, adicionados ou removidos;
   • git diff <revisado> <destino> mostra a mudança líquida;
   • os novos comentários, revisões e verificações do PR (gh pr view <n> --json comments,reviews, gh api repos/<proprietario>/<repo>/pulls/<n>/comments, gh pr checks <n>).
4. Avaliar cada correção. Para cada problema que a mudança aborda, leia a correção e registre em fix o que ela faz e como o código se comporta agora. Defina fixed somente quando a leitura confirmar e diga em verified até que ponto foi verificado.
5. Procurar problemas causados pelas correções. Uma correção frequentemente move o problema em vez de removê-lo. Verifique as entradas que o código antigo tratava por acidente:
   • um valor ausente, vazio ou nulo, por exemplo, uma propriedade que um cliente não define, que costumava produzir um literal inofensivo e agora significa "nenhuma restrição";
   • padrões para os quais um valor recai;
   • caminhos de código que a mudança alcança sem tocá-los, como chamadores, outros endpoints, clientes antigos e o lado de importação de uma exportação;
   • comportamento que a mudança altera para solicitações que não visava. Adicione cada problema como um novo problema e anote a correção que o causou em ambos os problemas. Execute "A revisão de prosa" na mudança líquida.
6. Reavaliar cada problema que não está corrigido em relação ao novo código e olhe novamente para os corrigidos cujo código mudou.
7. Executar testes apenas conforme "Reproduzindo com testes" abaixo permite.
8. Atualizar o rastreador, conforme descrito em "Mantendo o rastreador atual" abaixo:
   • Defina reviewed para a nova ponta.
   • Reescreva commits para os novos hashes. Um commit reescrito obtém seu novo hash; um removido sai do mapa; um novo é adicionado.
   • Altere status, commit, commitRole, note, fix e detail dos problemas que mudaram.
   • Reencontre a linha de cada localização na nova ponta com git grep -n. Não desloque linhas por aritmética.
   • Acrescente novos problemas com o próximo número livre. Nunca renumerar.
9. Validar, depois republicar para a mesma URL.
10. Relatar ao usuário: o que esta rodada corrigiu, o que ainda está aberto e o que é novo, com arquivo:linha e o que foi executado. Termine com o link da página.

Verificando descobertas

Leia o código você mesmo no commit revisado antes de um problema ir para a página.

1. Rastrear o cenário de ponta a ponta. Siga a entrada de onde ela entra até onde o dano acontece e nomeie cada etapa com arquivo:linha. Uma descoberta que precisa de uma etapa que o código não executa é descartada, com essa etapa como motivo.
2. Verificar as pré-condições. Pergunte como o estado desencadeador pode surgir:
   • quem pode criar a entrada, por exemplo, através de qual API, e se um validador ou um padrão a impede;
   • se um padrão configurado, como um tempo de vida ilimitado ou uma função atribuída quando nenhuma é fornecida, torna o cenário inatingível ou o torna o caso normal;
   • se os dados existentes podem contê-lo. Quando apenas dados fora do repositório podem responder, use o auxiliar de verificação de dados do projeto; sem ele, pergunte ao usuário como descobrir. Registre a resposta em verified e no registro.
3. Separar "intencional" de "aceitável". Um runbook, teste ou comentário de código que mostra que um comportamento é deliberado não o torna inofensivo. Verifique a compatibilidade com versões anteriores por conta própria: clientes existentes e versões implantadas, dados existentes e fornecedores ou usuários que nunca usaram o novo recurso. Uma quebra deliberada de um fluxo de trabalho existente é um problema e um bloqueador, a menos que o usuário o aceite.
4. Dizer como foi verificado. Escreva em verified: "Reproduzido por um teste de nível de controlador; a camada de serviço foi simulada", "Através da leitura do código; não executado", "Verificação de dados: nenhum registro correspondente". Relate o que a evidência prova e nomeie o que não prova. Não afirme um veredito causal ou comparativo que os dados não mostram.
5. Descartar com registro. Um descarte define status: "dismissed" e um dismissal com quem decidiu, quando e por quê. Quando Claude descarta, diga isso e que nenhuma pessoa aprovou; a página mostra isso.
6. Reabrir quando contestado. Quando o usuário questionar um descarte ou veredito, verifique novamente a partir do código em vez de defendê-lo. Se estava errado, reabra o problema, remova o descarte e diga claramente em note o que o veredito anterior errou.

Reproduzindo com testes

Execute builds e testes apenas quando o usuário pedir, ou quando as instruções do repositório e do usuário permitirem sem perguntar. Como construir e testar o projeto, com qual toolchain e configurações, vem do auxiliar de build-and-test do projeto e de suas instruções, não desta skill.

1. Nunca usar o checkout do usuário. Coloque o commit em teste em um diretório separado:
   • git worktree add --detach <scratchpad>/<nome>-wt <sha>;
   • se algo bloquear a worktree, exporte o commit em vez disso, omitindo os caminhos que a bloqueiam: git archive <sha> -- . ':(exclude)<caminho-bloqueado>' | tar -x -C <dir>. Por exemplo, um filtro smudge git-crypt falha em caminhos criptografados quando a chave não está disponível. O script de pré-verificação nomeia os caminhos que possuem filtros de checkout.
2. Construir e executar da maneira que o projeto diz. Uma falha de ferramenta, como uma toolchain que o projeto não suporta, não é um resultado de teste: corrija o ambiente conforme o auxiliar ou as instruções do projeto dizem e execute novamente. Sem um auxiliar, pergunte ao usuário em vez de adivinhar e anote o que foi aprendido para as notas do projeto.
3. Escrever o teste para que ele afirme o comportamento correto. Uma falha então reproduz o problema, e o mesmo teste se torna o teste de regressão para a correção. Dirija as classes reais ao longo do caminho e simule apenas o que o cenário precisa. Faça cada simulação espelhar o que o código real faz e nomeie cada camada simulada ou não exercitada em verified, como HTTP, a cadeia de segurança ou o banco de dados.
4. Executar o conjunto mais restrito: o novo teste, mais os testes que cobrem o código alterado.
5. Manter o código-fonte do teste no rastreador. O scratchpad pode ser limpo entre sessões. Publique o teste como tests/<Nome>.<ext> em files, com contentType: "text/plain", e nomeie-o no problema.
6. Limpar. Remova a worktree ou a exportação e qualquer saída de build que uma execução deixou no checkout do usuário, como classes de teste compiladas, que um build posterior pegaria. Em seguida, verifique se git status e git worktree list mostram o checkout do usuário inalterado.

Skills auxiliares

O fluxo de revisão é o mesmo para cada projeto; o que o projeto sabe vive em suas próprias skills. Use-as quando existirem; esta skill nunca codifica ferramentas de projeto diretamente.

Encontre-as na lista de skills disponíveis desta sessão, por suas descrições. Não adivinhe nomes. Carregue uma com a ferramenta Skill quando a etapa precisar dela.

Auxiliar	Usado para	Sem ela
lista de verificação de revisão	as áreas de risco do projeto: modelo de segurança, promessas de compatibilidade, contratos de API, migrações	a revisão depende de conhecimento geral; diga quais áreas pode perder
build e teste	construir e testar um commit isoladamente: comandos, toolchain, configurações, bloqueadores conhecidos	os testes são executados apenas depois de perguntar ao usuário como; as descobertas permanecem "a partir da leitura do código"
verificações de dados	responder a perguntas a partir de dados fora do repositório, com segurança	o usuário é perguntado como descobrir
regras de prosa	comentários, docstrings, changelogs, mensagens de commit e texto de PR, como uma geração de...