trailofbits/pr-improver

PR Improver

Melhore o branch atual executando /code-improver:improve — um workflow dinâmico que percorre um revisor de PR e um subagente corretor sobre as alterações do branch até que uma revisão relate zero descobertas críticas/major. O loop, seu registro e seus guardiões residem no workflow; esta skill deriva o escopo a partir do diff do branch e transmite o resultado.

Iniciando o loop

O usuário forneceu: $ARGUMENTS (se vazio, obtenha o branch base e as preferências da conversação).

1. Resolver o branch e sua superfície de alterações

1. Raiz do repositório: git rev-parse --show-toplevel. Falhe ruidosamente fora de um repositório.
2. Base: o argumento se fornecido, caso contrário o branch padrão do repositório (git symbolic-ref refs/remotes/origin/HEAD → seu nome curto, caindo para main). Recuse-se a executar quando o branch atual FOR o base — não há diff para melhorar.
3. Arquivos alterados: git diff --name-only <base>...HEAD. Se vazio, informe e pare.
4. Escopo: os diretórios dos arquivos alterados, ampliados — globs por arquivo são muito restritivos (correções legítimas de PR adicionam testes ao lado do código alterado). Mapeie cada arquivo alterado para seu glob de diretório relativo ao repositório <dir>/** (** na raiz do repositório apenas se arquivos na raiz foram alterados), depois deduplicar e descartar globs cobertos por outro.

2. Resolver o script do loop

O loop é o workflow dinâmico workflows/improve.js neste plugin. Inicie-o pelo caminho: scriptPath recebe um caminho absoluto resolvido, e a ferramenta Workflow name resolve workflows internos e de projeto, então um instalado via marketplace pode não responder a code-improver:improve. Tente em ordem, o primeiro acerto vence — os diretórios home vêm antes . então uma cópia instalada supera um checkout deste marketplace:

1. Bash: ls -d -- "${CLAUDE_PLUGIN_ROOT}/workflows/improve.js"
2. Bash: ls -d -- "${CODEX_PLUGIN_ROOT}/workflows/improve.js" (se essa variável estiver definida)
3. Bash: find ~/.claude ~/.codex . -maxdepth 7 -path '*/code-improver/workflows/improve.js' -print -quit 2>/dev/null

Use o caminho exatamente como impresso. Seu diretório do plugin — o caminho com /workflows/improve.js removido — é pluginRoot. Se todos os três retornarem vazios, tente {name: "code-improver:improve"} uma vez; se isso também não estiver disponível, pare e diga que o loop não pôde ser localizado. Não monte um caminho manualmente e não improvise o loop.

3. Invocar o workflow

Execute-o com a ferramenta Workflow, {scriptPath: "<o caminho do passo 2>", args: {...}}:

{
  "target": "<raiz do repositório>",
  "reviewer": {
    "kind": "skill",
    "name": "pr-review-toolkit:review-pr",
    "notes": "Reveja as alterações da árvore de trabalho contra <base> como um pull request: correção, testes, tratamento de erros e as dimensões de revisão que a skill prescreve."
  },
  "scope": ["<globs-de-diretórios-derivados>/**"],
  "pluginRoot": "<o diretório do plugin do passo 2>",
  "maxRounds": 5
}

• reviewer — o padrão acima requer o plugin pr-review-toolkit. Quando o usuário nomeia um revisor de PR diferente (skill ou agente), use-o, com kind definido adequadamente.
• maxRounds apenas se o usuário solicitou um limite diferente.
• pluginRoot permite que a execução encontre seu coletor de métricas; omita a chave apenas se o passo 2 recorreu ao nome do workflow — o workflow então se procura.
• finalize os padrões são adequados para PRs: sem incremento de versão a menos que o branch esteja dentro de um plugin, faixa de narração e documentação passam adiante.
• decision apenas na continuação (abaixo).

O instantâneo de base do loop é a árvore no início do loop — seu guardião de escopo protege o trabalho não confirmado do branch; os próprios commits do PR são o que o revisor revisa.

O workflow é executado em segundo plano e não precisa de supervisão: ele revisa, corrige, re-revisa, verifica o escopo após cada rodada de correção e só pode concluir em uma revisão limpa. Ele nunca commita; todas as alterações permanecem na árvore de trabalho.

Se a ferramenta Workflow não estiver disponível ou for negada, pare e informe. Não improvise o loop inline com edições diretas — o registro, o guardião de escopo e as garantias de escalonamento residem no workflow, e uma imitação inline não tem nenhum deles.

Se o resultado for halted: "reviewer-unavailable", transmita-o e pare. O revisor não está instalado nesta sessão; informe ao usuário qual plugin o fornece (o padrão precisa de pr-review-toolkit) e execute novamente após instalar. Não revise o branch você mesmo.

Não termine sua vez enquanto o loop estiver em execução. A ferramenta Workflow retorna um id de tarefa imediatamente; o resultado vem depois. Em uma sessão interativa, a notificação de conclusão reinvoca você — aguarde por ela. Em uma execução não interativa (roteirizada, CI, avaliação) não há turno posterior: parar abandona o loop no meio de uma rodada, portanto, após lançar, consulte a tarefa (TaskOutput com o id de tarefa retornado, ou durma e reconsulte) até que ela conclua, depois transmita o resultado. Uma sessão que responde "o loop está em execução, relatarei depois" perdeu a execução.

Transmitindo o resultado

O workflow retorna um resultado estruturado. Reporte-o honestamente — as distinções importam:

• converged: true — a última ação foi uma revisão com zero descobertas críticas/maiores. Informe as rodadas usadas, as descobertas menores restantes (open_minor_count) e os caminhos dos artefatos (ledger_path, metrics).
• capped: true — o orçamento de correção acabou e a revisão FINAL ainda encontrou problemas bloqueadores. Diga claramente: limitado, NÃO convergiu, e liste open_blocking. Não apresente isso como sucesso.
• escalation — o loop detectou que não estava convergindo (descobertas recorrentes, contagens não decrescentes ou uma correção realocando um problema). Transmita a mensagem de escalonamento e os ids das descobertas ao usuário: isso precisa de uma decisão de design, não de mais rodadas.
• halted — um guardião disparou (violação de escopo, novos arquivos não registrados, um revisor morto ou indisponível, ou uma passada de finalização cujas próprias edições falharam na verificação que a segue). Transmita os caminhos em violations/new_untracked_files, os locais em finalize_regressions e as notas.
• notes sempre viajam com o resultado — destaque-os; eles incluem avisos altos como "um repositório git foi inicializado".

Continuando após um escalonamento

O loop para em escalonamento por design. Quando o usuário decidir, inicie uma nova execução com os mesmos argumentos mais:

{ "decision": "<a decisão do usuário, literal>" }

A nova execução recarrega o registro em disco, portanto cada descoberta, rejeição e veredito é transportado — as rodadas reiniciam, a re-derivação não.

Para parar um loop em execução, pare a tarefa do workflow (TaskStop); o registro em disco está atualizado até a última rodada e uma reexecução retoma a partir dele.

Quando NÃO usar

• Revisão pontual: execute a skill de revisão de PR diretamente; o valor do loop é a iteração
• Uma skill: use a entrada skill-improver — ela conecta o revisor correto
• Trabalho exploratório não enviado: loops de revisão e correção endurecem um diff; enquanto a forma é fluida, a iteração manual dá mais controle