Descripciones de PR en lenguaje sencillo

¿Qué hace Descripciones de PR en lenguaje sencillo?

Escribe para un mantenedor que necesita entender el cambio rápidamente. Una buena descripción responde tres preguntas en su primera pantalla:

1. ¿Qué faltaba o estaba mal?
2. ¿Por qué era necesario cambiar?
3. ¿Qué es cierto ahora?

Lee el diff real, el cuerpo actual de la PR, los commits, las pruebas y el estado de la PR antes de escribir. El cuerpo anterior y los títulos de los commits describen la intención, no la prueba. No afirmes pruebas manuales, despliegues o comportamiento en producción a menos que el autor lo haya confirmado.

Apertura obligatoria: Lo que cambió y por qué

Cada descripción de PR debe comenzar con una sección ## What Changed and Why propiedad del contribuidor, inmediatamente después de la sección ## Status propiedad del monitor cuando Status está presente. Esto es obligatorio, no un formato opcional.

Usa tres párrafos etiquetados cortos, en este orden:

• Issue: el fallo real del usuario u operador, o el comportamiento faltante.
• Why this change was necessary: por qué ese fallo era importante y por qué se necesita el límite elegido.
• New status quo: el comportamiento concreto después de esta PR.

Mantén cada párrafo etiquetado a una o dos oraciones. Un mantenedor debe poder responder “¿qué sucedió en esta PR?” solo con esta sección. No comiences con mecánicas de implementación, un diseño eliminado o reescribas la historia.

Al revisar una apertura inadecuada, proporciona un reemplazo concreto o un esquema conciso de tres párrafos adaptado al diff real. No te limites a decir que es verboso, poco claro o que necesita una mejor explicación.

Usa esta forma para la mayoría de las PRs:

## What Changed and Why

**Issue:** [El fallo real del usuario u operador, o el comportamiento faltante.]

**Why this change was necessary:** [Por qué era importante y por qué se necesita este límite.]

**New status quo:** [El comportamiento concreto después de esta PR.]

## After merge

[Solo las acciones reales del operador o revisor que quedan. Omite esta sección si no hay ninguna.]

## Verification

[Indica solo las comprobaciones manuales confirmadas y las comprobaciones genuinamente posteriores a la fusión.]

Comienza con la sustancia. No repitas el título de la PR, añadas una introducción ni escribas un resumen que repita el párrafo siguiente.

Qué mantener

• Un estado final claro por cambio material. Un lector que escanea la primera oración de cada párrafo o viñeta debe entender qué cambia después de la fusión.
• Decisiones reales. Menciona una alternativa rechazada solo cuando afecte el comportamiento del producto, el riesgo o un costo significativo. Di qué se eligió y por qué en una oración. No fabriques una etiqueta "Key decision".
• Hechos operativos. Menciona migraciones, rellenos, trabajos programados, integraciones, secretos, orden de despliegue y comportamiento de fallo cuando un revisor u operador necesite actuar sobre ellos.
• Verificación honesta. Separa lo que alguien comprobó realmente a mano del trabajo que verdaderamente debe esperar hasta después de la fusión. No enumeres comandos de lint, build, CI o pruebas. Las pruebas se pueden mencionar en lenguaje sencillo cuando cubren un comportamiento significativo.
• Llamadas abiertas. Incluye solo las decisiones no resueltas que el revisor debe tomar. Pon la pregunta primero, luego una recomendación y su costo. Omite la sección cuando no haya nada que decidir.

Evidencia requerida para sistemas modificados

Una descripción está incompleta cuando cambia un sistema orientado al usuario, un flujo de trabajo de operador material o su configuración, y no muestra al revisor cómo inspeccionarlo.

• Capturas de pantalla o videos cortos: Coloca la evidencia visual en su propia sección ## Visual evidence. Incluye capturas de pantalla para una pantalla modificada o videos cortos para una interacción modificada o un flujo de varios pasos. Incrusta el medio o enlaza a un adjunto estable de la PR. Los pies de foto deben decir qué cambió y qué está viendo el revisor. No sustituyas una captura de pantalla de código fuente, un informe de prueba o una pantalla sin cambios. Coloca la evidencia de teléfono antes que la de computadora portátil para superficies públicas y de eventos, e identifica cada viewport y estado probado. Sigue la habilidad visual-proof para captura, carga y verificación del último commit. Omite esta sección solo cuando la PR no tenga superficie visual o interactiva.
• Configuración, entorno y migraciones: Coloca solo las variables de entorno, secretos, configuraciones de panel y migraciones de base de datos realmente añadidas, eliminadas, renombradas o que cambien el comportamiento en ## Configuration. Comienza con la única acción que un operador debe tomar; mantén la configuración externa ordinaria en una oración corta, por ejemplo: Set up a monitor at <URL> and point it to https://buildpurdue.org/api/health. No internal changes. No llenes la sección con detalles de sondeo, justificaciones ya explicadas en otro lugar o enlaces a runbooks duplicados. Para cada migración real, nombra su ruta confirmada supabase/migrations/, resume el cambio de esquema/datos/políticas, indica requisitos de compatibilidad o relleno, y da el resultado confirmado de la repetición de npm run db:verify. Nunca imprimas valores secretos. Omite la sección cuando no haya cambios de configuración o migración.
• Flujos modificados: Usa diagramas de flujo Mermaid para flujos materiales que cambian. Un flujo es material cuando tiene múltiples pasos, ramas, reintentos, una transferencia entre sistemas o una ruta de fallo. Muestra la ruta modificada y su comportamiento de fallo importante, usando etiquetas sencillas que un revisor pueda leer. Añade un diagrama para cada flujo modificado distinto. No uses un diagrama para un cambio de nombre de un solo paso o un cálculo local trivial.

Estos están separados de la explicación principal. La explicación dice por qué existe el cambio; la evidencia, la configuración y los diagramas permiten a un revisor inspeccionarlo.

Mantenlo legible

• Predetermina 250 palabras o menos. Una descripción puede ser más larga cuando el operador necesita una lista de verificación corta, pero cada oración debe ganarse su lugar.
• Usa párrafos cortos. Usa viñetas solo para una lista real, como pasos de configuración restantes. No conviertas cada oración en una viñeta etiquetada.
• Pon el issue, el por qué y el nuevo status quo en inglés normal. Di quién hace qué.
• Evita código sin formato, consultas, fragmentos de configuración, códigos de estado como sustantivos, jerga, metáforas, exageraciones y guiones largos.
• No expliques cada mecanismo. Mantén el comportamiento que el revisor necesita saber.
• No repitas un hecho en una sección posterior. Si una oración puede desaparecer sin perder información, elimínala.

Status es propiedad del monitor

Los contribuidores son dueños de cada parte de la descripción de la PR excepto ## Status. No añadas, elimines ni edites esa sección tú mismo. El monitor de PR de BuildPurdue es dueño de ella y la mantiene alineada con el estado de revisión actual.

Cuando cambia Status, el monitor también publica un comentario de PR Status update: coincidente. Usa una oración en inglés sencillo: una próxima acción concreta previa a la fusión cuando quede trabajo por hacer, o No more remaining work. cuando no quede nada. Status nunca pertenece a un comentario de revisión de descripción orientado al contribuidor.

No uses Status para ideas futuras opcionales, notas históricas, trabajo solo posterior a la fusión o trabajo seguido por separado que no bloquee esta PR.

Cuando se justifica más estructura

Añade una sección enfocada solo cuando contenga información que no encaje en la explicación principal:

• Database / migrations: qué debe ejecutarse, si los datos existentes siguen siendo compatibles y si se necesita un relleno.
• Operational behavior: qué se ejecuta, cuándo se ejecuta, cómo son visibles los fallos y qué debe configurar un operador.
• Verification: comprobaciones manuales confirmadas y comprobaciones genuinamente posteriores a la fusión.
• Open calls: elecciones de producto o riesgo no resueltas.

Una corrección de error pequeña puede simplemente usar:

## Root cause

## Fix

## Verification

Antes de publicar

1. Verifica que cada afirmación se remonte al diff actual, las pruebas, el estado de la PR o un comando que ejecutaste.
2. Lee la primera pantalla por sí sola. Debe decir claramente el issue, por qué era necesario el cambio y el nuevo status quo.
3. Elimina la narración histórica, los registros de implementación tipo changelog, las explicaciones repetidas y el trabajo no relacionado.
4. Confirma que cualquier migración, despliegue, secreto, panel o acción posterior a la fusión sea explícito y procesable.
5. Vuelve a leerlo en voz alta. Debe sonar como una persona explicando el cambio a un compañero, no como un informe de auditoría.
6. En cada empuje, compara el cuerpo con el nuevo diff y actualízalo cuando el comportamiento, la configuración restante o el estado de verificación hayan cambiado.

Fuente

Edita esta copia bajo .agents/skills/. El hook de pre-commit la refleja en .claude/skills/pr-description/; no edites el espejo directamente.