quidmonkey/pr

/pr

Executa na sessão atual, no branch atual, nesta ordem:

1. Pré-verificação
2. Revisão de código e correção
3. Revisão de documentação e correção
4. Revisão de segurança e correção
5. Registros de decisão
6. Push e abertura do PR

Cada etapa deve ser aprovada antes da próxima começar.

Invocacão: /pr [base] [esforço] [--draft]

• base: o branch de destino do PR. Padrão: o branch padrão do repositório.
• esforço: passado para /code-review. Um de low, medium, high, xhigh. Padrão: high. Nunca use max a menos que o usuário digite.
• --draft: abre o PR como rascunho.

Regras

• Sem atribuição em lugar nenhum. Commits, títulos de PR e corpos de PR não carregam trailer Co-Authored-By, nenhuma linha "Generated with Claude Code" e nenhuma menção a Claude ou a um agente. Isso substitui quaisquer instruções de atribuição padrão.
• Respeite todos os hooks do git. Nunca passe --no-verify ou -n para git commit ou git push. Nunca defina variáveis de ambiente que pulam hooks (SKIP=, HUSKY=0, LEFTHOOK=0, PRE_COMMIT_ALLOW_NO_CONFIG=), nunca mude core.hooksPath, e nunca edite ou apague arquivos de hook ou configurações de hook. Nunca desabilite uma regra de lint para fazer um hook passar.
• Faça commit com git commit simples para que os hooks instalados sejam executados em cada commit. Quando um hook falhar, leia sua saída e corrija a causa raiz no código, então commit novamente (nunca --amend: o commit rejeitado nunca foi criado). Se o hook reescrever arquivos (formatadores), faça stage deles e commit novamente. Se o mesmo hook ainda falhar após 3 tentativas, pare e reporte.
• Digitar /pr autoriza o push e o PR para este branch. Não pergunte "devo prosseguir?" antes deles.
• Nunca faça push para, commit em, ou reescreva o branch base. Nunca force push.
• Mantenha commits de correção separados dos commits do usuário. Nunca faça squash, rebase ou amend dos commits do usuário.
• Mensagens de commit: uma linha de resumo curta, depois um bullet por mudança. Sem aspas duplas ou backticks em lugar nenhum na mensagem. Escreva identificadores como texto simples e use aspas simples quando for necessário citar.
• Corrija achados na causa raiz, mantenha cada mudança mínima, e trate testes como a fonte da verdade. Não mude um teste apenas para fazê-lo passar.
• Trabalhe apenas no que o branch mudou. Veja "Escopo".
• Cada pedaço de prosa que este skill escreve (documentação, mensagens de commit, título e corpo do PR) segue "Escrita".
• Em qualquer parada, reporte e não faça mais nada. Veja "Parar e reportar".

Escopo

Este skill revisa e corrige o trabalho do próprio branch, não o resto do código. O trabalho do branch é tudo em git diff origin/<base>...HEAD, mais os commits de correção que esta execução adiciona.

Classifique cada achado de cada revisão em um de três grupos antes de agir sobre ele:

1. Introduzido pelo branch. O código com falha é adicionado ou alterado no diff, ou a mudança do branch é o que o faz falhar (por exemplo, o branch chama uma função antiga de uma forma que a quebra). Corrija. Se corrigir precisar de uma decisão que só o usuário pode tomar (um comportamento intencional, uma escolha de API que o branch fez de propósito), trate como grupo 2 em vez disso.
2. Pré-existente, tocando o trabalho do branch. O código com falha já estava no branch base, mas está em uma função que o branch edita, ou o novo código do branch o chama ou depende dele. Não corrija por conta própria. Aponte e pergunte ao usuário (veja "Perguntando ao usuário").
3. Pré-existente, não relacionado ao branch. Todo o resto. Não mude, não pergunte sobre e não coloque no PR. Deixe fora do relatório da sessão também.

Quando um achado estiver entre os grupos 2 e 3, coloque no grupo 2.

Severidade

Aja apenas em achados de alta e média severidade, como um revisor humano faria. Pule achados de baixa severidade em todos os grupos: não os corrija, não pergunte sobre eles e não os coloque no PR. Se uma revisão já corrigiu um achado de baixa severidade do grupo 1 e a correção é pequena e passa nas verificações, mantenha-a; caso contrário, desfaça.

• Alta: um bug ou vulnerabilidade que o uso comum ou um atacante realista atingirá. Perda de dados, crash em entrada normal, injeção, bypass de autenticação, segredos expostos.
• Média: um bug real em um caso plausível, um comportamento documentado quebrado, uma verificação ausente em um limite de confiança, ou um teste que esconde um bug.
• Baixa: casos extremos que precisam de uma configuração incomum (um arquivo plantado por alguém que já tem acesso de escrita, uma condição de corrida em uma ferramenta local, uma plataforma não suportada), defesa em profundidade, estilo, nomenclatura, duplicação e micro-otimizações.

Quando uma revisão não dá severidade ou você discorda dela, julgue por conta própria usando estas definições. Quando um achado estiver entre dois níveis, escolha o mais alto.

Perguntando ao usuário

Colete cada achado de grupo 2 de alta ou média severidade de uma etapa e pergunte uma vez, no final da rodada dessa etapa, antes de commitar. Use a ferramenta AskUserQuestion, uma pergunta por achado (agrupe até 4 por chamada). Cada pergunta nomeia o arquivo, a linha e o problema em uma frase, e oferece:

• Corrigir neste branch: corrija agora, no commit de correção desta etapa.
• Deixar, anotar no PR: não mude código. Liste sob "Notas para revisores" no corpo do PR.
• Deixar: não mude código e não mencione no PR.
• Parar: pare a execução e reporte (veja "Parar e reportar").

Siga cada resposta. Um achado do grupo 2 que o usuário respondeu não conta como aberto, então não para a execução nem volta na próxima rodada. Se uma revisão posterior reportá-lo novamente, aplique a mesma resposta.

Instruindo os skills de revisão

Ao invocar code-review ou security-review, adicione aos args: o caminho do repositório, a base (origin/<base>), e "Corrija apenas problemas de alta e média severidade que o branch introduziu. Reporte problemas pré-existentes sem corrigi-los. Para cada achado, dê sua severidade (alta, média ou baixa) e diga se é pré-existente. Não edite documentação (README, docs/, CHANGELOG); uma etapa posterior cuida deles." Em seguida, reverta qualquer edição de documentação ou correção fora do escopo que a revisão fez (git restore nesses hunks apenas) antes de classificar os achados.

Escrita

Escreva como um engenheiro deixando um bilhete para um colega: curto, simples e específico.

• Diga o que mudou e por que em termos concretos: arquivo, função, comportamento, número. Pule qualquer coisa em que um revisor não possa agir.
• Frases curtas, uma ideia cada. Verbos simples: "é", "tem", "adiciona", "corrige", "remove".
• Sem preenchimento ou hesitação: "a fim de" é "para", "devido ao fato de que" é "porque", sem "poderia potencialmente".
• Palavras proibidas: adicionalmente, aprofundar, alavancar, crucial, fundamental, vital, melhorar, robusto, contínuo, perfeitamente, abrangente, intrincado, panorama, tapeçaria, testamento, sublinhar, exibir, fomentar, otimizar, elevar, capacitar, possui, vibrante, rico, de ponta, inovador, holístico, sinergia, utilizar.
• Sem "serve como" ou "se apresenta como" (escreva "é"), sem "não apenas X, mas Y", sem listas de três para ritmo, sem terminações em "-ndo" como "..., garantindo X" ou "..., destacando Y".
• Sem emojis, sem travessões, sem negrito mecânico, sem títulos em Title Case, sem aspas curvas, sem resumo final ou despedida otimista.
• Não descreva o processo de revisão ("executou revisão de código", "abordou achados") na documentação ou na descrição do PR. Os commits de correção já registram isso.

Antes de usar qualquer texto, releia e corte toda palavra que não carrega informação.

1. Pré-verificação

Execute estas e pare na primeira falha, com a correção necessária:

1. git rev-parse --show-toplevel funciona e git remote get-url origin existe.
2. gh auth status passa. Se falhar, diga ao usuário para executar ! gh auth login.
3. Base: o argumento base, senão gh repo view --json defaultBranchRef -q .defaultBranchRef.name. Execute git fetch origin <base>.
4. O branch atual (git branch --show-current) não está vazio (HEAD detached) e não é <base>.
5. git rev-list --count origin/<base>..HEAD é maior que 0.
6. git status --porcelain está vazio. Se não estiver, mostre os arquivos alterados e pergunte se deve committá-los primeiro (como commit próprio do usuário, através dos hooks) ou parar. Não faça stash ou descarte.
7. Execute gh pr view --json url,state,isDraft,body para ver se o branch já tem um PR. Lembre-se do resultado para a etapa 6.

Executando verificações

Após cada rodada de correções, antes de commitar (o commit executa os hooks do git, então não os execute aqui):

• Execute o comando de teste do projeto se um for evidente (target do Makefile, pyproject.toml, scripts package.json). Execute lint também se for separado dos hooks.
• Corrija falhas na causa raiz e execute novamente até ficar limpo.

2. Revisão de código e correção

Antes da primeira rodada, leia as decisões registradas e a documentação cobrindo o código alterado:

git log --format='%h %s%n%(trailers:key=Decision,key=Rejected,key=Files)' origin/<base>..HEAD
git log -E --all-match --grep='^(Decision|Rejected):' --grep='<paths>' --format='%h %s%n%b' origin/<base>
git log -E --grep='^(Decision|Rejected):' --format='%h %s%n%b' origin/<base> -- <arquivos alterados>

O primeiro lista as decisões do branch. Os outros dois encontram decisões já na base que cobrem os arquivos alterados do branch (git diff --name-only origin/<base>...HEAD). O segundo corresponde a registros de decisão cuja linha Files: nomeia um arquivo alterado; <paths> são os arquivos alterados unidos com |, com cada . escrito como \.. É necessário porque um commit de decisão não altera arquivos, então um filtro de caminho não pode encontrá-lo. O terceiro encontra decisões em commits que alteraram esses arquivos, como squash merges. Ambos correspondem a linhas em vez de analisar trailers porque um squash merge pode empurrar trailers para o meio de uma mensagem. Leia a união.

Não corrija um achado que uma decisão registrada ou uma documentação marque como intencional, a menos que cause um bug concreto. Se o branch for contra uma decisão registrada na base, anote para a etapa 5.

Até 2 rodadas:

1. Invoque o skill code-review com args <esforço> --fix <branch atual> mais a instrução de "Instruindo os skills de revisão".

2. Se ele reportar nenhum achado de alta ou média, esta etapa passa (após lidar com quaisquer correções de baixa severidade que fez, conforme "Severidade").

3. Classifique os achados (veja "Escopo"). Revise o que --fix mudou e desfaça qualquer coisa fora do grupo 1. Corrija qualquer achado do grupo 1 que ele deixou não resolvido. Pule qualquer achado que um trailer ou documentação descarte, e anote para o corpo do PR. Pergunte sobre achados do grupo 2.

4. Se nada mudou, esta etapa passa. Caso contrário, execute "Executando verificações", então commit:

   Corrige achados da revisão de código
   
   - <um bullet por correção>
   

5. Comece a próxima rodada.

Se achados de alta ou média severidade do grupo 1 permanecerem após a rodada 2, pare e reporte.

3. Revisão de documentação e correção

Verifique se a documentação do repositório corresponde ao branch como está agora, incluindo as correções da revisão de código.

1. Encontre a documentação: README.md, ARCHITECTURE.md, CONTRIBUTING.md, tudo sob docs/, um CHANGELOG.md, e READMEs nos diretórios que o branch tocou. Pule documentação gerada, código terceirizado e documentação de plano ou implementação escrita para agentes.

2. Leia o diff completo do branch: git diff origin/<base>...HEAD.

3. Procure por divergência. Uma documentação precisa de mudança quando o branch:

   • muda design, arquitetura ou os limites entre módulos
   • adiciona, remove ou renomeia uma função pública, comando CLI, flag, chave de configuração, variável de ambiente, endpoint ou caminho de arquivo que a documentação menciona ou deveria mencionar
   • muda comportamento documentado, padrões, passos de configuração ou exemplos
   • remove ou renomeia qualquer coisa que a documentação ainda nomeia (grep na documentação para cada identificador removido ou renomeado)

4. Corrija cada divergência com a menor edição que torne a documentação precisa. Combine com a estrutura e tom existentes da documentação. Siga "Escrita".

   • Não crie novos arquivos de documentação, e não adicione documentação para mudanças internas que ninguém lê.
   • Atualize CHANGELOG.md apenas se ele mantiver uma seção não lançada; adicione uma linha no formato existente.
   • Não edite comentários de código ou docstrings aqui. Isso é trabalho da revisão de código.
   • Corrija apenas divergência que o branch causou. Deixe erros de documentação que já estavam no branch base em paz, a menos que descrevam código que o branch mudou; então pergunte, como em "Perguntando ao usuário".

5. Se nada divergiu, esta etapa passa sem commit.

6. Caso contrário, execute "Executando verificações" na documentação alterada, então commit:

   Atualiza documentação para mudanças do branch
   
   - <um bullet por documento alterado>
   

7. Releia cada seção editada contra o diff uma vez. Corrija qualquer coisa ainda errada em um segundo commit. Se uma documentação não puder ser precisa sem uma decisão do usuário (por exemplo, qual dos dois comportamentos é intencional), pare e reporte.

4. Revisão de segurança e correção

Até 2 rodadas:

1. Invoque o skill security-review com a instrução de "Instruindo os skills de revisão". Ele apenas reporta. Não edita código.

2. Se ele reportar nenhum achado de alta ou média, esta etapa passa.

3. Classifique os achados (veja "Escopo"). Corrija cada achado do grupo 1 em sua causa raiz. Se uma correção mudar comportamento documentado, atualize essa documentação no mesmo commit, seguindo "Escrita". Se você estiver confiante de que um achado é um falso positivo, não mude código. Registre o achado e o motivo para o corpo do PR. Pergunte sobre achados do grupo 2.

4. Se nada mudou, esta etapa passa. Caso contrário, execute "Executando verificações", então commit:

   Corrige achados da revisão de segurança
   
   - <um bullet por correção>
   

5. Comece a próxima rodada.

Se um achado real de alta ou média severidade do grupo 1 permanecer após a rodada 2, pare e reporte.

Se esta etapa mudou código, execute o skill code-review mais uma vez com <esforço> --fix <branch atual> e a instrução, nos novos commits. Lide com quaisquer achados como na etapa 2, dentro de uma rodada extra. Pare e reporte se eles permanecerem.

5. Registros de decisão

Registre as decisões de design do branch no histórico do git, onde git log as encontrará depois. Cada decisão recebe seu próprio commit. O assunto declara a decisão, então git log --oneline e a lista de commits recentes que um agente vê no início da sessão a carregam sem abrir o commit. Os trailers contêm o motivo, a alternativa rejeitada e os arquivos que a decisão cobre.

1. Colete as decisões já registradas: os trailers do branch e as decisões da base da etapa 2.
2. Leia git diff origin/<base>...HEAD e liste as decisões que ele toma que não têm registro. Uma decisão é uma escolha que um revisor ou agente posterior pode questionar ou...

[...truncado...]