Explica Este PR
Lee un pull request de GitHub, comprende qué cambia y escribe una explicación en lenguaje sencillo. Publícala como un comentario en el PR para que los revisores tengan contexto instantáneo.
Paso 1: Verificar la Configuración
Confirma que gh esté autenticado:
github auth status
Si no está autenticado: github auth login y sigue las instrucciones.
Confirma la entrada. El usuario debe proporcionar una de las siguientes opciones:
- Una URL de PR de GitHub (ej.
https://github.com/propietario/repo/pull/123) - Un número de PR en el repositorio actual (ej.
#123) - La palabra clave "current" para usar el PR de la rama actual
Si no hay entrada, pregunta: "¿Qué PR debería explicar? Comparte la URL, el número de PR o di 'current' para la rama activa."
Paso 2: Obtener el Contexto del PR
Obtener metadatos del PR:
github pr view URL_O_NUMERO_DEL_PR --json number,url,title,body,author,baseRefName,headRefName,additions,deletions,changedFiles,commits,labels,state,isDraft
Si isDraft es true, notifica al usuario: "Este PR aún está en borrador. La explicación se basa en su estado actual."
Obtener el diff:
github pr diff URL_O_NUMERO_DEL_PR
Si el diff tiene más de 400 líneas, lee el resumen --stat y las primeras 200 líneas del diff:
github pr view URL_O_NUMERO_DEL_PR --json files
github pr diff URL_O_NUMERO_DEL_PR | head -200
Obtener comentarios existentes (para evitar repetir lo que ya está allí):
github pr view URL_O_NUMERO_DEL_PR --json comments --jq '.comments[].body' 2>/dev/null | head -20
Paso 3: Escribir la Explicación
Escribe dos párrafos. Lee cada regla antes de escribir.
Párrafo 1: Qué hace (técnico)
- Una oración por cambio importante
- Nombra los archivos, funciones o sistemas específicos que cambiaron
- Indica el antes/después si el diff lo deja claro
- Incluye números concretos si están presentes en el diff (líneas eliminadas, tablas descartadas, endpoints añadidos)
- Voz activa, tiempo presente
Ejemplo:
Reemplaza el caché de sesión en memoria de auth.middleware.ts con un caché respaldado por Redis (src/cache/redis.ts). Añade los métodos get, set e invalidate al nuevo módulo Redis y envuelve UserService.getById() con un TTL de 5 minutos. Elimina el caché basado en Map que estaba limitado a un solo proceso y causaba desviación de sesión en múltiples instancias.
Párrafo 2: Por qué importa (impacto empresarial/de producto)
- Quién se beneficia y cómo
- Qué problema resuelve o qué riesgo reduce
- Si los mensajes de commit contienen un "por qué", usa ese contexto
- Si no hay un "por qué" claro en el diff o los commits, omite este párrafo en lugar de adivinar
Ejemplo:
Los usuarios que accedían al endpoint /api/me bajo carga obtenían datos de sesión inconsistentes entre instancias del servidor, causando errores 401 intermitentes. Este cambio hace que el estado de la sesión sea consistente en todas las instancias y reduce la carga de la base de datos al eliminar una consulta por solicitud autenticada.
Reglas para ambos párrafos:
- Sin guiones largos — usa una coma o un punto
- Sin frases de relleno: "este PR", "este cambio", "como puedes ver"
- Sin resultados inventados. Solo indica impactos que sean directamente visibles en el diff o los mensajes de commit
- Si el PR es una refactorización pura sin cambio de comportamiento, dilo explícitamente: "Refactoriza X a Y sin cambio en el comportamiento observable."
- Menos de 150 palabras en total
Paso 4: Autoverificación
Antes de publicar, verifica:
- El párrafo 1 nombra archivos o funciones específicas del diff
- Sin métricas o resultados inventados
- Sin guiones largos
- Sin frases de relleno
- Menos de 150 palabras en total
- Si no existe un "por qué" claro, se omite el párrafo 2 en lugar de adivinar
Corrige cualquier infracción antes de publicar.
Paso 5: Publicar como Comentario del PR
Presenta la explicación al usuario. Pregunta: "¿Listo para publicar esto como comentario del PR, o prefieres editarlo primero?"
Tras la confirmación, pasa el cuerpo por stdin para manejar comillas invertidas, comillas y saltos de línea de forma segura:
github pr comment URL_O_NUMERO_DEL_PR --body-file - << 'EOF'
EXPLICACION_AQUI
EOF
Después de publicar: "Comentario añadido. Véalo en: [url del paso 2]"
Si el usuario dice "solo salida", presenta la explicación en un bloque de código para copia manual sin publicarla.