Explicador de PR
Genera un documento que enseña a un compañero de equipo un cambio: qué estaba mal o faltaba, cómo funciona el sistema a su alrededor, qué hace el cambio y cómo sabemos que funciona.
Argumentos
- Objetivo: un número o URL de PR, o nada.
- Con un PR y la CLI
ghdisponible, obtén los detalles congh pr view <url> --json title,url,body,baseRefName,headRefName,headRefOid,filesy el diff congh pr diff <url>. Lee el código circundante en el commit head del PR (git show <headRefOid>:<path>), no en elHEADlocal. - Sin PR, o sin
gh: explica el cambio local. Usagit diff <base>...HEADpara commits ygit diffmásgit statuspara trabajo no commiteado, donde<base>es la rama por defecto o el primer commit.
- Con un PR y la CLI
--local: usa el checkout local incluso cuando existe un PR (trabajo no subido). Indica en la página que refleja cambios locales.--concise: una versión corta que se lee en unos dos minutos. Como máximo un visual, 3 fragmentos, sin tabla de contenidos, 1–3 frases por sección.--md: escribe Markdown en lugar de HTML (archivo por defectoHANDOVER.mden la raíz del repositorio, a menos que el usuario indique otro). Úsalo para traspasos y cuando no se tenga un navegador a mano.
Audiencia y voz
- El lector es un ingeniero junior del equipo. Usa frases cortas, verbos sencillos, una idea por párrafo.
- No definas conceptos básicos (REST, SQL, JWT, hooks de React) y no uses analogías no técnicas. Mantén el tono técnico, con nombres reales de módulos, funciones, rutas y campos, y números reales.
- Haz que el lenguaje sea simple, no el contenido. Explica una llamada a una biblioteca o un patrón inusual donde aparezca por primera vez.
- Escríbelo como un borrador final. Describe el estado actual directamente. Sin registro de cambios ni frases como "antes pensábamos".
- Sé honesto sobre la certeza. Etiqueta las afirmaciones no comprobadas como "probable, aún no confirmado".
Alcance: explica el cambio, no el diff
- Elige los archivos que cuentan la historia, y dentro de ellos solo las líneas importantes.
- Usa de 1 a 3 fragmentos por archivo, cada uno de menos de ~25 líneas, con
...para partes omitidas. Indica la ruta del archivo y 2–4 frases sobre lo que hace y por qué. - Para una corrección, muestra el código que causó el error y el diff de la corrección.
- Ordena el código por flujo de ejecución, no por orden del diff.
- Omite cambios de infraestructura, renombrados y formato. Mencíonalos en una línea si un revisor los verá en el diff.
1. Comprender el cambio
- Lee el diff y el código circundante. Decide el modo:
- Característica: comportamiento nuevo o una refactorización grande.
- Corrección de error: un síntoma, una causa raíz y una corrección.
- Encuentra la ejecución de verificación más reciente: comando de prueba y recuentos, e idealmente la prueba de que una nueva prueba de regresión falla sin la corrección y pasa con ella. Si esa prueba no existe y es barata, prodúcela:
git stash push -- <archivos fuente>, ejecuta la prueba, luegogit stash pop. También busca una comprobación manual o de extremo a extremo (salida de CLI, una solicitud, una captura de pantalla). Muestra solo la ejecución más reciente de cada una. - Usa los hallazgos de la conversación (análisis de causa raíz, informe de QA, ticket) cuando existan.
2. Esqueleto
Todo documento comienza con una línea de encabezado (repositorio · PR #n · ticket, o repositorio · cambios locales), un título en lenguaje sencillo y una introducción de 1–2 frases.
Corrección de error
- Qué salió mal: el síntoma, dónde se vio, qué se descartó.
- Causa raíz: el lugar exacto donde se rompe el dato o el flujo (
archivo:línea), con un visual si ayuda. - El código que lo causó: uno o dos fragmentos.
- La corrección: un fragmento de diff y por qué funciona. Menciona los efectos secundarios que también corrige.
- Cómo lo sabemos: una prueba de regresión que falla antes y pasa después, recuentos del conjunto completo, una comprobación manual.
- Conclusiones: 2–4 lecciones que un junior pueda reutilizar en otro lugar.
Característica
- Por qué: el problema o el objetivo, con evidencia.
- Dónde se sitúa: contexto de arquitectura o módulo (diagrama), más lo que queda intencionadamente sin cambios.
- Cómo fluye: pasos o un diagrama de flujo vinculado a las tarjetas de código.
- Recorrido por el código: una tarjeta por archivo importante, en orden de flujo.
- Comportamiento a conocer: casos límite, estados, modos de fallo (una tabla si hay más de 3).
- Verificación: solo la ejecución más reciente.
- Conclusión para el revisor: el modelo mental en 2–3 líneas, y dónde mirar con más atención en el diff.
Adiciones para traspaso (incluir siempre con --md; opcional en HTML):
- Cómo ejecutar / probar: comandos exactos.
- Suposiciones realizadas: decisiones tomadas donde la especificación era ambigua, y por qué.
- Preguntas abiertas para el negocio: ordenadas por impacto.
- Riesgos y reversión: qué podría salir mal en producción y cómo revertir.
- Próximos pasos: qué harías con más tiempo.
Conciso: solo Qué salió mal / Qué y por qué, Causa raíz / Cómo funciona, La corrección / Código clave y Cómo lo sabemos.
3. Visuales: solo cuando explican algo que el texto no puede
| Contenido | Uso |
|---|---|
| Arquitectura de módulos o servicios, quién llama a quién, secuencia de solicitudes | flowchart / sequenceDiagram de Mermaid (≤ ~12 nodos) |
| Una rama que se comporta diferente antes y después | Tabla antes/después o un pequeño SVG estático |
| Datos que pasan por etapas, valores descartados por un filtro | Una tabla de ejemplos de entrada → salida, antes vs después |
| Estados, comandos, riesgos, contratos | Tablas |
En Markdown, usa bloques de código con ```mermaid (GitHub los renderiza). Añade animaciones solo si el usuario lo pide.
4. Construcción
- HTML: comienza desde
references/page-template.html(autónomo, modo claro y oscuro, Mermaid y highlight.js desde una CDN). Guarda en.pr-review/<nombre>.html, nombrado según el ticket o PR, olocal-<descripción-corta>. No lo incluyas en git: sigit check-ignore -q .pr-review/falla, añade.pr-review/a.git/info/exclude. No edites.gitignorea menos que te lo pidan.- Fragmentos de código:
<pre><code class="language-<idioma>">…</code></pre>, escapado para HTML. Para un diff de corrección, usalanguage-diffcon líneas-/+. - Mermaid:
<pre class="mermaid">…</pre>. Nunca uses colores fijos.
- Fragmentos de código:
- Markdown (
--md): Markdown estándar de GitHub Flavored Markdown, mismo esqueleto, sin HTML.
5. Verificación única
- HTML: si hay una herramienta de navegador disponible, abre la página una vez con ancho de escritorio y otra con ~400 px. Comprueba que Mermaid se renderiza y el código está resaltado, corrige lo que veas en una sola pasada y no repitas. De lo contrario, indica que no se previsualizó y da el comando para abrirlo (
openen macOS,starten Windows,xdg-openen Linux). - Vuelve a leer cada
archivo:línea, número y comando de la página contra el código. Los hechos deben ser exactos.
6. Informar
Responde con:
- la ruta del archivo
- el modo y las secciones cubiertas
- los visuales usados y qué explica cada uno
- qué ejecución de verificación muestra el documento
- cualquier cosa etiquetada como "aún no confirmado"
Nunca edites el cuerpo de un PR, publiques un comentario ni subas nada sin preguntar antes.