Revisión de PR
Estas reglas aplican a cualquier revisor, humano o agente (Copilot code review, Claude, entre otros).
El skill hermano github cubre el lado del autor: arreglar comentarios,
responder y solicitar la siguiente revisión. Cuando las reglas de revisión propias del repositorio (AGENTS.md,
CONTRIBUTING.md, una guía de estilo) entren en conflicto con este skill, prevalecen las reglas del repositorio.
El objetivo de una revisión es lograr que un PR correcto se fusione. No es encontrar algo que decir. "No se encontraron problemas" es un buen resultado.
El umbral para un hallazgo
Publica un hallazgo solo si puedes nombrar un fallo realista: un llamante real, una entrada o configuración, y el resultado incorrecto que produce. Si no puedes escribir ese escenario en una o dos oraciones, no lo publiques.
| Gravedad | Uso para |
|---|---|
| Bloqueante | Resultados incorrectos en una ruta común, agujeros de seguridad, pérdida de datos, una compilación o pruebas rotas, un cambio que rompe una API pública, o una clara violación de una regla escrita en el repositorio |
| Debería arreglarse | Un error real en una ruta menos común, una prueba faltante para un comportamiento nuevo, o documentación o instrucciones que llevarían a un lector a hacer lo incorrecto en un caso normal |
| Nit | Problemas de nombre, redacción o pequeñas mejoras de claridad. Opcionales por definición. Máximo tres por revisión, y solo en la primera ronda |
No publiques:
- Hipótesis que requieran entrada no realista, un entorno mal configurado o un atacante que ya tenga el acceso que el ataque le otorgaría.
- Código defensivo para un caso que ningún llamante puede alcanzar ("considera agregar una comprobación nula").
- Cualquier cosa que un formateador, linter o verificador de tipos en el repositorio ya imponga.
- Preferencia personal entre dos enfoques razonables.
- Preocupaciones de rendimiento sin una ruta crítica o medición detrás.
- Solicitudes para ampliar el PR: características, refactorizaciones o limpiezas que no eran parte del objetivo original.
- Problemas en código que el PR no modificó, a menos que el PR los empeore. Si hay algo grave de todas formas, menciónalo una vez, marcado como preexistente, no bloqueante.
Para documentación, skills y otras instrucciones, haz una sola pregunta: ¿un lector que siga este texto haría lo incorrecto en un caso normal? Las omisiones para configuraciones poco comunes son nits como mucho. No pidas que se detalle cada caso límite.
Converger entre rondas
Un PR debería volverse más silencioso con cada revisión, no más ruidoso.
- Ronda 1 (primera revisión): el diff completo, todas las gravedades, nits limitados como se indicó.
- Ronda 2 y posteriores (nuevos commits desde tu última revisión):
- Revisa solo lo que cambió desde tu última revisión, y comprueba si tus hallazgos anteriores fueron corregidos.
- No plantees nuevos hallazgos en código que ya revisaste y que no ha cambiado. Si pasaste algo por alto allí, publícalo solo si es bloqueante.
- Sin nits.
- No vuelvas a plantear un hallazgo que el autor respondió con una razón, a menos que tengas nueva evidencia de que la razón es incorrecta. El desacuerdo por sí solo no es evidencia nueva.
- Si nada cumple con el umbral, dilo en una línea y detente. No alargues la revisión.
Redacción de hallazgos
- Un problema por comentario, anclado a la línea correspondiente.
- Comienza con la gravedad:
Bloqueante:,Debería arreglarse:oNit:. - Luego el escenario de fallo en una o dos oraciones, y después la corrección más pequeña que funcione.
- Máximo cinco hallazgos por revisión, los más graves primero. Si hay más, enumera el resto brevemente en el resumen. Fusiona duplicados en un solo comentario que liste cada lugar.
- Sé específico y neutral. Sin elogios de relleno, sin "quizás quieras considerar" con rodeos.
El resumen
Termina con un resumen breve:
- Un veredicto: Aprobar, Aprobar con nits o Cambios solicitados (solo cuando haya al menos un hallazgo bloqueante).
- Conteos por gravedad.
- En la ronda 2 o posteriores: qué hallazgos anteriores están ahora corregidos y cuáles siguen abiertos.
Revisar como agente en un bucle
Cuando otro agente está corrigiendo tus hallazgos y pidiéndote la siguiente revisión:
- Trata las respuestas del autor como parte de la revisión. "Corregido en abc1234" significa revisa ese commit. "Lo dejo como está, porque…" significa que el hallazgo está cerrado a menos que la razón sea incorrecta.
- Después de tres rondas, publica solo hallazgos bloqueantes y di que los elementos restantes son decisión del autor.