Revisão da mudança
Esta skill revisa uma mudança, e não uma tela. Ela resolve o escopo, expande os arquivos alterados para as superfícies que eles afetam, lê ambos os lados do diff e classifica cada achado.
O escopo é tudo que ela gerencia. As regras de domínio pertencem às skills better-*. A severidade, consolidação, cobertura, o limite e o veredito pertencem à better-interface, para quem esta skill entrega a revisão.
Corretude, testes, segurança e desempenho pertencem à revisão de código geral do projeto. Mencione a preocupação uma vez e siga em frente.
A mudança, não o código-fonte
O autor está perguntando "eu piorei isso?". Relate o que a mudança causou e fique quase em silêncio sobre o que ela apenas tocou. Três achados pré-existentes são uma cortesia; trinta são uma revisão diferente que ninguém pediu.
Leia a mudança antes de formar uma opinião sobre ela. A intenção declarada decide o que conta como incompleto, e um diff lido superficialmente produz achados sobre código que o próximo hunk já corrigiu.
Princípios fundamentais
1. Resolva o escopo da mudança primeiro
A invocação inteira é o alvo, então /interface-review pr 482 revisa o pull request 482. A resolução do escopo contém os alvos aceitos e como cada um é resolvido.
Sem alvo fornecido, resolva nesta ordem e pare na primeira correspondência:
HEADestá à frente degit merge-base origin/<default-branch> HEAD: esse intervalo mais quaisquer alterações não confirmadas, com a contagem de commits e a contagem de arquivos não confirmados declaradas separadamente.- A árvore de trabalho está suja: as alterações não confirmadas.
- Nenhum dos dois: não há mudança para revisar. Pare e pergunte, conforme Sem mudança, pergunte em vez de inventar uma.
A ordem importa. Verifique a árvore de trabalho primeiro e uma edição de formatação perdida obscurece um branch de doze commits, com o relatório ainda alegando cobertura total.
Exclua lockfiles, snapshots, saída gerada, código vendido e binários, e nomeie o que foi excluído. Um escopo vazio após exclusões chega ao mesmo lugar por um caminho diferente.
2. Sem mudança, pergunte em vez de inventar uma
Uma árvore limpa sem nada à frente do merge base significa que o usuário pediu para revisar uma mudança que não existe. Nunca recorra a HEAD~1..HEAD por conta própria. O último commit é o que quer que tenha caído, geralmente um merge, geralmente trabalho de outra pessoa, e um relatório sobre ele é indistinguível de um relatório sobre o que o usuário queria.
Declare os fatos do repositório que você encontrou, então ofereça os caminhos e aguarde. Nada a revisar contém os fatos a serem colhidos:
- O último commit,
HEAD~1..HEAD, nomeado pelo SHA curto e assunto, para que o usuário veja o que obteria antes de escolhê-lo. - Um alvo que eles nomeiem:
pr <n>, um branch, uma ref ou um intervalo, resolvido conforme Resolva o escopo da mudança primeiro. - Uma auditoria de interface do repositório inteiro, que não é uma revisão de mudança. Entregue-a para
better-interfacecomo uma revisão de escopo de repositório, sem o bloco de escopo, status ou seção pré-existente desta skill. Sem mudança, todo achado é pré-existente e a classificação não diz nada.
Verifique se há um pull request aberto no branch atual antes de perguntar e ofereça-o primeiro. Um branch cujos commits já foram mesclados resulta em nenhuma mudança, enquanto seu pull request ainda é exatamente o que o usuário queria.
Quando o escopo se esvaziou após exclusões, diga quais arquivos foram excluídos e pergunte da mesma forma. Nunca relate uma revisão de nada como Approve.
3. Um diff não é uma superfície
Um arquivo alterado é evidência, não o assunto da revisão. Seu raio de explosão é o conjunto de superfícies em que ele é renderizado; revise essas.
Expanda o raio de explosão em um salto por padrão: os importadores e chamadores diretos. Expanda um segundo salto apenas para design tokens, valores de tema e primitivas compartilhadas, onde uma linha atinge todo o produto.
Revise no máximo cinco consumidores, ordenados por a regra em Resolução de escopo, então declare quantos você não expandiu. Uma varredura sem limites não pode sustentar a cobertura que alega, e um limite não declarado parece completude.
4. Leia as linhas removidas
Regressões são invisíveis no estado pós-mudança. Leia o lado - de cada hunk comparando com Sinais removidos.
Um sinal é uma pista, não um achado. Uma remoção é apenas uma regressão quando nada na mudança a substitui, e a skill de domínio é dona desse julgamento. Encaminhe cada remoção não correspondida ao seu proprietário, relate apenas o que essa skill confirmar e marque o status como Regression. Isso diz ao autor que eles quebraram algo que funcionava, em vez de terem cometido um novo erro.
5. Classifique cada achado
Dê a cada achado um status:
Introduced: a mudança o criou.Regression: a mudança enfraqueceu algo que estava correto anteriormente.Pre-existing: presente no código tocado, mas não causado por esta mudança.
Status é pelo que o diff tocou, não pelo arquivo em que está: uma linha que a mudança nunca tocou é Pre-existing mesmo a três linhas de um hunk. Confirme contra a ref base quando necessário:
git blame -L <linha>,<linha> "$BASE" -- caminho/para/arquivo
Entregue cada achado com seu status anexado e deixe better-interface aplicar suas regras de limite e veredito.
6. Julgue a mudança pela sua intenção declarada
Leia o título e o corpo do pull request, o issue vinculado e as mensagens de commit, então revise se a interface entrega o que eles alegam.
Isso é o que revela a mudança incompleta. Uma revisão de superfície não pode vê-la, porque inspeciona os estados que estão presentes, e aqui o ponto são os que estão ausentes:
- Uma nova variante, tamanho ou tema aplicado a alguns estados, mas não a todos: hover, focus, active, disabled, loading, selected.
- Uma nova string voltada ao usuário sem entrada no catálogo de tradução que o projeto mantém.
- Um novo componente sem estados vazio, carregando, erro, desabilitado ou de largura estreita.
- Um controle adicionado a uma superfície, mas não aos irmãos que já carregam seus pares.
Não reporte aumento de escopo. Se uma mudança faz demais é uma questão de processo, não de interface.
7. Entregue a revisão para better-interface
Entregue para better-interface o bloco de escopo, as superfícies afetadas e um status para cada achado. Ela encaminha para as skills de domínio, aplica severidade, consolida, impõe o limite e emite o veredito.
Se better-interface estiver indisponível, relate o escopo resolvido e o inventário de arquivos, nomeie-a como a skill ausente e pare. Não invente uma escala de severidade, um limite ou um veredito.
8. Nunca mude a árvore de trabalho
Uma revisão de mudança é somente leitura, incluindo o checkout. Busque refs de pull request; nunca faça checkout delas. git fetch escreve apenas em .git e é permitido. gh pr checkout, git checkout, git switch e git stash reescrevem os arquivos que o autor tem abertos. Eles falham contra edições locais ou as descartam, portanto nunca são permitidos.
A verificação renderizada é opcional. Marque alegações visuais e de runtime como Not verified a menos que o projeto exponha uma prévia barata ou o usuário peça uma revisão renderizada. Quando isso acontecer, use uma worktree isolada (git worktree add /tmp/review-<n> refs/remotes/pr/<n>) e remova-a quando terminar.
Antes de finalizar
| Erro | Correção |
|---|---|
| Uma edição perdida revisada em vez do branch | Verifique merge-base antes da árvore de trabalho e reporte ambas as contagens |
| O último commit revisado porque não havia mudança | Declare os fatos e ofereça o último commit, um alvo nomeado ou uma auditoria de repositório |
| Hunks revisados sem seus consumidores | Expanda um salto, dois para tokens e primitivas, e nomeie o que você pulou |
Apenas o lado + do diff lido | Pesquise o lado - por sinais de acessibilidade, foco, movimento e texto removidos |
| Uma substituição equivalente reportada como regressão | Encaminhe a remoção ao seu proprietário; relate apenas o que ele confirmar |
| Uma remoção reportada como novo erro | Marque o status como Regression para que o autor saiba que costumava funcionar |
Uma linha perto de um hunk com status Introduced | Dê o status pelo que o diff tocou, confirmado com git blame contra a ref base |
| Um pull request recebido com checkout para revisá-lo | Busque a ref e revise-a no lugar |
| Números de linha citados que não existem na ref revisada | Cite contra a ref head nomeada no bloco de escopo |
| A escala de severidade ou o limite de achados reafirmados aqui | Diferencie para better-interface |
| Achados de corretude, teste ou segurança no relatório | Mencione a preocupação uma vez, aponte para a revisão de código do projeto e abandone-a |
Formato da saída da revisão
Abra com o bloco de escopo:
| Campo | Valor |
|---|---|
| Alvo | branch, working, staged, pr 482 ou o intervalo conforme inserido |
| Ref base | origin/main em a1b2c3d |
| Ref head | refs/remotes/pr/482 em e4f5g6h |
| Commits | 7 commitados, 2 arquivos não commitados |
| Arquivos no escopo | 12 após exclusões |
| Excluídos | pnpm-lock.yaml, src/__snapshots__/: lockfile e snapshots |
| Superfícies expandidas | CheckoutPage, SettingsPanel; 3 consumidores adicionais de Button não expandidos |
A tabela de cobertura a segue inalterada. Um domínio sem evidência no escopo da mudança é Not reviewed: no evidence in the change scope, que é uma declaração de cobertura, e não uma lacuna.
Em seguida, os achados, com uma coluna Status conforme Classifique cada achado:
| Severidade | Domínio | Status | Localização | Antes | Depois | Por que |
|---|---|---|---|---|---|---|
| ALTA | Acessibilidade | Regression | src/Dialog.tsx:42 | aria-label="Close" removido nesta mudança | Restaure aria-label="Close" no controle apenas de ícone | O controle de fechar tinha um nome acessível antes desta mudança e não tem mais |
Sem achados Introduced ou Regression, omita a tabela e declare "Nenhum achado de interface acionável nesta mudança."
Em seguida, achados Pre-existing, no máximo três, maior severidade primeiro, declarados claramente como não sendo responsabilidade desta mudança. Omita a seção quando não houver nenhum.
| Severidade | Domínio | Localização | Problema |
|---|---|---|---|
| MÉDIA | Tipografia | src/Toolbar.tsx:7 | Badges numéricos usam figuras proporcionais; predata esta mudança |
O limite e o veredito cobrem apenas Introduced e Regression. Achados Pre-existing ficam fora do limite, então tocar em um arquivo legado não pode se transformar em uma auditoria de arquivo inteiro. Eles ficam fora do veredito também, então uma mudança cujos únicos achados são pré-existentes é um Approve.
Termine com Block quando qualquer HIGH permanecer e Approve caso contrário, deixando os achados restantes na tabela como trabalho a fazer. Quando better-interface estiver disponível, a escala de severidade e o limite vêm dela.