Revisão de Código

Atue como um revisor sênior. Revise as diferenças entre HEAD e uma base fixa fornecida pelo usuário. Produza um artefato rastreável:

CODE-REVIEW.md: contexto da revisão, resumo, eixo Especificação, eixo Padrões, validação sugerida, evidências, suposições, perguntas em aberto e rastreabilidade.

Revise dois eixos separadamente:

Padrões: o código segue as convenções deste repositório, políticas de segurança, padrões de teste e decisões arquiteturais?
Especificação: o código implementa fielmente a issue, PRD ou especificação?

Nunca misture os dois resultados. Uma alteração pode seguir todas as convenções e ainda implementar o requisito errado.

Não emita uma aprovação automática. Relate apenas riscos e validações necessárias.

Quando usar

Use esta skill quando o usuário:

solicitar uma revisão de branch, PR, merge request ou trabalho em andamento;
pedir para revisar alterações desde uma branch, commit, tag, data ou HEAD~N;
quiser saber se uma alteração segue os padrões do repositório;
quiser saber se uma alteração implementa a issue, PRD ou especificação;
quiser um artefato de revisão rastreável com evidências e validação sugerida.

Quando não usar

Não use esta skill para:

uma auditoria de segurança completa com CVSS, CWE e mapeamento OWASP; use security-audit;
descoberta de produto, PRD, SPEC, marcos ou decomposição de tarefas; use techlead;
tokens de design, bibliotecas de componentes ou auditorias de acessibilidade; use design-system;
uma alteração de linha única sem diff e sem base fixa; revise diretamente ou peça uma base;
executar testes, builds, linters ou deploys. Esta skill revisa e sugere validação; não executa a menos que o usuário peça explicitamente.

Regras inegociáveis

Fixe a base antes de revisar. Pergunte ao usuário quando a base estiver faltando. Nunca assuma main.
Valide a referência com git rev-parse --verify e revise git diff <base>...HEAD.
Pare e informe quando a base não existir ou o diff estiver vazio. Não continue para revisões especializadas.
Mantenha os eixos Especificação e Padrões separados na análise, nos achados e no relatório.
Padrões do repositório documentados têm prioridade sobre heurísticas gerais.
Ignore problemas já detectados e bloqueados por lint, formatador, typechecker ou CI.
Diferencie uma violação objetiva de uma sugestão de melhoria.
Não proponha refatorações fora do diff, exceto por segurança, corretude ou risco de regressão.
Cada achado deve ter evidência: um trecho de diff, um arquivo e linha, um requisito da especificação ou uma observação reproduzível.
Não invente linhas, comportamentos ou requisitos. Se a evidência for insuficiente, escreva uma nota ou uma pergunta em aberto.
Redija segredos, tokens, dados pessoais e dados de cliente. Substitua valores por [REDACTED].
Somente leitura por padrão: não modifique código de aplicação, dependências, configuração, commits ou pull requests.
Não execute testes, linters, builds ou deploys a menos que o usuário peça explicitamente.
Não reduza uma gravidade para desbloquear um lançamento. Registre o risco.
Não emita um veredito de aprovação automática. Relate riscos e a validação ainda necessária.
Escreva o artefato em inglês por padrão. Mantenha IDs, marcadores, valores de gravidade, valores de eixo e valores de status em inglês.
Preserve todo marcador legível por máquina no template do relatório.
Pare a revisão quando as perguntas restantes não alterariam um achado, uma gravidade ou o plano de validação.

Modos

Selecione o modo antes de iniciar e registre-o no artefato.

Revisão: fixe a base, leia o diff, revise ambos os eixos e escreva ou atualize CODE-REVIEW.md.
Validar: valide um CODE-REVIEW.md existente em relação ao contrato do relatório sem refazer a revisão.

Fluxo de trabalho

Siga estas portas em ordem. Não pule nenhuma porta.

Porta 1: Fixar a base de revisão

Identifique o ponto fixo: uma branch, SHA de commit, tag, main, origin/main, HEAD~N ou outra referência explícita.
Se o usuário não forneceu uma base, pergunte qual base deve ser usada. Não adivinhe.
Valide a referência:
```
git rev-parse --verify <base>
```
Verifique se o repositório é raso quando a merge-base pode estar faltando:
```
git rev-parse --is-shallow-repository
```
Gere o diff contra a merge-base:
```
git diff <base>...HEAD
```
Liste os commits incluídos:
```
git log <base>..HEAD --oneline
```

Colete o tamanho do diff e os arquivos alterados:

git diff --stat <base>...HEAD
git diff --name-status <base>...HEAD

Inspecione a árvore de trabalho:
```
git status --short
```
Se existirem alterações não commitadas, pergunte se elas estão no escopo. Quando estiverem, inclua git diff e git diff --cached como uma superfície adicional de revisão e registre a decisão.
Se a base não existir, a merge-base não puder ser resolvida ou o diff estiver vazio, pare e informe o usuário. Não continue para a Porta 2.
Registre cada comando, seu destino e a saída relevante na seção de evidências do relatório.

Quando o usuário fornecer uma data em vez de uma referência, resolva explicitamente o último commit antes dessa data:

git rev-list -1 --before=<date> HEAD

Use o commit resultante como base somente após o usuário confirmá-lo.

Porta 2: Encontrar a especificação

Procure a fonte do requisito nesta ordem:

Uma referência de issue nos commits, nome da branch ou descrição do PR (#123, Closes #45, Fixes #78).
Um caminho de especificação fornecido pelo usuário.
Um arquivo em docs/, specs/, .scratch/ ou tasks/ relacionado ao nome da branch ou à funcionalidade.
Pergunte ao usuário onde está a especificação.

Leia a fonte e extraia:

o problema e o resultado esperado;
os critérios de aceitação;
os itens explícitos dentro e fora do escopo;
as restrições, casos de borda e requisitos não funcionais;
os requisitos que o diff não toca mas deve preservar.

Mapeie cada requisito para os arquivos, comportamentos e testes que o implementam.

Se o usuário disser que não há especificação, registre exatamente:

Nenhuma especificação disponível; revisão da Especificação foi pulada.

Defina Revisão da Especificação: pulada e não revise o eixo Especificação nem invente requisitos.

Porta 3: Carregar os padrões do repositório

Leia, quando existirem:

CONTRIBUTING.md;
CODING_STANDARDS.md;
ARCHITECTURE.md;
SECURITY.md;
ADRs em docs/adr/;
configuração de lint, formatador, teste e CI;
exemplos aprovados recentes no repositório.

Regras:

Padrões documentados do repositório têm prioridade sobre heurísticas gerais.
Ignore problemas que lint, formatador, typechecker ou CI já detectam e bloqueiam.
Diferencie uma violação objetiva de uma sugestão de melhoria.
Cite o padrão que fundamenta cada achado de Padrões.
Se nenhum padrão for documentado, use heurísticas gerais e rotule-as como tal na referência do achado.
Se um padrão for ambíguo, registre uma pergunta em aberto em vez de inventar uma regra.

Porta 4: Revisar por categoria

Revise cada arquivo alterado e cada hunk significativo. Não revise apenas as linhas adicionadas; considere o código circundante e os consumidores do comportamento alterado.

Eixo Especificação

Requisitos atendidos: mapeie cada critério de aceitação para sua implementação e testes.
Lacunas ou implementação incorreta: requisito ausente, implementação parcial, comportamento errado, contradição com a especificação ou requisito não testado.
Escopo adicional: comportamento adicionado fora da especificação, refatorações não solicitadas, contratos públicos alterados ou aumento de escopo.
Para cada lacuna, cite o requisito exato e o arquivo e linha onde a implementação falha.

Eixo Padrões

Corretude: bugs, casos de borda, tratamento de erros, concorrência, null/undefined, tipos e comportamento inesperado.
Segurança: injeção, autenticação e autorização, validação de entrada, exposição de dados, segredos, SSRF, XSS, CSRF, manipulação insegura de arquivos e limites de permissão.
Testes: cobertura de caminhos novos ou alterados, casos negativos, regressões, qualidade de asserção e instabilidade.
API e compatibilidade: mudanças que quebram compatibilidade, contratos públicos, versionamento, migrações e compatibilidade com consumidores.
Desempenho: consultas N+1, loops desnecessários, alocações, comportamento de cache, índices e trabalho síncrono evitável.
Manutenibilidade: nomes, duplicação, acoplamento, responsabilidades, abstrações prematuras e consistência com o domínio.
Observabilidade: logs, métricas, tracing, alertas e mensagens de erro úteis quando a alteração afeta a operação em produção.

Use references/review-checklist.md para a lista de verificação detalhada.

Porta 5: Escrever o relatório

Crie ou atualize CODE-REVIEW.md usando references/report-template.md. A localização padrão é a raiz do diretório de trabalho atual. Aceite um caminho diferente quando o usuário fornecer um.

Requisitos:

Preserve o marcador do artefato e todo marcador de seção obrigatório.
Registre a base, head, merge-base, contagem de commits, arquivos alterados, fontes de padrões e fonte da especificação.
Mantenha as seções de Especificação e Padrões separadas. Nunca mova um achado de Especificação para Padrões ou vice-versa.
Use IDs de achados estáveis: CR-001, CR-002, e assim por diante. Não renumere achados aprovados sem registrar a alteração.
Use uma gravidade por achado: blocking, recommended ou note. Siga references/severity-baseline.md.
Dê a cada achado um eixo, uma categoria, uma localização, um problema, evidência, uma sugestão, uma referência e uma etapa de verificação.
Faça o marcador de contagens corresponder exatamente aos achados.
Faça as contagens do resumo corresponderem ao marcador de contagens.
Mapeie cada achado para evidência e validação sugerida na seção de rastreabilidade.
Declare se a revisão da Especificação foi realizada ou pulada. Quando pulada, inclua a frase exata da Porta 2.
Escreva Nenhum achado em uma categoria quando não houver achados. Não deixe seções vazias.
Não inclua segredos, dados pessoais ou dados de cliente. Redija-os como [REDACTED].
Não inclua um veredito de aprovação, LGTM ou Pode enviar.

Porta 6: Validação

Resolva o caminho do validador relativo a este SKILL.md e execute:

python3 skills/code-review/scripts/validate_review.py CODE-REVIEW.md

Opções:

--strict                     Trate avisos como falhas.
--json                       Emita um relatório legível por máquina.
--min-findings N             Exija pelo menos N achados. O padrão é 0.
--require-spec               Falhe quando a revisão da Especificação foi pulada.
--require-standards-sources  Falhe quando nenhuma fonte de padrões está listada.

Corrija cada erro e reexecute o validador. Não entregue um relatório que falhe na validação.

Se o Python não estiver disponível, execute a lista de verificação manual em references/validation-checklist.md.

Porta 7: Handoff

Relate:

onde CODE-REVIEW.md foi escrito;
a base revisada, a merge-base, a contagem de commits e os arquivos alterados;
as contagens de achados por gravidade e por eixo;
o status da revisão da Especificação e a lacuna de Especificação de maior risco;
os achados de Padrões de maior risco e seu impacto;
o resultado da validação;
as limitações, arquivos excluídos e verificações que não foram executadas;
que nenhum código de aplicação, dependência ou configuração foi alterado.

Ofereça-se para propor correções ou um plano de remediação, mas não modifique código, faça commit, faça push ou abra um pull request a menos que o usuário peça explicitamente.

Regra dos dois eixos

Os eixos respondem a perguntas diferentes e devem permanecer separados:

Eixo	Pergunta	Evidência típica
Especificação	A alteração implementa o requisito solicitado?	Issue, PRD, especificação, critérios de aceitação
Padrões	A alteração segue convenções do repositório e padrões de engenharia?	CONTRIBUTING, ADRs, config lint/test/CI, revisão de código

Um achado pode existir em ambos os eixos apenas quando a causa raiz for diferente e a remediação for diferente. Caso contrário, registre-o uma vez sob o eixo que possui a causa raiz e faça referência cruzada ao outro eixo no campo de referência.

Exemplos:

Uma alteração segue todas as convenções, mas omite um critério de aceitação: um achado blocking de Especificação e nenhum achado de Padrões.
Uma alteração implementa o requisito, mas introduz uma bypass de autorização: um achado blocking de Padrões e uma nota de Especificação de que o requisito foi implementado, mas de forma insegura.
Uma alteração implementa o requisito com um padrão documentado, mas ruim: um achado recommended de Padrões e uma entrada "requisitos atendidos" de Especificação.

Contrato do artefato

CODE-REVIEW.md começa com:

<!-- code-review:artifact type=review version=1 -->

Seções obrigatórias usam marcadores:

<!-- code-review:section id=summary -->
<!-- code-review:section id=context -->
<!-- code-review:section id=spec -->
<!-- code-review:section id=standards -->
<!-- code-review:section id=validation -->
<!-- code-review:section id=evidence -->
<!-- code-review:section id=assumptions -->
<!-- code-review:section id=traceability -->

A seção de Especificação também usa um marcador de status:

<!-- code-review:spec status=performed -->
<!-- code-review:spec status=skipped -->

O marcador de contagens deve corresponder aos achados:

<!-- code-review:counts blocking=1 recommended=2 note=0 -->

Cada achado usa um marcador imediatamente antes do seu título:

<!-- code-review:finding id=CR-001 axis=standards severity=blocking category=security status=open -->
### CR-001: Título curto do achado

Cada corpo de achado contém:

Eixo: Especificação ou Padrões
Gravidade: Blocking, Recommended ou Note
Categoria: spec-gap, scope, correctness, security, tests, api, performance, maintainability ou observability
Localização: caminho/para/arquivo.ext:42, caminho/para/arquivo.ext ou n/a para um achado de Especificação sem código
Problema: o defeito, risco ou lacuna
Evidência: um trecho de diff, um arquivo e linha, um requisito da especificação ou uma observação reproduzível
Sugestão: uma ação de remediação ou validação
Referência: a especificação, padrão ou outro achado que fundamenta o achado
Verificação: a etapa que confirmaria a correção

Saída do fluxo

O artefato CODE-REVIEW.md é a única saída desta skill. Nenhum código de aplicação, dependência, configuração, commit ou pull request é criado ou modificado.

rmsaitam/code-review

O que é code-review?

Perguntar na sua IA favorita

Documentação