differential-review

Visão geral da skill differential-review

O que a differential-review faz

A skill differential-review é um fluxo de trabalho com foco em segurança para revisar PRs, commits e diffs com mais rigor do que um prompt comum. Ela foi feita para revisores que precisam decidir se uma mudança introduz regressões, especialmente em auth, crypto, chamadas externas, mudanças de estado e outros caminhos de alto risco.

Para quem ela é mais indicada

Use a skill differential-review se você estiver revisando código sensível a segurança, herdou um diff grande ou precisa de um método repetível que se adapte ao tamanho do codebase. Ela é uma ótima opção para engenheiros, revisores de segurança e auditores com apoio de IA que querem achados sustentados por evidências, e não uma passada superficial linha a linha.

O que a torna diferente

O principal valor da differential-review é obrigar a considerar contexto antes de tirar conclusões: histórico de base, blast radius, cobertura de testes e limites explícitos de confiança. O repositório também empurra a saída para um relatório markdown estruturado, então a skill não é só um prompt de análise; é um processo de revisão com entrega final.

Como usar a skill differential-review

Instale e carregue a skill

Uma instalação típica da differential-review começa pela toolchain do repositório e depois aponta o agente para a pasta da skill. Neste pacote, o caminho de instalação é plugins/differential-review/skills/differential-review. Se você estiver usando o repo de skills da Trail of Bits, instale com o comando de skills do projeto e depois abra SKILL.md primeiro.

Forneça uma entrada no formato de revisão

Para um melhor uso da differential-review, peça que ela revise um intervalo específico de base/head, um commit ou um PR, e nomeie o tema de segurança, se houver um. Boas entradas parecem com isto: “Revise base..head para auth bypass, reentrancy e testes ausentes; foque nos caminhos de chamadas externas e nas transições de estado.” Entradas fracas como “verifique este diff” deixam espaço demais para adivinhação.

Leia os arquivos certos primeiro

Um bom differential-review guide começa com SKILL.md, depois methodology.md, adversarial.md, patterns.md e reporting.md. Esses arquivos dizem ao agente como montar o contexto de base, quais modelos de ataque usar, quais padrões procurar e como formatar o relatório final. Não há scripts auxiliares nem pastas extras de referência neste plugin, então os arquivos da skill são a fonte da verdade.

Dicas de fluxo que mudam a qualidade da saída

Use a skill quando puder fornecer um diff limpo, um commit de base e contexto suficiente do repositório para inspecionar callers e testes. Diga se o codebase é pequeno, médio ou grande, ou deixe que ele infira a escala, mas não pule a etapa de base/histórico. Para differential-review for Code Review, as entradas de maior valor são concretas: arquivos alterados, possíveis fronteiras de confiança, funções suspeitas e qualquer histórico de regressão que você já conheça.

FAQ da skill differential-review

A differential-review serve só para revisões de segurança?

Sim, principalmente. Ela foi projetada para revisão diferencial com foco em segurança, não para limpeza de estilo geral nem aceitação de features. Ainda dá para usá-la em code review comum, mas o valor principal aparece quando a mudança pode afetar fronteiras de confiança, integridade de dados ou explorabilidade.

Em que ela é diferente de um prompt comum?

Um prompt comum pode resumir o diff; a differential-review tenta provar ou refutar o risco com histórico, blast radius e modelagem do atacante. Ela também espera um relatório em markdown, o que facilita repassar ou arquivar a saída.

Ela é amigável para iniciantes?

Ela pode ser usada por iniciantes, mas pressupõe que a pessoa consiga apontar para um diff específico e queira uma análise estruturada. Se você não conhece bem o codebase, a skill ainda ajuda porque exige contexto de base e torna explícitas as lacunas de cobertura.

Quando eu não devo usar?

Não use a differential-review para mudanças triviais de texto, PRs de baixo risco só de formatação ou casos em que você só precisa de um resumo de um parágrafo. Ela é exagerada quando não há risco relevante de segurança ou regressão, e o processo só agrega valor se houver algo que realmente valha uma análise mais profunda.

Como melhorar a skill differential-review

Forneça um contexto de revisão mais forte

A maior melhoria vem de dar à skill a superfície exata da revisão: número do PR, intervalo de commits, branch de destino e qualquer área suspeita de risco. Se você conhece o domínio do projeto, diga isso logo de início: uma mudança em Solidity, um fluxo de auth de API ou um caminho de pagamento direciona a análise para o modelo de ataque certo.

Peça a profundidade certa na primeira passada

Se quiser um uso melhor da differential-review, especifique se a prioridade é correção, explorabilidade ou risco de regressão. Por exemplo: “Foque em funções chamáveis externamente, validação alterada e quaisquer testes ausentes para novos branches.” Isso afunila a busca para os caminhos que mais importam e reduz achados barulhentos.

Fique atento aos modos de falha comuns

Os erros mais comuns são tratar diffs pequenos como de baixo risco, ignorar o histórico de código removido e esquecer callers transitivos ao avaliar o blast radius. A skill foi escrita justamente para evitar esses deslizes, mas ainda precisa de uma base concreta e de um diff claramente delimitado para fazer isso bem.

Itere depois do primeiro relatório

Use o primeiro relatório para refinar a próxima passada. Se o resultado vier amplo demais, peça um modelo de atacante mais estreito ou uma inspeção mais profunda de um subsistema. Se vier superficial demais, peça para rodar de novo com mais histórico, uma análise de testes mais rigorosa ou um foco mais estrito em invariantes e caminhos de regressão.