pedro-oscar/shorts-ai

Pregunta a Matt

No recuerdas todas las habilidades, así que pregunta.

Antes de decir qué hace una habilidad o recomendar omitir 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 por debajo.

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. Empieza aquí siempre que estés trabajando en un directorio de trabajo: tiene estado, conservando lo que aprende en GLOSSARY.md y ADR. (¿No tienes un directorio de trabajo? Usa /grill-me, que se cubre en Independientes. Ambos ejecutan la misma primitiva /grilling; grill-with-docs es el que deja un rastro en papel, lo que lo convierte en el mejor de los dos siempre que haya un repositorio donde dejarlo).

2. Rama: ¿puedes resolver todas las preguntas en conversación? Si una pregunta necesita una respuesta ejecutable (estado, lógica de negocio, una interfaz de usuario que tengas que 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 hacia fuera, luego abre una nueva sesión contra ese archivo,
   • /prototype para responder la pregunta con código desechable,
   • /handoff de vuelta con lo aprendido, y referéncialo 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, /clearando 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 cualquier ticket cuyos bloqueadores estén hechos se puede tomar. Cada ticket es autónomo, 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. Recurre a él cuando prefieras orquestar la construcción en lugar de conducir cada ticket tú mismo.
   • No → /implement aquí mismo, en la misma ventana de contexto.

   De cualquier manera, el código se construye impulsando /tdd (una rebanada roja-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 a /code-review por sí solo siempre que quieras revisar una rama o PR contra un punto fijo.

   Cuando el trabajo sube como una solicitud de extracción (pull request), /pr da forma al cuerpo: la visualización más pequeña 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 si salió mal, revisa la sesión y sugiere cambios al entorno del agente, no al 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; las decisiones de criterio se convierten en estándares de codificación. La siguiente construcción comienza desde un entorno mejor.

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 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 todavía razona con claridad. Si una sesión se acerca antes de /to-tickets, no insistas con degradación; /compact en el límite de fase más cercano y continúa (ver Límites de fase).

Rampas de acceso

Una situación de inicio que genera trabajo y luego se fusiona con el flujo principal.

• Se acumulan errores y solicitudes → /triage. Mueve los problemas a través de roles de triaje y produce problemas listos para el agente, que /implement recoge más tarde.

  El triaje es solo para problemas que no creaste: informes de errores, solicitudes de características 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 un primer vistazo, el fallo 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 el arreglo está listo, ejecuta /retro en la misma sesión para preguntar qué habría evitado el error; donde el hallazgo real es que no hay una buena costura para asegurarlo, eso es trabajo para /improve-codebase-architecture.

• Un esfuerzo enorme y nebuloso: un proyecto desde cero o una construcción de características enorme, 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 problemas 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 exactamente para eso, nunca para una característica bien delimitada.

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

Salud del código base

No es trabajo de características, solo mantenimiento.

• /improve-codebase-architecture se ejecuta siempre 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 donde diseñas el elegido.

Vocabulario subyacente

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

• /domain-modeling: afila el lenguaje de dominio del proyecto: cuestiona 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 de módulo profundo (módulo, interfaz, profundidad, costura, adaptador, apalancamiento, localidad) para diseñar la forma de un módulo: mucho comportamiento detrás de una interfaz pequeña en una costura limpia. Tanto /tdd como /improve-codebase-architecture lo hablan.

Límites de fase

Una fase es un fragmento 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 quieto. No cuesta nada, no pierde nada.
• /clear: vacía la ventana, cuando nada aquí importa para lo que sigue.
• /handoff escribe un archivo Markdown portátil. Estrecho: solo para un nuevo arnés, 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 de alcance ajustado a su propia ventana y obtén un informe de vuelta.
• /compact comprime este contexto y siembra una nueva sesión con él. El predeterminado, en la parte inferior del árbol en lugar del primer alcance.

Lee PHASE-BOUNDARIES.md para el árbol ordenado: las cinco preguntas, el razonamiento detrás de cada rama, y por qué el costo de la fuente primaria hace que Continuar sea la que hay que descartar primero. Toma la decisión en un límite; en medio de una 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 (afinando 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 en papel, 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 entrar, y /triage, /wayfinder y /improve-codebase-architecture lo ejecutan internamente. Recurre a él directamente solo cuando quieras la entrevista sin ningún envoltorio alrededor.
• /prototype es un programa pequeño y desechable que responde a una pregunta de diseño: ¿este modelo de estado se siente bien, 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/<name> fuera de main, señalada desde el problema de implementación. Es el desvío en el paso 2 del flujo principal, pero recurre a él cada vez que una pregunta de diseño es 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 entra cuando lo que te bloquea no está en tu cabeza ni en el código base sino en la de otra persona, y les escribe un cuestionario para que lo llenen. Es el inverso de /grill-me: en lugar de entrevistarte sobre el tema, te entrevista 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 dar: aprovisionar infraestructura, configurar credenciales o secretos de CI, hacer clic en un panel de control de terceros desconocido, ejecutar una migración o transición única. Genera un script bash interactivo que abre cada URL, captura cada valor y lo escribe en .env y secretos de GitHub, por lo que el procedimiento deja 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 una pared que solo tú puedes pasar. Si el agente pudiera hacerlo por sí mismo, debería; esto es para donde un humano está genuinamente en el bucle.
• /wait-what es el correctivo para un mensaje que no llegó. Úsalo en medio de la conversación, dentro de cualquier otra habilidad, y el agente reformula lo que acaba de decir con el contexto que te faltaba, en español 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.
• /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 apuntados.

Precondición

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