differential-review

Resumen general de la skill differential-review

Qué hace differential-review

La skill differential-review es un flujo de trabajo centrado en seguridad para revisar PR, commits y diffs con más rigor que un prompt normal. Está pensada para revisores que necesitan decidir si un cambio introduce regresiones, sobre todo en auth, crypto, llamadas externas, cambios de estado y otras rutas de alto riesgo.

Para quién encaja mejor

Usa la skill differential-review si estás revisando código sensible para seguridad, si heredaste un diff grande o si necesitas un método repetible que se adapte al tamaño del codebase. Encaja especialmente bien para engineers, security reviewers y auditores asistidos por IA que quieren hallazgos basados en evidencia en lugar de un repaso superficial línea por línea.

Qué la hace diferente

El valor principal de differential-review es que obliga a reunir contexto antes de sacar conclusiones: historial base, blast radius, cobertura de tests y límites explícitos de confianza. Además, el repositorio empuja la salida a un informe estructurado en markdown, así que la skill no es solo un prompt de análisis; es un proceso de revisión con entregable.

Cómo usar la skill differential-review

Instalar y cargar la skill

Una instalación típica de differential-review install empieza con la toolchain del repositorio y luego apunta al agente hacia la carpeta de la skill. En este paquete, la ruta de instalación es plugins/differential-review/skills/differential-review. Si estás usando el repo de skills de Trail of Bits, instala con el comando de skills del proyecto y abre primero SKILL.md.

Darle una entrada con forma de revisión

Para obtener el mejor differential-review usage, pídele que revise un rango base/head concreto, un commit o un PR, y nombra el problema de seguridad si ya lo tienes claro. Buenas entradas se parecen a: “Revisa base..head para auth bypass, reentrancy y tests faltantes; céntrate en rutas de llamadas externas y transiciones de estado”. Entradas débiles como “revisa este diff” dejan demasiado margen para adivinar.

Leer primero los archivos correctos

Una buena differential-review guide empieza con SKILL.md, luego methodology.md, adversarial.md, patterns.md y reporting.md. Estos archivos indican al agente cómo construir contexto base, qué modelos de ataque usar, qué patrones buscar y cómo formatear el informe final. No hay scripts auxiliares ni carpetas extra de referencia en este plugin, así que los archivos de la skill son la fuente de verdad.

Consejos de workflow que cambian la calidad del resultado

Usa la skill cuando puedas proporcionar un diff limpio, un commit base y suficiente contexto del repositorio para inspeccionar callers y tests. Indícale si el codebase es pequeño, mediano o grande, o deja que infiera la escala, pero no te saltes el paso de baseline/historial. Para differential-review for Code Review, las entradas de mayor valor son concretas: archivos cambiados, fronteras de confianza probables, funciones sospechosas y cualquier historial de regresiones que ya conozcas.

Preguntas frecuentes sobre la skill differential-review

¿differential-review es solo para revisiones de seguridad?

Sí, principalmente. Está diseñada para differential review enfocado en seguridad, no para limpieza general de estilo ni para aceptación de funcionalidades. Aun así, puedes usarla para una revisión de código ordinaria, pero su mayor valor aparece cuando el cambio puede afectar fronteras de confianza, integridad de datos o explotabilidad.

¿En qué se diferencia de un prompt normal?

Un prompt normal puede resumir el diff; differential-review intenta demostrar o descartar riesgo con historial, blast radius y modelado de atacante. También espera un informe en markdown, lo que facilita entregar o archivar el resultado.

¿Es apta para principiantes?

Sí, se puede usar si eres principiante, pero asume que puedes señalar un diff concreto y quieres un análisis estructurado. Si no conoces bien el codebase, la skill igual ayuda porque exige contexto base y deja explícita la cobertura faltante.

¿Cuándo no debería usarla?

No uses differential-review para cambios de texto triviales, PRs de bajo riesgo que solo tocan formato o casos en los que solo necesitas un resumen de un párrafo. Es excesiva cuando no hay un riesgo real de seguridad o regresión, y su proceso solo aporta valor si hay algo que merezca una revisión profunda.

Cómo mejorar la skill differential-review

Aportar mejor contexto de revisión

La mejora más grande viene de darle a la skill la superficie exacta de revisión: número de PR, rango de commits, rama destino y cualquier área de riesgo sospechosa. Si conoces el dominio del proyecto, dilo desde el principio: un cambio en Solidity, un flujo de auth de API o una ruta de pagos orienta el análisis hacia el modelo de ataque adecuado.

Pedir la profundidad correcta desde el primer pase

Si quieres un mejor differential-review usage, especifica si te importa más la corrección, la explotabilidad o el riesgo de regresión. Por ejemplo: “Céntrate en las funciones accesibles externamente, la validación modificada y cualquier test faltante para nuevas ramas”. Eso acota la búsqueda a las rutas que más importan y reduce hallazgos ruidosos.

Vigilar los modos de fallo más comunes

Los fallos más habituales son tratar diffs pequeños como de bajo riesgo, ignorar el historial del código eliminado y olvidar callers transitivos al evaluar el blast radius. La skill está escrita explícitamente para evitar esos errores, pero aun así necesita un baseline concreto y un diff claramente acotado para hacerlo bien.

Iterar después del primer informe

Usa el primer informe para afinar el siguiente pase. Si el resultado es demasiado amplio, pide un modelo de atacante más estrecho o una inspección más profunda de un subsistema. Si es demasiado superficial, pídele que vuelva a ejecutarse con más historial, una revisión de tests más estricta o un foco más duro en invariantes y rutas de regresión.