to-spec y to-tickets: specs y tickets para agentes

Después de una sesión de grill-me o grill-with-docs tienes algo muy valioso: un diseño razonado. Pero vive en la conversación, y la conversación se pierde en cuanto limpias el contexto. to-spec y to-tickets son la pareja que lo convierte en trabajo ejecutable: un spec publicado en tu issue tracker y una lista de tickets con sus dependencias, cada uno del tamaño justo para que un agente lo termine en una sesión.

Es la quinta parte de la guía de las skills de Matt Pocock (repositorio mattpocock/skills, licencia MIT).

Cuándo necesitas esta pareja

ask-matt, el router del repositorio, lo plantea como una bifurcación después del interrogatorio:

¿El trabajo cabe en una sesión? Pasa directamente a /implement en la misma ventana de contexto.
¿Es un desarrollo de varias sesiones? /to-spec y después /to-tickets.

Un detalle importante: mantén el interrogatorio, el spec y los tickets en la misma ventana de contexto. No compactes hasta después de to-tickets, porque cada paso necesita el razonamiento literal del anterior, no un resumen.

Ambas skills necesitan saber dónde está tu issue tracker. Si no ejecutaste /setup-matt-pocock-skills, te lo pedirán.

Flujo de to-spec y to-tickets: conversación de grill-with-docs, spec publicado en el issue tracker y tickets verticales con dependencias — De la conversación al spec y del spec a un grafo de tickets · codigoagente

to-spec: sintetizar, no entrevistar

La primera regla de to-spec es lo que no hace: "No entrevistes al usuario; sintetiza lo que ya sabes". El interrogatorio ya pasó; ahora toca escribir.

Su proceso en tres pasos

Explorar el repositorio, si no lo hizo ya, usando el vocabulario de GLOSSARY.md y respetando los ADR del área que toca.
Proponer las costuras de test (*seams*): los puntos públicos donde se comprobará la funcionalidad. Prefiere las que ya existen, lo más arriba posible, y cuantas menos mejor: "el número ideal es una". Este es el único punto donde te pide confirmación.
Escribir el spec con su plantilla y publicarlo en el issue tracker con la etiqueta ready-for-agent, sin pasar por triage.

Las secciones del spec

Sección	Qué contiene
Problem Statement	El problema desde el punto de vista del usuario
Solution	La solución, también desde el usuario
User Stories	Una lista larga y numerada: "Como <actor>, quiero <función>, para <beneficio>"
Implementation Decisions	Módulos, interfaces, esquemas, contratos de API, decisiones de arquitectura
Testing Decisions	Qué es un buen test, qué módulos se prueban, tests parecidos que ya existen
Out of Scope	Lo que queda fuera
Further Notes	Lo demás

Una regla que merece copiarse: ni rutas de fichero ni fragmentos de código, porque caducan rápido. La única excepción es un fragmento que salió de un prototipo y expresa una decisión mejor que la prosa (una máquina de estados, un tipo, un esquema).

to-tickets: rebanadas verticales con dependencias

to-tickets parte el spec (o un plan, o la conversación) en tickets tipo "bala trazadora". La idea viene de *The Pragmatic Programmer*: en lugar de construir capa a capa, cada ticket atraviesa todas las capas de forma estrecha pero completa.

Las reglas de una rebanada vertical

Recorre todas las capas: esquema, API, interfaz y tests. Nunca una capa sola.
Al terminarla, se puede demostrar o verificar por sí misma.
Cabe en una ventana de contexto limpia.
Si hace falta refactorizar antes, ese ticket va primero: "haz que el cambio sea fácil, y luego haz el cambio fácil".

Cada ticket declara sus dependencias (*blocking edges*): qué otros tickets deben terminar antes. Un ticket sin dependencias puede empezar ya. El conjunto de tickets listos en cada momento es la frontera, la misma idea que en grill-me.

La excepción: refactors anchos

Renombrar una columna o cambiar el tipo de algo compartido rompe miles de llamadas a la vez y no admite rebanadas verticales. Para eso la skill usa expandir-contraer:

Expandir: añadir la forma nueva junto a la vieja, sin romper nada.
Migrar las llamadas por lotes (por paquete o directorio), cada lote su ticket, con CI en verde porque la forma vieja sigue existiendo.
Contraer: borrar la forma vieja cuando ya nadie la usa.

Te consulta antes de publicar

Antes de crear nada, te enseña la lista numerada con título, dependencias y qué entrega cada ticket, y pregunta si la granularidad es correcta, si las dependencias son reales y si algún ticket se debe unir o partir. Itera hasta que lo apruebas.

Dónde quedan los tickets

Markdown local: un fichero por ticket en .scratch/<feature>/issues/01-slug.md, 02-slug.md..., numerados con las dependencias primero.
GitHub, GitLab u otro tracker: un issue por ticket con la relación de bloqueo nativa de la plataforma y la etiqueta ready-for-agent. Si el origen era un issue, los tickets quedan como sub-issues.

La plantilla de un ticket local:

snippettext

# 02: Enviar el borrador semanal para revisión

**What to build:** el domingo se genera el borrador con los productos nuevos y las ofertas activas, y el administrador recibe un email para revisarlo.

**Blocked by:** 01

**Status:** ready-for-agent

- [ ] El borrador incluye solo productos publicados con stock
- [ ] Sin novedades no se genera borrador y se avisa al administrador

Ejemplo: la newsletter de grill-me convertida en tickets

Tomamos el diseño que cerramos en la sesión real de grill-me (newsletter semanal de una tienda de bicicletas con revisión manual) y aplicamos las reglas de to-tickets a mano para ver la forma que tendría. Es un ejemplo ilustrativo, no una salida de la skill:

#	Ticket	Bloqueado por	Qué entrega
01	Alta con doble opt-in	Ninguno	Formulario en el pie, email de confirmación y suscriptor activo al confirmar
02	Borrador semanal	01	Cron del domingo que genera el borrador y avisa al administrador
03	Revisión y aprobación	02	Página de administración con vista previa, prueba y botón "Aprobar" que congela el contenido
04	Envío de números aprobados	03	Cron cada 15 minutos que envía por lotes con idempotencia
05	Baja y supresión	01	Enlace de baja de un clic, `List-Unsubscribe` y webhook de rebotes

Fíjate en dos cosas. Ningún ticket es "crear las tablas" ni "hacer el frontend": cada uno es un recorrido completo que se puede probar. Y el 05 solo depende del 01, así que puede avanzar en paralelo con el 02, el 03 y el 04.

Errores frecuentes

Pedir a to-spec que pregunte más. No lo hará: si faltan decisiones, vuelve a grill-with-docs.
Compactar entre to-spec y to-tickets. Los tickets saldrán con menos matices que el spec.
Tickets horizontales. "Backend de la newsletter" y "frontend de la newsletter" no se pueden verificar por separado.
Dependencias de más. Si todos los tickets dependen del anterior, pierdes el paralelismo. Revisa cada dependencia en la consulta previa.
Pasar los tickets por /triage. Ya salen listos para un agente. Triage es para issues que llegan de fuera.

Preguntas frecuentes

¿Puedo usar to-tickets sin to-spec? Sí. Acepta un plan, un spec, la conversación actual o la referencia a un issue.

¿Funciona con Jira o Linear? Sí, si los describiste en /setup-matt-pocock-skills. Usa la relación de bloqueo nativa cuando existe.

¿Qué tamaño tiene un ticket? El que cabe en una ventana de contexto limpia. Si un ticket necesita compactar a mitad, era demasiado grande.

Siguiente paso

Lanza /to-spec justo después de tu próximo grill-with-docs y deja que /to-tickets lo parta. En la parte 6 de la guía vemos cómo se construye cada ticket con tdd y cómo se arreglan los fallos difíciles con diagnosing-bugs.