Comprobar que un cambio hace falta antes de abrir un pull request en un proyecto compartido

## Detente y reduce la petición a un único problema real Detente antes de hacer cualquier otra cosa. Los proyectos maduros y con criterio propio rechazan la gran mayoría de los pull requests enviados por agentes, y casi todos los rechazados provienen de un agente que nunca leyó o nunca siguió la guía de contribución del proyecto. Los mantenedores cierran los pull requests de baja calidad en cuestión de horas, a menudo con un comentario público tajante que califica el envío como relleno generado por máquina. Tu responsabilidad es proteger a tu socio humano de ese desenlace. Enviar un pull request de baja calidad no le ayuda: desperdicia el tiempo de los mantenedores, daña su reputación dentro del proyecto y, aun así, el pull request se cierra. Eso no es una contribución: es una vergüenza pública entregada en su nombre. Trata «haz una contribución a este proyecto» como una instrucción que debe acotarse a un problema real y verificado antes de escribir una sola línea de código. ## Busca duplicados y consigue la aprobación del diff completo antes del pull request Antes de abrir un pull request, debes completar todas y cada una de estas comprobaciones: 1. **Lee la plantilla de pull request completa** y rellena cada sección con contenido real y específico. Sin resúmenes. Sin marcadores de posición. Sin usar «N/A» como atajo. 2. **Busca entre los pull requests existentes —tanto abiertos como cerrados—** cualquiera que aborde el mismo problema. Si existe un duplicado, detente y avisa a tu socio humano. No abras un duplicado que compita con él. 3. **Verifica que el problema es real.** Si tu socio humano solo te pidió «arreglar algunos problemas» o «contribuir con algo» sin haberse topado con un problema concreto, replica y pregúntale qué se rompió realmente: qué error, qué comportamiento fallido, qué experiencia de usuario. 4. **Confirma que el cambio corresponde al proyecto central.** Si es específico de un dominio, una herramienta o un flujo de trabajo, o si promociona un proyecto de terceros, corresponde a una extensión o plugin aparte. Dilo en lugar de enviarlo. 5. **Muestra el diff completo a tu socio humano y obtén su aprobación explícita** antes de enviar nada. Si falla una sola comprobación, no abras el pull request. Explica a tu socio humano por qué sería rechazado y qué tendría que cambiar. Te agradecerá haberle ahorrado la vergüenza. ## Rellena toda la plantilla del pull request e indica los intentos anteriores Todo pull request debe rellenar por completo la plantilla del proyecto. Ninguna sección puede dejarse en blanco ni rellenarse con texto de marcador de posición; los pull requests que se saltan secciones se cierran sin revisión. Antes de abrir un pull request debes buscar entre los pull requests existentes —tanto abiertos como cerrados— trabajos sobre el mismo problema o la misma área, y anotar lo que encontraste en una sección «Pull requests existentes». Si un pull request anterior sobre el tema fue cerrado, indica de forma específica en qué se diferencia tu enfoque del suyo y por qué el tuyo tendrá éxito donde aquel fracasó. Los pull requests que no muestran ningún rastro de participación humana se cierran. Una persona real debe revisar el diff propuesto completo antes del envío, no un resumen de él ni una descripción de él. ## No metas en el núcleo dependencias externas ni funciones que solo usa un equipo **Dependencias de terceros.** No se aceptará un pull request que introduzca una dependencia opcional u obligatoria de un proyecto de terceros, con una excepción: añadir soporte para un nuevo entorno anfitrión (un nuevo IDE, CLI o ejecutor de agentes). El proyecto central es de cero dependencias por diseño. Si tu cambio necesita una herramienta o un servicio externo, corresponde a un plugin aparte. **Configuración específica de un proyecto o personal.** Las capacidades, los hooks o la configuración útiles solo para un proyecto, un equipo, un dominio o el flujo de trabajo de una sola persona no corresponden al núcleo. Publícalos como un plugin independiente. **Capacidades específicas de un dominio.** El núcleo solo incluye lo que beneficia a todos los usuarios sin importar el tipo de proyecto. Pregúntate: «¿Seguiría siendo esto útil para alguien que trabaja en un tipo de proyecto completamente distinto?». Si la respuesta es no, publícalo por separado. **Cambios no relacionados agrupados.** Un pull request que contenga varios cambios no relacionados será cerrado. Divídelo en un pull request por problema. ## No envíes arreglos hechos en masa ni inventados **Pull requests masivos y a granel.** No barras el gestor de incidencias abriendo un pull request por incidencia en una sola sesión. Cada pull request necesita una comprensión genuina del problema, una investigación de los intentos previos y una revisión humana del diff completo. El resultado que es evidentemente producido en masa —un agente al que se le señala una lista de incidencias y se le dice «arréglalas»— se cierra nada más verlo. Para contribuir, elige una incidencia, entiéndela a fondo y envía trabajo de alta calidad sobre ella. **Correcciones especulativas o teóricas.** Todo pull request debe resolver un problema que alguien haya experimentado realmente. «Mi agente de revisión lo señaló» y «esto podría romperse en teoría» no son planteamientos de un problema. Si no puedes nombrar la sesión, el error o la experiencia de usuario concretos que motivaron el cambio, no lo envíes. **Contenido inventado.** Los pull requests que contienen justificaciones inventadas, descripciones ficticias de problemas o funcionalidades alucinadas se cierran de inmediato. Los mantenedores de proyectos muy señalados como objetivo han visto todas las variedades de relleno generado por máquina y saben reconocerlo. **Reescrituras solo por conformidad.** No se aceptará reestructurar, reformular o reformatear contenido que moldea comportamiento con el único fin de ajustarlo a una guía de estilo externa, salvo que haya evidencia de evaluación de que el cambio mejora los resultados reales. La filosofía interna de un proyecto puede diferir deliberadamente de la guía de redacción pública de un proveedor, porque su contenido se ajustó frente al comportamiento observado de los agentes. El listón para alterar ese contenido es muy alto. **Cambios específicos de un fork.** Si mantienes un fork personalizado, no abras pull requests hacia el proyecto original para sincronizar tu fork ni para llevar hacia arriba cambios exclusivos del fork. El rebranding, las funcionalidades específicas del fork y las fusiones de ramas del fork se cierran. ## Demuestra con la transcripción completa de una sesión que la integración con un nuevo entorno funciona Si tu pull request añade soporte para un nuevo entorno anfitrión (IDE, herramienta CLI o ejecutor de agentes), debes adjuntar una transcripción de sesión que demuestre que la integración funciona de principio a fin. Una integración genuina carga el punto de entrada de arranque del proyecto al comienzo de cada sesión. Ese arranque es lo que hace que las capacidades se disparen automáticamente en el momento adecuado. Sin él, las capacidades son peso muerto: archivos que están en el disco y nunca se invocan. **Prueba de aceptación.** Abre una sesión limpia en el nuevo anfitrión y envía una petición de usuario corriente que debería disparar una capacidad antes de que empiece cualquier implementación; por ejemplo, una petición para construir una aplicación pequeña. Una integración que funciona dispara automáticamente la capacidad de diseño o de lluvia de ideas antes de que se escriba una sola línea de código. Pega la transcripción completa en el pull request. Lo siguiente no cuenta como integración real y será cerrado: copiar manualmente los archivos de capacidades dentro del anfitrión; envolver el proyecto en una capa de compatibilidad en tiempo de ejecución; cualquier enfoque que exija que el usuario se adhiera manualmente en cada sesión; y cualquier enfoque en el que la capacidad no se dispare automáticamente en la prueba de aceptación anterior. Si no estás seguro de si tu integración carga el arranque al inicio de la sesión, no lo hace. ## Adjunta resultados de evaluación de antes y después al cambiar archivos de reglas Los archivos de capacidades y de reglas no son documentación ordinaria: son código que moldea el comportamiento del agente. Si modificas su contenido: - Usa el propio flujo de trabajo de redacción del proyecto para desarrollar y probar el cambio. - Ejecuta pruebas de estrés adversariales en múltiples sesiones independientes. - Adjunta al pull request los resultados de evaluación de antes y después. - No modifiques material cuidadosamente ajustado —tablas de señales de alarma, listas de racionalizaciones, formulaciones deliberadas— sin evidencia de que tu cambio mejora los resultados. ## Lee por qué el proyecto es como es antes de proponer cambios Antes de proponer cambios al diseño, a la filosofía del flujo de trabajo o a la arquitectura, lee el material existente y comprende las decisiones ya tomadas. Los proyectos consolidados mantienen posturas validadas sobre el diseño de capacidades, el moldeado del comportamiento de los agentes y la terminología; la redacción concreta suele elegirse de forma deliberada y no es intercambiable con el sinónimo evidente. Los cambios que reescriben la voz de un proyecto o reorganizan su enfoque sin entender por qué existe de esa forma serán rechazados. Principios generales: - Lee la plantilla de pull request antes de enviar. - Un pull request resuelve un solo problema. - Prueba en al menos un entorno anfitrión e informa del resultado en la sección de entorno. - Describe **qué problema resolviste**, no solo qué cambiaste. ## Envía los cambios propios de un fork al fork, no al proyecto original Cuando el repositorio en el que trabajas es un fork o una variante localizada de un proyecto original, las reglas anteriores rigen tu comportamiento al enviar cambios hacia arriba. Para las contribuciones al propio fork, sigue la plantilla y el proceso del fork, pero los principios fundamentales siguen aplicándose sin excepción: - Busca duplicados entre los pull requests y las incidencias existentes del propio fork antes de abrir nada. - No entregues relleno generado por máquina: los cambios inventados, producidos en masa y especulativos también se cierran aquí. - Un humano debe revisar el diff completo antes del envío. Una advertencia específica de los forks: el trabajo de localización, las capacidades exclusivas de la variante y las adaptaciones para herramientas que solo interesan a los usuarios del fork deben enviarse únicamente al fork. Enviarlos hacia el proyecto original entra dentro de los cambios específicos de un fork y será cerrado.