Razsk/VideoStudio

Pregunta a Matt

No recuerdas cada habilidad, así que pregunta.

Antes de afirmar lo que hace una habilidad o recomendar que se omita un paso, lee el SKILL.md de esa habilidad: los resúmenes aquí son solo para orientación.

Un flujo es un camino a través de las habilidades. La mayoría de los caminos recorren un flujo principal y dos rampas de acceso se fusionan en él. Todo lo demás es independiente, o una capa de vocabulario que se ejecuta subyacentemente.

El flujo principal: idea → envío

La ruta que recorre la mayor parte del trabajo. Tienes una idea y quieres que se construya.

1. /grill-with-docs afila la idea mediante una entrevista. Comienza aquí siempre que estés trabajando en un directorio de trabajo: tiene estado, reteniendo lo que aprende en GLOSSARY.md y ADR. (¿No tienes un directorio de trabajo? Usa /grill-me en su lugar, cubierto en Independiente. Ambos ejecutan la misma primitiva /grilling; grill-with-docs es el que deja un rastro documental, lo que lo convierte en la mejor opción cuando hay un repositorio donde dejarlo).

2. Rama: ¿puedes resolver todas las preguntas en la conversación? Si una pregunta necesita una respuesta ejecutable (estado, lógica de negocio, una interfaz de usuario que debes ver), desvía a través de un prototipo, puenteado por /handoff en ambas direcciones (un prototipo vive en su propio directorio, que es exactamente para lo que sirve /handoff; ver Límites de fase):

   • /handoff salida, luego abre una nueva sesión contra ese archivo,
   • /prototype para responder la pregunta con código desechable,
   • /handoff de regreso lo que aprendiste, y haz referencia a ello desde el hilo de la idea original.

3. Rama: ¿es una construcción de múltiples sesiones?

   • Sí → /to-spec (convierte el hilo en una especificación), luego /to-tickets para dividirlo en tickets de trazador, cada uno declarando sus bordes de bloqueo. Luego trabaja los tickets de una de dos maneras:
     • /implement por ticket, /clear el contexto entre cada uno. En un rastreador local, eso es un archivo por ticket bajo .scratch/<feature>/issues/, trabajados primero los bloqueadores a mano; en un rastreador real, los bordes se convierten en enlaces de bloqueo nativos, por lo que se puede tomar cualquier ticket cuyos bloqueadores estén listos. Cada ticket es autocontenido, por lo que el contexto del último es desechable.
     • /implement-spec para toda la especificación en una sola ejecución. Lee los tickets como un grafo de tareas, ejecuta subagentes implementadores a través de la frontera lista en paralelo, y aterriza todo en una rama de integración. Úsalo cuando prefieras orquestar la construcción en lugar de impulsar cada ticket tú mismo.
   • No → /implement aquí mismo, en la misma ventana de contexto.

   De cualquier manera, el código se construye impulsando /tdd (un slice rojo-verde a la vez) y se cierra con /code-review, una revisión de dos ejes (Estándares + Especificación) del diff. /implement ejecuta ambos por ticket; los implementadores de /implement-spec impulsan /tdd, y ejecuta una /code-review sobre la rama de integración. Recurre a /tdd por sí solo cuando solo quieras construir un comportamiento concreto con pruebas primero sin una especificación completa, y /code-review por sí solo cada vez que quieras revisar una rama o PR contra un punto fijo.

   Cuando el trabajo se presenta como una pull request, /pr da forma al cuerpo: el visual más pequeño que muestra el cambio, evidencia de antes/después de que funciona, y una llamada de puerta unidireccional o bidireccional. Es invocado por el modelo, por lo que el agente recurre a él cada vez que escribe un PR.

4. /retro cierra el ciclo. Después de una construcción, y especialmente de una que salió mal, revisa la sesión y sugiere cambios en el entorno del agente, no en el código: punteros de navegación, comprobaciones automatizadas, los estándares de codificación que /code-review aplica, archivos de dirección, herramientas. Los errores mecánicos se convierten en comprobaciones deterministas; los juicios se convierten en estándares de codificación. La siguiente construcción comienza entonces desde un mejor entorno.

Higiene del contexto

Mantén los pasos 1–3 en una ventana de contexto ininterrumpida (no compactes ni limpies hasta después de /to-tickets) para que la entrevista, la especificación y los tickets se construyan sobre el mismo pensamiento. Cada /implement comienza entonces fresco, trabajando desde el ticket. Ejecuta /retro en la sesión que está revisando, antes de limpiar; después de limpiar, apúntalo al registro de esa sesión.

El límite de esto es la zona inteligente: la ventana (~150k tokens en modelos de última generación) dentro de la cual el modelo aún razona con claridad. Si una sesión se acerca a ella antes de /to-tickets, no continúes degradado; /compact en el límite de fase más cercano y continúa (ver Límites de fase).

Rampas de acceso

Una situación inicial que genera trabajo, luego se fusiona en el flujo principal.

• Errores y solicitudes acumulándose → /triage. Mueve los issues a través de roles de triaje y produce issues listos para el agente, que /implement recoge más tarde.

  El triaje es solo para issues que no creaste tú: informes de errores, solicitudes de funciones entrantes, cualquier cosa que llegue en bruto. Los tickets que produjo /to-tickets ya están listos para el agente, así que no los triajes.

• Algo está roto → /diagnosing-bugs. Para los difíciles: el error que resiste una primera mirada, la falla intermitente, la regresión que se coló entre dos estados conocidos como buenos. Se niega a teorizar hasta que tenga un bucle de retroalimentación ajustado (un comando que ya se vuelve rojo en este error), luego arregla con una prueba de regresión. Una vez que la corrección está hecha, ejecuta /retro en la misma sesión para preguntar qué habría prevenido el error; cuando el hallazgo real es que no hay un buen punto de sutura para asegurarlo, ese es un trabajo para /improve-codebase-architecture.

• Un esfuerzo enorme y nebuloso: un proyecto greenfield o una construcción de funciones masiva, demasiado grande para una sesión → /wayfinder, el flujo más exigente cognitivamente aquí. Cuando el camino desde aquí hasta el destino aún no es visible, traza un mapa compartido de tickets de decisión en el rastreador de issues y los resuelve uno a la vez, produciendo decisiones, no entregables, hasta que la niebla se disipa y el camino está claro. Mientras que /grill-with-docs afila una idea que puedes mantener en una sesión, wayfinder es para la idea que no puedes, y es más lento y denso, así que guárdalo para exactamente eso, nunca para una función bien delimitada.

  Cuando el mapa se aclara, entrega, no construye: fusiónate en el flujo principal en /to-spec, que colapsa las decisiones vinculadas del mapa en un plan construible, luego /to-tickets e /implement como de costumbre. Pasar el mapa directamente a /implement omite ese colapso y tira el detalle vinculado, así que ve directamente a /implement solo cuando el esfuerzo resultó genuinamente pequeño.

Salud del código base

No es trabajo de funciones, solo mantenimiento.

• /improve-codebase-architecture se ejecuta cada vez que tengas un momento libre para mantener el código base en buen estado para que los agentes operen en él. Descubre oportunidades de profundización; elegir una genera una idea que puedes llevar al flujo principal en /grill-with-docs. Es el estudio que encuentra los candidatos; /codebase-design (abajo) es el banco en el que diseñas el elegido.

Vocabulario subyacente

Dos referencias invocadas por el modelo que se ejecutan debajo de las otras habilidades, cada una la única fuente de verdad para su vocabulario. Recurre a ellas directamente cuando las palabras, no el proceso, sean el problema; o deja que las habilidades anteriores las integren.

• /domain-modeling: afila el lenguaje de dominio del proyecto: desafía un término difuso, resuelve una palabra sobrecargada ("cuenta" haciendo tres trabajos), registra una decisión difícil de revertir como un ADR. Es la disciplina activa que /grill-with-docs impulsa para mantener GLOSSARY.md como un glosario limpio.
• /codebase-design es el vocabulario del módulo profundo (módulo, interfaz, profundidad, punto de sutura, adaptador, apalancamiento, localidad) para diseñar la forma de un módulo: mucho comportamiento detrás de una interfaz pequeña en un punto de sutura limpio. /tdd y /improve-codebase-architecture lo hablan.

Límites de fase

Una fase es un trozo de trabajo dentro de una sesión: la entrevista, la implementación, el QA. En el límite entre dos de ellas tienes cinco opciones, y elegir entre ellas es la decisión más difusa en todo este mapa:

• Continuar: quédate donde estás. No cuesta nada, no pierde nada.
• /clear: vacía la ventana, cuando nada de aquí importa para lo que sigue.
• /handoff escribe un archivo markdown portátil. Estrecho: solo para un nuevo armazón, un nuevo directorio, un colega, o bifurcar una tarea lateral en medio de una fase. Lo que compra es portabilidad.
• Subagente: envía una tarea con alcance ajustado a su propia ventana y recibe un informe.
• /compact comprime este contexto y siembra una nueva sesión con él. El predeterminado, en la parte inferior del árbol en lugar de la primera opción.

Lee PHASE-BOUNDARIES.md para el árbol ordenado: las cinco preguntas, el razonamiento detrás de cada rama, y por qué el coste de la fuente primaria hace que Continuar sea el que hay que descartar primero. Toma la decisión en un límite; en medio de la fase, continúa o divide el resto en subagentes.

Independientes

Fuera del flujo principal por completo.

• /grill-me: la misma entrevista implacable que /grill-with-docs, pero sin estado: no guarda nada localmente y no construye GLOSSARY.md. Recurre a él cuando no estés trabajando en un directorio de trabajo (afilando un plan, un diseño, un escrito, cualquier cosa sin un repositorio debajo). Si estás en un directorio de trabajo, usa /grill-with-docs en su lugar: ejecuta la misma entrevista y deja un rastro documental, por lo que es estrictamente mejor.
• /grilling es la primitiva de entrevista en sí misma: rondas, la frontera, los hechos son trabajo del agente y las decisiones son tuyas. /grill-me y /grill-with-docs son las dos formas nombradas de entrada, y /triage, /wayfinder y /improve-codebase-architecture todas lo ejecutan internamente. Recurre a él directamente solo cuando quieras la entrevista sin envoltorio.
• /prototype es un programa pequeño y desechable que responde una pregunta de diseño: ¿este modelo de estado se siente correcto, o cómo debería verse esta interfaz de usuario? Desechable es una restricción sobre cómo se escribe el código, no una promesa de destruirlo: la respuesta se pliega en el código real, y el prototipo en sí se mantiene como una fuente primaria en una rama prototype/<nombre> fuera de main, señalada desde el issue de implementación. Es el desvío en el paso 2 del flujo principal, pero recurre a él en cualquier momento en que una pregunta de diseño sea difícil de resolver en papel.
• /research: delega el trabajo de lectura a un agente de fondo: investiga una pregunta contra fuentes primarias, luego deja un archivo Markdown citado en el repositorio. Sigue trabajando mientras lee. El archivo que produce es algo para llevar al flujo principal en /grill-with-docs, ya que la investigación alimenta el pensamiento en lugar de reemplazarlo.
• /to-questionnaire aparece cuando lo que te bloquea no está en tu cabeza ni en el código base sino en la de otro, y les escribe un cuestionario para que lo llenen. Es el inverso de /grill-me: en lugar de entrevistarte a ti sobre el tema, te entrevista a ti sobre el envío (a quién va dirigido, qué necesitas de vuelta) y apunta las preguntas a la brecha. Lo que vuelve es material para /grill-with-docs o /to-spec.
• /wizard es para los pasos que solo un humano puede tomar: aprovisionar infraestructura, configurar credenciales o secretos de CI, navegar por un panel de control de terceros desconocido, ejecutar una migración o corte único. Genera un script bash interactivo que abre cada URL, captura cada valor y lo escribe en .env y los secretos de GitHub, para que el procedimiento deje de ser algo que reexplicas a un agente cada vez. Invocado por el modelo, por lo que el agente recurre a él en el momento en que choca contra un muro que solo tú puedes pasar. Si el agente pudiera hacerlo por sí mismo, debería; esto es para cuando un humano está genuinamente en el bucle.
• /wait-what es el correctivo para un mensaje que no aterrizó. Úsalo en medio de una conversación, dentro de cualquier otra habilidad, y el agente reformula lo que acaba de decir con el contexto que te faltaba, en inglés sencillo, usando el vocabulario de GLOSSARY.md. Funciona después del hecho; /grill-with-docs es la cura preventiva, porque un lenguaje compartido acordado temprano es lo que evita que llegue la jerga en absoluto.
• /teach: aprende un concepto a lo largo de múltiples sesiones, usando el directorio actual como un espacio de trabajo con estado.
• /writing-for-agents es la referencia para escribir documentos que los agentes consumen: habilidades, AGENTS.md, documentos señalados.

Precondición

/setup-matt-pocock-skills: ejecuta antes de tu primer flujo de ingeniería para configurar el rastreador de issues, las etiquetas de triaje y el diseño de documentos que las otras habilidades asumen. Los rastreadores de issues personalizados también funcionan.