steve-swanson/review-work

Review Work

Esta skill revisa código, mostra os resultados em uma página web local e corrige apenas o que o usuário aprovar. Todas as correções aprovadas chegam em um único branch e são enviadas em um único pull request (PR).

O agente principal (o chat que executa esta skill) está no comando. Ele define o escopo, escolhe o modelo para cada agente auxiliar, salva todos os registros e verifica todos os resultados. Os agentes auxiliares fazem o trabalho que lhes é atribuído e reportam de volta.

Esta skill funciona ao lado de plan-work e execute-work. Ela não os chama nem os modifica.

Palavras usadas aqui

• Branch revisado: o branch sob revisão. O PR retorna para este branch. Não é sempre develop.
• Commit revisado: o SHA exato do commit que foi revisado. Cada descoberta aponta para ele.
• Descoberta: um problema ou pergunta da revisão, com um ID como R001.
• Página: a página web local onde o usuário escolhe Corrigir, Não corrigir ou Esclarecer para cada descoberta.
• Lote: as escolhas enviadas por um clique em Enviar.
• Worktree: uma checkout extra do mesmo repositório em sua própria pasta.
• Branch coordenador: o único branch (com seu próprio worktree) que coleta todas as correções. Ele se torna o PR. Nomeie-o no estilo Conventional Branch, <tipo>/<descrição-curta>, em minúsculas com hífens. As correções de revisão geralmente são fix/, como fix/session-recovery; use refactor/, perf/, docs/, test/ ou chore/ quando isso se adequar melhor a todas as correções. Se o usuário ou repositório nomear uma convenção diferente (por exemplo, em AGENTS.md), siga-a. Nunca coloque integration no nome.
• Branch de tarefa: um branch e worktree de curta duração onde um auxiliar faz uma correção.
• Merge fast-forward: um merge que apenas move o branch para frente e não adiciona commit de merge (git merge --ff-only).
• De propriedade da execução: criado por esta execução de revisão. A limpeza toca apenas branches e worktrees de propriedade da execução. Um nome correspondente não é prova de propriedade.

O que o usuário permitiu

• Iniciar esta skill permite registros de revisão e o serviço de página local.
• Escolher mostrar a página em outra máquina vinculada permite um thread de hospedagem de página nessa máquina, em um projeto T3 chamado Review-work pages (criado se ausente). Ele executa apenas a CLI do review-work. Nunca toca no código lá. Quando a revisão estiver concluída, encerrar esse thread e excluir o projeto Review-work pages (o que exclui seus chats) é permitido, conforme em remote-page.md. Nunca exclua nenhum outro projeto. Este chat de revisão nunca está nesse projeto: ele permanece e recebe o relatório final.
• Enviar Corrigir (na página ou um claro "corrija isso" no chat) permite worktrees de tarefa, commits, merges no branch coordenador, limpeza segura, push e um PR pronto para revisão. Também permite observar esse PR até seu merge e, em seguida, remover o worktree e o branch local inalterados e mesclados desta execução na máquina de revisão.
• Se o usuário disser "apenas local" ou "sem PR", siga isso.
• Nunca faça merge do PR, ative o auto-merge ou implante.

Etapa 1: Definir o que revisar

1. Leia as instruções, requisitos, status, branches e worktrees do repositório. Deixe edições não commitadas e outras execuções em paz.
2. Registre o caminho do repositório, pasta Git compartilhada, branch, base, SHA do commit revisado, host (nome da máquina) e o ID do chat.
3. Revise apenas o código commitado, com git show, diffs ou uma checkout gerenciada limpa. Arquivos não commitados não fazem parte da revisão.
4. Escolha o escopo:
   • Branch de recurso: revise seu diff em relação à sua base. Obtenha a base do usuário, regras do projeto ou metadados do PR. Se ainda não estiver claro, pergunte.
   • develop: revise todo o código atual. Não invente uma data de início ou commit inicial.
5. Pergunte "Inline ou fan-out de subagentes?" a menos que o usuário já tenha dito.
   • Inline: o agente principal revisa por conta própria. As correções ainda usam auxiliares.
   • Fan-out: os auxiliares revisam em paralelo. Peça o máximo de auxiliares de uma vez e sugira um número com base nas áreas independentes úteis. Ofereça Auto: quantos auxiliares úteis a capacidade permitir. Se a capacidade for desconhecida, diga que o limite é 4. Coloque o restante na fila.
6. Antes de criar qualquer worktree, salve um snapshot dos worktrees atuais, branches locais e anexos gerenciados. Mantenha uma lista de cada worktree que esta execução cria: revisores, corrigidores, auxiliares, tentativas e seus filhos, também os inalterados ou abandonados. Consulte cleanup.md.

Etapa 2: Iniciar os registros de revisão

• Use Node 24+ e scripts/review.mjs desta skill. Os comandos estão em runtime.md.
• Execute init uma vez, com um arquivo de entrada JSON mantido fora do projeto. Salve o caminho da pasta de revisão retornado e reutilize-o. Ao retomar, nunca crie uma nova execução.
• Os registros residem em <home>/.agents/state/review-work/. O runtime cria seu .gitignore antes de qualquer outro arquivo lá, para que o Git nunca os colete.
• A identidade de um repositório é sua URL remota limpa mais sua pasta Git compartilhada real. Worktrees vinculados de um clone compartilham uma identidade; clones separados não. Cada execução também tem seu próprio ID, para que revisões em execução ao mesmo tempo não se misturem.
• Apenas o agente principal e seu serviço de página escrevem os registros. Nunca copie o banco de dados, serviço ou estado para um worktree ou .worktreeinclude. Os auxiliares retornam resultados, e o agente principal os salva. Os auxiliares colocam arquivos grandes em sua própria pasta temporária; o agente principal os importa.

Etapa 3: Escolher modelos, depois revisar

Leia routing.md primeiro.

• O agente principal escolhe o modelo e esforço exatos para cada tarefa de revisão e correção. Ele verifica se o host os oferece, então registra a escolha antes de iniciar a tarefa. Os auxiliares nunca chamam Jev ou escolhem rotas (modelo, esforço ou opções). Eles nunca iniciam seus próprios auxiliares, a menos que o principal lhes dê uma atribuição exata e fixa para fazê-lo.
• Permaneça na família de modelos do chat: modelos GPT em um chat GPT; Claude Opus, Sonnet ou Haiku em um chat Claude.
• Sempre a versão mais recente. Os modelos são escolhidos pelo nome do nível (Astra, Sol, Terra, Opus, Sonnet, Haiku). Para cada nível, o runtime mantém apenas a versão mais recente na lista de modelos do host e rejeita as mais antigas. Nunca escolha uma versão da memória. Confie na lista de modelos do host em vez de suposições. Nunca invente um ID de modelo ou mude de provedor silenciosamente. Se a família for desconhecida ou um modelo necessário estiver ausente, pergunte.
• Jev pode escolher o modelo primeiro, depois um esforço que esse modelo suporta. Ele precisa de uma chave. Encontre-a com a descoberta de credenciais do runtime, nunca abrindo o arquivo você mesmo. A descoberta verifica <home>/.config/jev/credentials.env primeiro (TYPESAFE_API_KEY é o nome recomendado). Se nenhuma chave inicial utilizável existir, verifique a ordem real de carregamento de env do projeto e seus adaptadores configurados, depois passe esses caminhos de arquivo env. Nunca imprima, salve ou use source em arquivos de chave ou valores de chave. A ordem completa de consulta está em routing.md.
• Um adaptador Jev MCP configurado pode fazer as mesmas duas escolhas. Leia seu esquema de ferramenta real primeiro; não presuma que uma ferramenta jev_route existe. Sem um adaptador, use o transporte direto integrado do runtime.
• Limites de esforço, para todos os modelos: revisões e planejamento vão até extra-alto, nunca máximo ou ultra. Correções vão até Alto. O runtime rejeita qualquer rota acima do limite, de Jev ou do principal.
• Se Jev estiver ausente ou der uma resposta inutilizável, o agente principal decide com as mesmas regras. Não há tabela de fallback fixa.
  • Trabalho de listagem somente leitura: Baixo é suficiente.
  • Algoritmos ou raciocínio difícil: Alto ou extra-alto.
  • Não tem certeza: Alto.
  • Revisão e planejamento de segurança (login, permissões, segredos, criptografia, isolamento de inquilino, limites de confiança): a versão mais recente do GPT Astra ou a versão mais recente do Claude Opus, em extra-alto. Se esse modelo não tiver extra-alto, use o mesmo modelo em seu nível mais alto abaixo do limite (pelo menos Alto). Não mude para uma versão mais antiga. Se um auxiliar encontrar um novo escopo de segurança, ele para nessa parte e reporta ao principal. A implementação planejada usa as rotas de correção abaixo, incluindo correções de segurança.
  • Revisão inline quando parte dela precisar de uma rota superior: não peça ao usuário para mudar o modelo ou esforço deste chat. Este chat não pode confirmar ou definir seu próprio esforço. Dê essa parte (por exemplo, as verificações de segurança) a um auxiliar de revisão e defina o modelo e esforço exatos do auxiliar ao iniciá-lo (em Claude Code, os parâmetros model e effort da ferramenta Agent; em T3, as opções delegate_task). Registre a rota primeiro. O auxiliar retorna as descobertas; o agente principal as salva. Pergunte ao usuário apenas se o host não puder iniciar um auxiliar no modelo e esforço necessários: então explique a lacuna e ofereça manter o modelo deste chat. Registre essa escolha uma vez para esta revisão e não pergunte novamente. Isso nunca reduz a regra para auxiliares de fan-out.
• Divida a revisão por comportamento e por arquivos. Siga fluxos entre arquivos. Caça por maneiras como o código quebra: resultados errados, regras quebradas, dados perdidos, verificações ausentes e quebras de compatibilidade. Verifique cada preocupação contra os requisitos e o código que realmente é executado. Mescle duplicatas.
• Registre a cobertura: o que você verificou, pulou e não conseguiu terminar, com caminhos, SHA, motivo e prova. "Nenhuma descoberta" não significa que todos os arquivos foram verificados. Não considere a revisão completa enquanto a cobertura importante não for contabilizada (não registrada como verificada, pulada ou não terminada).

Etapa 4: Escrever descobertas que as pessoas possam entender

O usuário decide apenas pelo texto da descoberta, então o texto deve ser curto, exato e simples. Leia writing-findings.md. Dê seu caminho a cada auxiliar de revisão e diga para segui-lo.

Use rótulos de Comentários Convencionais como issue, question, suggestion e nitpick. Marque cada descoberta como blocking ou non-blocking. Cada descoberta tem quatro partes:

• Título: o que dá errado, como uma frase simples de 80 caracteres ou menos. "Repetir um pagamento pode criar duas faturas", não "Caminho de criação de fatura não idempotente".
• Por que importa (discussion): quem ou o que é afetado, quando e com que frequência.
• Prova (evidence, mais um excerpt de código opcional): path:line, o caminho do código ou etapas, e como você sabe.
• Ideia de correção (suggestion): começa com Correção pequena, Correção média ou Correção grande, depois diz o que mudar.

Se você não tiver certeza, escreva uma question. Nunca apresente um palpite como um issue confirmado. Dê a cada descoberta um ID estável, o caminho e linha, e o SHA revisado.

Antes de carregar as descobertas, execute a verificação de clareza em writing-findings.md em cada uma. Reescreva qualquer uma que falhe e mantenha todos os fatos.

Etapa 5: Mostrar a página e coletar decisões

1. Carregue as descobertas e a cobertura, depois inicie a página. Uma página serve toda a revisão, incluindo rodadas posteriores.

2. Para cada descoberta, o usuário escolhe Corrigir, Não corrigir ou Esclarecer, e pode adicionar uma nota a qualquer uma delas. As escolhas são salvas como rascunhos. Trocar a escolha mantém a nota.

3. Apenas Enviar envia um lote. Lotes parciais são aceitáveis; descobertas não decididas permanecem abertas. Escolhas enviadas são bloqueadas na página. As alterações acontecem no chat.

4. Verifique a plataforma primeiro. Este chat executa em T3 Code quando seu shell tem T3CODE_THREAD_ID ou T3CODE_CLI_PATH definidos, ou quando ferramentas T3 como t3_environment_links estão disponíveis. Se não:

   • Mostre a página nesta máquina, com deliveryMode: "terminal".
   • Pule a escolha de hospedagem de página abaixo e não ofereça outra máquina. Não leia remote-page.md.
   • Use a redação de terminal simples no item 5.

   No T3, escolha onde mostrar a página a partir da origem do chat. Mantenha isso separado da escolha inline/fan-out.

   • Respeite uma escolha explícita de hospedagem de página já feita neste chat. Ao retomar, reutilize-a; pergunte novamente apenas se o usuário a mudar ou se esse host estiver indisponível.
   • Se o chat foi iniciado localmente na máquina de revisão, mostre a página nessa máquina sem perguntar. Estabeleça isso a partir da declaração do usuário ou de metadados de origem do cliente fornecidos pelo host que identificam o dispositivo iniciador. O nome do host do agente, diretório de trabalho, ambiente de execução ou creationSource (web, mobile ou mcp) sozinho não prova onde o usuário iniciou o chat.
   • Se o chat foi iniciado remotamente, ou sua origem for incerta, pergunte uma vez onde mostrar a página. Pergunte diretamente pelo host da página, sem uma pergunta separada sobre se o usuário está local. Chame t3_environment_links e ofereça esta máquina mais cada máquina vinculada alcançável com acesso total, usando seus rótulos reais. Não omita nenhuma máquina devido ao seu sistema operacional. Explique um bloqueador de capacidade/acesso conhecido em vez de ocultar silenciosamente um host. Se a ferramenta de pergunta não couber em todas as escolhas, liste todos os hosts elegíveis na pergunta e aceite um nome de host.
   • Recomende a máquina do usuário quando ela for conhecida e elegível. Explique a limitação de bloqueio de tela apenas quando ela afetar a escolha: o navegador transmitido do T3 para quando a tela da máquina de revisão está bloqueada. Salve o host selecionado e a evidência de origem (ou unknown) nas notas de revisão.
   • Em outra máquina: siga remote-page.md. A página abre no próprio navegador do usuário lá, e Enviar envia as escolhas de volta para este chat. Precisa de links T3 de acesso total. Funciona enquanto esta máquina estiver bloqueada.

5. Sempre forneça o host e link da página.

   • No T3, nesta máquina: o navegador T3 pode abrir a página. Diga "Enviar retoma esta conversa automaticamente." A página usa o comando local t3 thread send. Nenhum webhook público ou túnel é necessário.
   • No T3, em outra máquina: diga qual máquina mostra a página e "Enviar envia suas escolhas de volta para este chat."
   • Em um terminal simples, diga:
     1. Abra a página de revisão.
     2. Escolha uma opção para cada descoberta, adicione notas se quiser e clique em Enviar.
     3. Volte a este chat e aguarde o próximo lote. Os resultados aparecerão aqui.
     4. Repita até que todas as descobertas estejam finalizadas ou você queira parar. Fechar a página é seguro; as descobertas não finalizadas permanecem sem decisão.
     5. Quando terminar, diga "concluído" para obter o relatório final.

6. Colete todas as decisões enviadas. Após cada lote, pergunte se o usuário vai enviar mais ou se a página está concluída. Não presuma que a página está concluída quando um lote está vazio; se estiver faltando, pergunte se o usuário esqueceu de enviar ou quer interromper. O usuário pode reabrir a qualquer momento.