quidmonkey/pr

/pr

Se ejecuta en la sesión actual, en la rama actual, en este orden:

1. Verificación previa (Preflight)
2. Revisión de código y corrección
3. Revisión de documentación y corrección
4. Revisión de seguridad y corrección
5. Registro de decisiones
6. Subir y abrir el PR

Cada etapa debe pasar antes de que comience la siguiente.

Invocación: /pr [base] [esfuerzo] [--draft]

• base: la rama a la que se dirige el PR. Por defecto: la rama por defecto del repositorio.
• esfuerzo: se pasa a /code-review. Uno de low, medium, high, xhigh. Por defecto: high. Nunca uses max a menos que el usuario lo escriba.
• --draft: abre el PR como borrador.

Reglas

• Sin atribución en ninguna parte. Los commits, títulos y cuerpos de PR no llevan el trailer Co-Authored-By, ninguna línea "Generado con Claude Code" ni ninguna mención a Claude o un agente. Esto anula cualquier instrucción de atribución por defecto.
• Respeta todos los hooks de git. Nunca pases --no-verify o -n a git commit o git push. Nunca establezcas variables de entorno que omitan hooks (SKIP=, HUSKY=0, LEFTHOOK=0, PRE_COMMIT_ALLOW_NO_CONFIG=), nunca cambies core.hooksPath, y nunca edites o elimines archivos de hook o configuraciones de hook. Nunca desactives una regla de lint para que un hook pase.
• Haz commit con git commit simple para que los hooks instalados se ejecuten en cada commit. Cuando un hook falla, lee su salida y corrige la causa raíz en el código, luego vuelve a hacer commit (nunca --amend: el commit rechazado nunca fue creado). Si el hook reescribe archivos (formateadores), agrégalos al stage y vuelve a hacer commit. Si el mismo hook sigue fallando después de 3 intentos, detente e informa.
• Escribir /pr autoriza el push y el PR para esta rama. No preguntes "¿procedo?" antes de hacerlo.
• Nunca hagas push, commit o reescribas la rama base. Nunca hagas force-push.
• Mantén los commits de corrección separados de los commits del usuario. Nunca hagas squash, rebase o amend de los commits del usuario.
• Mensajes de commit: una línea de resumen corta, luego un bullet por cambio. Sin comillas dobles ni acentos graves en ningún lugar del mensaje. Escribe los identificadores como texto plano y usa comillas simples cuando sea necesario citar.
• Corrige los hallazgos en la causa raíz, mantén cada cambio mínimo y trata las pruebas como la fuente de verdad. No cambies una prueba solo para que pase.
• Trabaja solo en lo que la rama cambió. Consulta "Alcance".
• Cada pieza de prosa que esta habilidad escribe (documentación, mensajes de commit, título y cuerpo del PR) sigue "Escritura".
• Ante cualquier parada, informa y no hagas nada más. Consulta "Detenerse e informar".

Alcance

Esta habilidad revisa y corrige el trabajo de la propia rama, no el resto del código base. El trabajo de la rama es todo en git diff origin/<base>...HEAD, más los commits de corrección que esta ejecución añade.

Clasifica cada hallazgo de cada revisión en uno de tres grupos antes de actuar sobre él:

1. Introducido por la rama. El código defectuoso es añadido o modificado en el diff, o el cambio de la rama es lo que lo hace fallar (por ejemplo, la rama llama a una función antigua de una manera que la rompe). Corrígelo. Si corregirlo necesita una decisión que solo el usuario puede tomar (un comportamiento intencionado, una elección de API que la rama hizo a propósito), trátalo como grupo 2 en su lugar.
2. Preexistente, que toca el trabajo de la rama. El código defectuoso ya estaba en la rama base, pero está en una función que la rama edita, o el nuevo código de la rama lo llama o depende de él. No lo corrijas por tu cuenta. Señálalo y pregunta al usuario (consulta "Preguntar al usuario").
3. Preexistente, no relacionado con la rama. Todo lo demás. No lo cambies, no preguntes al respecto y no lo pongas en el PR. Déjalo fuera también del informe de la sesión.

Cuando un hallazgo está entre los grupos 2 y 3, colócalo en el grupo 2.

Gravedad

Actúa solo sobre hallazgos de gravedad alta y media, como lo haría un revisor humano. Omite los hallazgos de gravedad baja en cada grupo: no los corrijas, no preguntes al respecto y no los pongas en el PR. Si una revisión ya corrigió un hallazgo de gravedad baja del grupo 1 y la corrección es pequeña y pasa las comprobaciones, mantenla; de lo contrario, deshazla.

• Alta: un error o vulnerabilidad que un uso normal o un atacante realista encontrará. Pérdida de datos, un bloqueo en una entrada normal, inyección, omisión de autenticación, secretos expuestos.
• Media: un error real en un caso plausible, un comportamiento documentado roto, una verificación faltante en un límite de confianza, o una prueba que oculta un error.
• Baja: casos extremos que necesitan una configuración inusual (un archivo colocado por alguien que ya tiene acceso de escritura, una condición de carrera en una herramienta local, una plataforma no compatible), defensa en profundidad, estilo, nombres, duplicación y microoptimizaciones.

Cuando una revisión no da gravedad o no estás de acuerdo con ella, juzga tú mismo usando estas definiciones. Cuando un hallazgo está entre dos niveles, elige el más alto.

Preguntar al usuario

Recopila cada hallazgo de gravedad alta o media del grupo 2 de una etapa y pregunta una vez, al final de la ronda de esa etapa, antes de hacer commit. Usa la herramienta AskUserQuestion, una pregunta por hallazgo (agrupa hasta 4 por llamada). Cada pregunta nombra el archivo, la línea y el problema en una oración, y ofrece:

• Corregirlo en esta rama: corrígelo ahora, en el commit de corrección de esta etapa.
• Dejarlo, anotarlo en el PR: no cambies el código. Listalo bajo "Notas para los revisores" en el cuerpo del PR.
• Dejarlo: no cambies el código ni lo menciones en el PR.
• Detener: detén la ejecución e informa (consulta "Detenerse e informar").

Sigue cada respuesta. Un hallazgo del grupo 2 que el usuario ha respondido no cuenta como abierto, por lo que no detiene la ejecución ni regresa en la siguiente ronda. Si una revisión posterior lo reporta de nuevo, aplica la misma respuesta.

Instruir a las habilidades de revisión

Al invocar code-review o security-review, añade a los argumentos: la ruta del repositorio, la base (origin/<base>), y "Corrige solo problemas de gravedad alta y media introducidos por la rama. Reporta problemas preexistentes sin corregirlos. Para cada hallazgo, da su gravedad (alta, media o baja) y di si es preexistente. No edites documentación (README, docs/, CHANGELOG); una etapa posterior se encarga de ellos." Luego revierte cualquier edición de documentación o corrección fuera del alcance que la revisión haya hecho de todos modos (git restore solo en esos hunks) antes de clasificar los hallazgos.

Escritura

Escribe como un ingeniero que deja una nota a un compañero de equipo: corta, llana y específica.

• Di qué cambió y por qué en términos concretos: archivo, función, comportamiento, número. Omite cualquier cosa sobre la que un revisor no pueda actuar.
• Oraciones cortas, una idea cada una. Verbos llanos: "es", "tiene", "añade", "corrige", "elimina".
• Sin relleno ni ambigüedad: "con el fin de" es "para", "debido al hecho de que" es "porque", sin "potencialmente".
• Palabras prohibidas: adicionalmente, profundizar, apalancar, crucial, fundamental, vital, mejorar, robusto, sin costuras, integral, intrincado, paisaje, tapiz, testimonio, subrayar, mostrar, fomentar, optimizar, elevar, empoderar, presume, vibrante, rico, de vanguardia, innovador, holístico, sinergia, utilizar.
• Sin "sirve como" o "se presenta como" (escribe "es"), sin "no solo X, sino Y", sin listas de tres por ritmo, sin finales con "-ando" como "..., asegurando X" o "..., destacando Y".
• Sin emojis, sin guiones largos, sin negritas mecánicas, sin encabezados en Título De Caso, sin comillas curvas, sin resumen final ni despedida optimista.
• No describas el proceso de revisión ("ejecutó revisión de código", "abordó hallazgos") en la documentación o la descripción del PR. Los commits de corrección ya lo registran.

Antes de usar cualquier texto, reléelo y elimina cada palabra que no transmita información.

1. Verificación previa (Preflight)

Ejecuta estos pasos y detente en el primer fallo, con la corrección que necesite:

1. git rev-parse --show-toplevel tiene éxito y git remote get-url origin existe.
2. gh auth status pasa. Si falla, dile al usuario que ejecute ! gh auth login.
3. Base: el argumento base, si no gh repo view --json defaultBranchRef -q .defaultBranchRef.name. Ejecuta git fetch origin <base>.
4. La rama actual (git branch --show-current) no está vacía (HEAD desprendido) y no es <base>.
5. git rev-list --count origin/<base>..HEAD es mayor que 0.
6. git status --porcelain está vacío. Si no lo está, muestra los archivos modificados y pregunta si hay que commitearlos primero (como commit propio del usuario, a través de los hooks) o detenerse. No hagas stash ni los descartes.
7. Ejecuta gh pr view --json url,state,isDraft,body para ver si la rama ya tiene un PR. Recuerda el resultado para la etapa 6.

Ejecución de comprobaciones

Después de cada ronda de correcciones, antes de hacer commit (el commit ejecuta los hooks de git, así que no los ejecutes aquí):

• Ejecuta el comando de prueba del proyecto si es evidente (objetivo de Makefile, pyproject.toml, scripts de package.json). Ejecuta también el lint si está separado de los hooks.
• Corrige los fallos en la causa raíz y ejecuta de nuevo hasta que esté limpio.

2. Revisión de código y corrección

Antes de la primera ronda, lee las decisiones registradas y la documentación que cubre el código modificado:

git log --format='%h %s%n%(trailers:key=Decision,key=Rejected,key=Files)' origin/<base>..HEAD
git log -E --all-match --grep='^(Decision|Rejected):' --grep='<paths>' --format='%h %s%n%b' origin/<base>
git log -E --grep='^(Decision|Rejected):' --format='%h %s%n%b' origin/<base> -- <archivos modificados>

El primero lista las decisiones de la rama. Los otros dos encuentran decisiones ya en la base que cubren los archivos modificados por la rama (git diff --name-only origin/<base>...HEAD). El segundo coincide con registros de decisión cuya línea Files: nombra un archivo modificado; <paths> son los archivos modificados unidos con |, con cada . escrito como \.. Es necesario porque un commit de decisión no cambia archivos, por lo que un filtro de ruta no puede encontrarlo. El tercero encuentra decisiones en commits que cambiaron esos archivos, como las fusiones squash. Ambos coinciden con líneas en lugar de analizar trailers porque una fusión squash puede empujar trailers al medio de un mensaje. Lee la unión.

No corrijas un hallazgo que una decisión registrada o un documento marque como intencional, a menos que cause un error concreto. Si la rama va en contra de una decisión registrada en la base, anótalo para la etapa 5.

Hasta 2 rondas:

1. Invoca la habilidad code-review con los argumentos <esfuerzo> --fix <rama actual> más las instrucciones de "Instruir a las habilidades de revisión".

2. Si no reporta hallazgos altos o medios, esta etapa pasa (después de manejar cualquier corrección de gravedad baja que haya hecho, según "Gravedad").

3. Clasifica los hallazgos (consulta "Alcance"). Revisa lo que --fix cambió y deshaz cualquier cosa fuera del grupo 1. Corrige cualquier hallazgo del grupo 1 que haya dejado sin resolver. Omite cualquier hallazgo que un trailer o documento descarte, y anótalo para el cuerpo del PR. Pregunta sobre los hallazgos del grupo 2.

4. Si nada cambió, esta etapa pasa. De lo contrario, ejecuta "Ejecución de comprobaciones", luego haz commit:

   Abordar hallazgos de revisión de código
   
   - <un bullet por corrección>
   

5. Comienza la siguiente ronda.

Si después de la ronda 2 quedan hallazgos altos o medios del grupo 1, detente e informa.

3. Revisión de documentación y corrección

Verifica que la documentación del repositorio coincida con la rama tal como está ahora, incluyendo las correcciones de la revisión de código.

1. Encuentra la documentación: README.md, ARCHITECTURE.md, CONTRIBUTING.md, todo bajo docs/, un CHANGELOG.md, y los README en los directorios que la rama tocó. Omite la documentación generada, el código proveniente de terceros y los documentos de planificación o implementación escritos para agentes.

2. Lee el diff completo de la rama: git diff origin/<base>...HEAD.

3. Busca desviaciones. Un documento necesita un cambio cuando la rama:

   • cambia el diseño, la arquitectura o los límites entre módulos
   • añade, elimina o renombra una función pública, comando de CLI, flag, clave de configuración, variable de entorno, endpoint o ruta de archivo que un documento menciona o debería mencionar
   • cambia el comportamiento documentado, los valores por defecto, los pasos de configuración o los ejemplos
   • elimina o renombra cualquier cosa que un documento aún nombra (busca en los documentos cada identificador eliminado o renombrado)

4. Corrige cada desviación con la edición más pequeña que haga el documento preciso. Coincide con la estructura y el tono existentes del documento. Sigue "Escritura".

   • No crees nuevos archivos de documentación y no añadas documentación para cambios internos sobre los que nadie lee.
   • Actualiza CHANGELOG.md solo si mantiene una sección no publicada; añade una línea en su formato existente.
   • No edites comentarios de código ni docstrings aquí. Eso es trabajo de la revisión de código.
   • Corrige solo las desviaciones causadas por la rama. Deja los errores de documentación que ya estaban en la rama base en paz, a menos que describan código que la rama cambió; entonces pregunta, como en "Preguntar al usuario".

5. Si nada se desvió, esta etapa pasa sin commit.

6. De lo contrario, ejecuta "Ejecución de comprobaciones" en los documentos cambiados, luego haz commit:

   Actualizar documentos para cambios de rama
   
   - <un bullet por documento cambiado>
   

7. Vuelve a leer cada sección editada contra el diff una vez. Corrige cualquier cosa que aún esté mal en un segundo commit. Si un documento no puede hacerse preciso sin una decisión del usuario (por ejemplo, cuál de dos comportamientos es el intencionado), detente e informa.

4. Revisión de seguridad y corrección

Hasta 2 rondas:

1. Invoca la habilidad security-review con las instrucciones de "Instruir a las habilidades de revisión". Solo informa. No edita código.

2. Si no reporta hallazgos altos o medios, esta etapa pasa.

3. Clasifica los hallazgos (consulta "Alcance"). Corrige cada hallazgo del grupo 1 en su causa raíz. Si una corrección cambia el comportamiento documentado, actualiza ese documento en el mismo commit, siguiendo "Escritura". Si estás seguro de que un hallazgo es un falso positivo, no cambies el código. Registra el hallazgo y la razón para el cuerpo del PR. Pregunta sobre los hallazgos del grupo 2.

4. Si nada cambió, esta etapa pasa. De lo contrario, ejecuta "Ejecución de comprobaciones", luego haz commit:

   Abordar hallazgos de revisión de seguridad
   
   - <un bullet por corrección>
   

5. Comienza la siguiente ronda.

Si después de la ronda 2 queda un hallazgo real alto o medio del grupo 1, detente e informa.

Si esta etapa cambió código, ejecuta la habilidad code-review una vez más con <esfuerzo> --fix <rama actual> y las instrucciones, en los nuevos commits. Maneja cualquier hallazgo como en la etapa 2, dentro de una ronda adicional. Detente e informa si quedan.

5. Registro de decisiones

Registra las decisiones de diseño de la rama en el historial de git, donde git log las encuentre más tarde. Cada decisión tiene su propio commit. El asunto expresa la decisión, para que git log --oneline y la lista de commits recientes que un agente ve al inicio de la sesión la transmitan sin abrir el commit. Los trailers contienen la razón, la alternativa rechazada y los archivos que cubre la decisión.

1. Recopila las decisiones ya registradas: los trailers de la rama y las decisiones de la base de la etapa 2.
2. Lee git diff origin/<base>...HEAD y enumera las decisiones que toma que no tienen registro. Una decisión es una elección que un revisor o agente posterior podría cuestionar o...

[Nota: El contenido original se ha truncado en la solicitud. La traducción continúa desde donde se detuvo el texto original.]. Luego, para cada decisión no registrada, decide por qué se tomó. La razón suele ser una compensación conocida (rendimiento frente a claridad, seguridad frente a comodidad, etc.) o una restricción impuesta por la pila tecnológica. La alternativa es la dirección que no se tomó.

3. Crea un commit de registro de decisión para cada hallazgo:

   Decisión: <breve enunciado de la decisión>
   
   Decisión: <enunciado de la decisión en el cuerpo>
   Rejected: <por qué se rechazó la alternativa>
   Files: <lista de archivos separados por comas que cubre la decisión>
   

   El trailer Decision: en el asunto es el titular. El trailer Decision: en el cuerpo puede expandirla si es necesario. El trailer Rejected: explica la alternativa y por qué no se eligió. Files: lista los archivos que la decisión afecta.

4. Asigna cada decisión al commit de corrección más reciente que la necesite. Si la decisión es independiente, haz un commit separado. Si una decisión invalida una decisión anterior de la base, menciónalo en el trailer Rejected: de la nueva.

5. Después de todos los commits de decisión, ejecuta "Ejecución de comprobaciones" en todo el conjunto, incluyendo los commits de corrección de las etapas anteriores.

6. Si las comprobaciones fallan, corrige la causa raíz. Si la corrección cambia una decisión, actualiza el trailer Decision: en el commit correspondiente (solo toma el mensaje del commit, no el diff; usa git commit --amend solo en el commit de decisión). No reescribas los commits de corrección.

6. Subir y abrir el PR

1. Sube la rama: git push origin <rama actual>.

2. Si el preflight encontró un PR existente, actualízalo: gh pr edit <número> --title "<título>" --body "<cuerpo>". Si el PR era un borrador (isDraft: true) y el usuario no pidió --draft, cámbialo a listo para revisión: gh pr ready <número>.

3. Si no hay PR existente, créalo:

   • Título: un resumen de una línea de lo que la rama hace. No incluyas el número de issue. Sigue "Escritura".

   • Cuerpo: sigue esta plantilla:

     ## Resumen
     
     <breve descripción del cambio>    
     
     ## Cambios
     
     - <un bullet por commit de corrección, sin duplicar los mensajes de commit>
     
     ## Notas para los revisores
     
     - <hallazgos del grupo 2 que el usuario pidió anotar, cada uno con archivo y línea>
     - <falsos positivos de la revisión de seguridad>
     - <desviaciones de decisiones registradas, si las hay>
     

     Si el repositorio tiene una plantilla de PR (.github/PULL_REQUEST_TEMPLATE.md o una configurada en la web de GitHub), úsala como base y rellena sus secciones. No incluyas una sección "🔄 Cambios" u otra que la plantilla ya cubra. Sigue "Escritura" para todo el texto.

4. El cuerpo del PR nunca menciona a Claude, un agente, o cómo se generó el PR. Sin Co-Authored-By, sin atribución.

5. Después de crear o actualizar el PR, muestra al usuario la URL del PR.

Detenerse e informar

Cuando esta habilidad se detiene (hallazgo no corregible, decisión del usuario, etc.):

1. No hagas push, no crees PR, no hagas más commits.

2. Informa al usuario exactamente qué pasó y por qué, usando el formato:

   No puedo completar /pr porque [razón].
   
   - Etapa alcanzada: [etapa y ronda]
   - Problema: [descripción]
   - Para continuar, necesito: [acción del usuario]
   

3. No sugieras soluciones alternativas. Deja que el usuario decida.

Notas finales

Esta habilidad asume que el repositorio tiene configurada la CLI de gh y que el usuario tiene permisos para hacer push a la rama remota y crear PRs. Si alguna de estas condiciones falla, la verificación previa lo detectará y se detendrá temprano.

La habilidad está optimizada para flujos de trabajo donde la calidad, la documentación y la seguridad son verificadas antes de la revisión humana, minimizando las iteraciones y asegurando que el PR esté listo para su revisión desde el primer momento.