pr y wizard: pull requests que se entienden de un vistazo y asistentes para los pasos que solo tú puedes dar

Un agente puede escribir el código, pero hay dos momentos en los que necesita a una persona. Uno es la revisión: alguien tiene que leer el pull request y decidir si se fusiona. El otro son los pasos que solo un humano puede dar: crear la cuenta en un proveedor, copiar una clave de un panel, configurar un secreto en GitHub. pr y wizard son las skills de Matt Pocock para esos dos momentos: una da al PR la forma que un humano lee más rápido, y la otra convierte los pasos manuales en un asistente de terminal que se ejecuta una vez y no se vuelve a explicar.

Es la duodécima parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT). Las dos las invoca el modelo cuando la tarea encaja.

pr: la forma de un buen pull request

pr se activa cada vez que el agente escribe la descripción de un PR. Da una plantilla con tres secciones y una regla general: sin preámbulos, prosa breve y el vocabulario del GLOSSARY.md.

## Summary

<diagrama, diff-sketch o árbol>

## Evidence

- **Before:** <captura / salida / test fallando>
  **After:** <captura / salida / test pasando>

## Merge Danger

**Door:** <one-way o two-way>

**Blast Radius:** <una palabra>

Summary: la vista más pequeña que lo deja claro

En lugar de párrafos, el resumen elige la representación más pequeña que muestra el cambio. La skill da un menú (tomado de la skill show-me de Dex Horthy, de HumanLayer, con atribución en CREDITS.md):

• Pseudocódigo para lógica o algoritmos.
• Árbol de llamadas para el flujo en tiempo de ejecución.
• Árbol de componentes para la estructura de la interfaz.
• Árbol de ficheros para responsabilidades o un refactor amplio.
• Mermaid para interacción entre componentes o flujo de datos.
• Un diff del dibujo, no del código, cuando lo importante es qué cambia sobre una forma que ya existe:

 on(save)
-  write content
+  if content is unchanged
+    return cached result
+  write new content
+  invalidate cache

Se puede usar uno o varios, "es poco probable que uses todos". La consigna es incluir solo las llamadas, ficheros y estados necesarios para la pregunta que tiene el revisor.

Evidence: antes y después

Pruebas concretas de que funciona. Las capturas son "nivel S" si el cambio es visual y el entorno lo permite. La evidencia de ejecución (resultados de tests, salida de consola) es "nivel A": el test exacto que antes fallaba y ahora pasa.

Merge Danger: puerta de una o dos direcciones

• Puerta de dos direcciones: se puede deshacer con un revert barato. Riesgo bajo.
• Puerta de una dirección: acciones destructivas o decisiones difíciles de revertir (borrar datos, migraciones, cambios de contrato público).

Y el radio de impacto (*blast radius*) en una palabra, con sus posibles consecuencias: saltos de maquetación, roturas para quien consume la API, responsive en móvil...

wizard: un asistente de terminal para pasos humanos

Hay procedimientos que son tediosos de hacer a mano y tediosos de volver a explicarle a una IA cada vez: dar de alta un proveedor, generar claves, configurar secretos de CI, una migración puntual. wizard genera un script bash interactivo que guía a la persona paso a paso: abre cada URL, dice exactamente qué pulsar y copiar, captura los valores, los escribe donde corresponde (.env, secretos de GitHub), pide confirmación en cada fase y muestra cuántas quedan.

La skill es explícita: no se usa para pasos que el agente puede hacer solo. Es para cuando hay un humano de verdad en el bucle.

La plantilla ya resuelve la experiencia

La skill trae template.sh con una biblioteca que nunca se edita a mano: progreso por fases, puertas de confirmación, apertura de URLs multiplataforma (incluido WSL), entrada oculta para secretos, escritura idempotente en .env, gh secret y gh variable, y un resumen final. El agente solo escribe las fases debajo del marcador STAGES, con estas funciones:

La fase de ejemplo de la propia plantilla, para claves de Stripe:

stage "Stripe: API keys"
say "We'll grab your Stripe test keys and store them for local dev + CI."
open_url "https://dashboard.stripe.com/test/apikeys"
step "On the API keys page, copy the Publishable key (starts pk_test_)."
ask STRIPE_PUBLISHABLE_KEY "Paste the publishable key:"
ask_secret STRIPE_SECRET_KEY "Paste the secret key:"
write_env STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"
set_secret STRIPE_SECRET_KEY "$STRIPE_SECRET_KEY"

El proceso

1. Delimitar el procedimiento: leer .env, .env.example, el README, docker-compose* y .github/workflows/* (cada secrets.* o vars.* es un valor que el asistente debe producir). Te enseña las fases y los valores, y confirmas.
2. Trazar el recorrido de cada fase: qué URL, qué hacer allí, dónde aparece el valor. Si no conoce la interfaz actual de un panel, debe decirlo y preguntarte o consultar la documentación: nunca inventar pasos.
3. Escribir el asistente a partir de la plantilla, una fase por paso y en orden de dependencias.
4. Verificar: bash -n, shellcheck si está disponible y chmod +x. No lo ejecuta de principio a fin (abre navegadores y espera a una persona); lo revisa en estático: que cada valor acabe donde debe y que cada set_secret coincida con un secrets.* del CI.

Por defecto es efímero: se usa una vez y se borra. Si es un camino de configuración repetible, se hace commit y se enlaza desde el README.

Cómo se combinan

Las dos son la cara humana del final del flujo. Un ejemplo con la newsletter de la parte 5:

1. implement construye el ticket "Envío de números aprobados".
2. El código necesita una clave del proveedor de correo, registros DNS y un secreto en GitHub Actions. El agente no puede entrar en tu panel, así que wizard genera scripts/setup-newsletter.sh con tres fases: crear la clave, añadir los registros DNS (con confirm antes de seguir) y guardar la clave en .env y en los secretos de GitHub.
3. pr escribe el PR: un árbol de llamadas del cron de envío, la salida del test de idempotencia antes y después, y puerta de dos direcciones con radio de impacto "suscriptores", porque un fallo enviaría correos a gente real.
4. El revisor ve en la descripción que el siguiente paso es ejecutar el asistente, no una lista de instrucciones sueltas.

Errores frecuentes

• Resúmenes en prosa. Si el cambio cabe en un árbol de cinco líneas, tres párrafos son ruido.
• "Funciona en mi máquina" como evidencia. La skill pide el antes y el después concretos.
• Marcar todo como puerta de dos direcciones. Una migración que borra columnas no se deshace con un revert.
• Editar la biblioteca de template.sh. La coherencia entre asistentes es justo lo que aporta.
• Dejar que el asistente invente menús. Si el agente no conoce el panel, que lo diga.

Preguntas frecuentes

¿wizard necesita el CLI de GitHub? Solo para set_secret y set_var, que usan gh secret y gh variable.

¿Funciona en Windows? El script es bash: en Windows, con WSL o Git Bash. La apertura de URLs contempla WSL.

¿pr abre el PR por mí? No: define la forma de la descripción. Crear el PR depende de tu agente o de implement-spec.

Siguiente paso

Pide a tu agente que reescriba la descripción de tu último PR con la plantilla de pr y compara cuánto tardas en entenderlo. En la parte 13 de la guía vemos retro y writing-for-agents, la pareja que mejora el entorno del agente después de cada sesión.