La habilidad /to-spec

Fuente: The /to-spec Skill — traducción comunitaria no oficial al español.

Qué hace

to-spec convierte la conversación que acabas de tener en una spec, y la publica en tu gestor de pendientes como un solo issue.

No te entrevista. Para cuando la usas la decisión ya está tomada, así que sintetiza lo conocido (del hilo, de la base de código, de tu CONTEXT.md y tus ADR) en lugar de abrir una nueva ronda de preguntas. La spec es un registro de decisiones ya tomadas, no un lugar donde se toman decisiones nuevas.

Cuándo usarla

La invocas escribiendo /to-spec; el agente no la usará por su cuenta.

Úsala cuando la construcción sea demasiado grande para una sola sesión de agente y tenga que sobrevivir repartida en varias. Ese es todo el disparador:

Dónde estás	Qué ejecutar
Aún no has decidido nada	grill-with-docs primero
Decidido, y el trabajo cabe en una ventana de contexto	implement: sáltate la spec
Decidido, y el trabajo abarca varias sesiones	/to-spec, luego to-tickets
Un mapa de wayfinder se ha despejado	/to-spec #<map_issue>

Requisitos previos

to-spec publica la spec como un issue, así que setup-matt-pocock-skills debe haber configurado primero un gestor y el vocabulario de etiquetas de triaje para este repositorio. Valen ambos tipos: un gestor real como GitHub, o archivos Markdown locales bajo .scratch/, que funciona sin configuración.

La spec es un registro de decisiones

La spec existe porque las ventanas de contexto terminan. Todo lo que acordaste mientras te interrogaban (la forma de la solución, las opciones que discutiste, lo que rechazaste deliberadamente) está en una conversación que está a punto de borrarse. La spec es lo que sobrevive a eso.

Así que no valida nada, y no decide nada. Captura lo decidido, en el vocabulario propio de tu proyecto, para que una sesión nueva pueda retomar el trabajo sin que lo reexpliques. Cualquier cosa que la spec afirme y que tú nunca dijiste es un defecto.

Costuras antes que prosa

Antes de escribir una palabra, to-spec esboza las costuras en las que se probará la funcionalidad, y las verifica contigo. Prefiere costuras que ya existen a las nuevas, y toma la más alta que pueda: el número ideal en un cambio es uno.

Esas costuras acordadas luego viajan. tdd solo trabaja en costuras preacordadas, y code-review revisa el diff contra la spec, así que una costura que nadie acordó aparece como un hallazgo de revisión. La vinculación es indirecta: pasa por este documento, que es justo por lo que la conversación de costuras vale la pena tomársela en serio aquí en lugar de diferirla a la implementación.

Preguntas comunes

¿A dónde se fue /to-prd? Es esta habilidad, renombrada en v1.1. “Spec” es ahora el único término transversal, y el antiguo slug to-prd está muerto; reinstala con el nuevo nombre. El par que reemplazó el vocabulario antiguo es spec y tickets: la spec es el destino y las decisiones que lo fijan, los tickets son los pasos de ejecución que llegan allí. Si pivotas, borra los tickets sin terminar y conserva la spec.

¿Por qué la spec recibe la etiqueta ready-for-agent? No quiero que un agente la implemente directamente. La etiqueta significa “no necesita más triaje”: el documento está lo bastante completo para que un agente trabaje desde él. Es una designación de entrada, no una orden de trabajo. Pero si ejecutas agentes AFK que rastrean ready-for-agent, esa distinción no es visible para ellos, y con gusto intentarán construir toda la spec en una ejecución en lugar de tomar los recortes de tickets. Este es el borde más áspero reportado de la habilidad. Hasta que cambie, excluye la spec padre explícitamente en el prompt de tu agente AFK, o quita la etiqueta una vez que /to-tickets haya corrido.

¿Por qué no ir directo del interrogatorio a /to-tickets y saltarse la spec? A menudo deberías; la spec solo gana su paso en trabajo multisesión. Donde paga es en que los tickets son desechables y la spec no: cada ticket tiene el tamaño de una ventana de contexto nueva y se borra o se cierra, mientras la spec queda como el único lugar donde vive el razonamiento detrás de ellos. En un cambio de una sola sesión eso no te compra nada, y has pagado un paso extra de síntesis donde el modelo puede derivar. Ve de interrogatorio → /implement.

Acabo de terminar un mapa de wayfinder. ¿Qué le paso? El issue principal del mapa: /to-spec #<map_issue>, no los tickets de decisión individuales. wayfinder produce decisiones en lugar de entregables, dispersas por un mapa; to-spec es el paso que las colapsa en un documento construible. Pasar el mapa directo a /implement desecha ese colapso.

¿La spec es para que yo la revise, o solo para el agente? Mayormente para el agente, y se lee así: completa, densa, cargada de referencias. Las partes que valen tus ojos son las costuras y la sección de fuera de alcance, porque esos son los dos lugares donde una decisión errónea es más barata de atrapar y más cara de descubrir después. Leerla entera de principio a fin es una queja real de la gente, y no hay modo resumen: la respuesta honesta es que si la spec te sorprende, el interrogatorio fue demasiado superficial, no la spec demasiado larga.

¿Mantengo la spec congelada una vez que empiezan los tickets, o dejo que el agente la reescriba? Nada la mantiene sincronizada, así que en la práctica es una instantánea de lo que sabías en ese momento, y se queda obsoleta la primera vez que la implementación te enseña algo. Trátala como desechable una vez que el trabajo se publica. Los artefactos destinados a sobrevivirla son tu CONTEXT.md y tus ADR; si algo aprendido durante la implementación merece durar, pertenece allí, no en una spec editada.

Mi trabajo es un refactor o un límite de módulo, no una funcionalidad. ¿Encaja la plantilla? Peor, y esta es una limitación conocida. La plantilla se apoya fuerte en historias de usuario, que es la forma equivocada para trabajo arquitectónico: terminas escribiendo historias que nadie pidió alrededor de decisiones que en realidad son sobre interfaces e invariantes. Apóyate en las secciones de decisiones de implementación y decisiones de pruebas, y deja que las decisiones arquitectónicas duraderas caigan como ADR vía grill-with-docs en lugar de intentar que la spec las cargue.

¿Revisará el gestor por trabajo relacionado, o citará los ADR que respeta? No a ambas. Lee y respeta los ADR que cubren el área que toca, pero no los enlaza, y no busca en el gestor issues solapados antes de redactar, así que una spec puede duplicar silenciosamente trabajo que alguien ya registró. Busca tú mismo primero en el gestor si el área está concurrida.

/to-tickets no pudo leer mi spec: se truncaba. Las specs muy grandes pueden superar lo que un issue del gestor devuelve limpio, y no hay copia local a la que recurrir. La solución es higiene de contexto: no hagas clear ni compact entre /to-spec y /to-tickets. Ejecútalos en la misma ventana y la spec nunca tiene que volver a recuperarse.

Funciona si

• Empieza a escribir en lugar de hacerte una nueva ronda de preguntas.
• Te presenta las costuras antes de escribir, y propone tan pocas como pueda.
• Vuelve en los sustantivos de tu proyecto, no en plantilla genérica de gestión de producto.
• Cada decisión en ella es una que recuerdas haber tomado. Nada fue inventado para rellenar una sección.
• La sección de fuera de alcance tiene cosas reales: las cosas que rechazaste suelen ser las líneas más útiles de la página.

Dónde encaja

to-spec es un paso en la cadena principal de construcción, y solo en la rama multisesión de ella:

grill-with-docs → to-spec → to-tickets → implement → code-review

Sus vecinos aguas arriba son grill-with-docs, que hace la definición que esta habilidad solo registra, y wayfinder, cuyo mapa terminado se fusiona a la cadena justo aquí. Aguas abajo, to-tickets corta la spec en tickets bala trazadora para que implement los construya. Cuando no sepas qué habilidad o flujo encaja, ask-matt te dirige.