PTENES
MÓDULO 1.6 — FINAL

🏁 Módulo 1.6 — Workflow completo

De la idea al PR mergeado. Conecta todas las skills de Matt Pocock en un único ciclo repetible: setup → grill → PRD → issues → triage → TDD → review → merge.

8
Etapas
~45
Minutos
Avanzado
Nivel
Práctica
Tipo
1

⚙️ Configuración inicial: /setup-matt-pocock-skills

Antes de ejecutar cualquier otra skill, el repositorio debe estar configurado una vez. O /setup-matt-pocock-skills te entrevista sobre tres puntos y registra las decisiones en archivos versionados; todas las demás skills leen este contexto para comportarse de la manera correcta.

🎯 Qué decide el setup

  • • Issue tracker: GitHub Issues, Linear o carpeta local issues/ en markdown. Define dónde /to-prd e /to-issues van a escribir.
  • • Vocabulario de etiquetas: los roles de /triage (needs-triage, ready-for-afk, blocked, etc.) se convierten en etiquetas reales en el tracker.
  • • Diseño del documento: dónde está CONTEXT.md, dónde van los ADRs, y cómo /grill-with-docs debe actualizarlos.

💻 Prompts típicos de la skill 

$ /setup-matt-pocock-skills

→ Qual issue tracker este repo usa?
   [1] GitHub Issues  [2] Linear  [3] Local (issues/*.md)

→ Onde fica a documentação viva?
   docs/CONTEXT.md (default)  ou caminho customizado

→ Pasta de ADRs?
   docs/adr/ (default)

✓ Gravado em .claude/skills-config.json
✓ Stub de docs/CONTEXT.md criado
✓ Labels recomendadas listadas (rode `gh label create ...`)

💡 Consejo práctico

Ejecuta /setup-matt-pocock-skills una sola vez por repo, justo después del clone. Haz commit de .claude/skills-config.json y del stub de CONTEXT.md — así todo el equipo hereda el mismo workflow.

CONCEPTO 1
El setup es por repo, no global
CONCEPTO 2
Las decisiones se convierten en archivos versionados
CONCEPTO 3
Habilita las otras skills
CONCEPTO 4
Ejecuta una vez, no a cada rato
2

🔥 Etapa 1 — Grilling (alineación)

Toda feature nueva empieza por /grill-with-docs. Él interroga tu idea frente al dominio existente: vocabulario del CONTEXT.md, ADRs anteriores, restricciones conocidas. El resultado no es código: es alineación.

📝 Qué se obtiene del grilling

  • • CONTEXT.md actualizado: nuevos términos del dominio, ambigüedades resueltas, alcance refinado.
  • • Nuevos ADRs: las decisiones arquitectónicas que surgieron durante el grilling se convierten en archivos en docs/adr/.
  • • Conversación guardada: la transcripción queda disponible para /to-prd usar como insumo.

🚫 NO te saltes esta etapa

Omitir el grilling es el error n.º 1 de quienes empiezan con las skills. Sin alineación, generas PRD basados en premisas incorrectas, y la cascada se convierte en retrabajo. 15 minutos de grilling ahorran 3 horas de refactorización.

CONCEPTO 1
Grilling siempre va primero
CONCEPTO 2
El output es alineación, no código
CONCEPTO 3
Actualiza CONTEXT.md en línea
CONCEPTO 4
Genera ADR cuando toma una decisión
3

📄 Etapa 2 — /to-prd (sintetizar)

Con la conversación de grilling fresca, /to-prd sintetiza todo en un PRD y crea una issue en el tracker. Ten en cuenta: no hay una nueva entrevista — la skill usa el contexto de la sesión actual + CONTEXT.md.

🧠 Por qué sin una nueva entrevista

Volver a preguntar todo sería un desperdicio: el agente ya vio la discusión. La skill extrae, no recopilación. Esto cambia el tipo de relación con el agente: cada skill es un nodo de un pipeline, no una conversación aislada.

  • 67% menos preguntas redundantes frente a PRD hechos desde cero
  • Contexto preservado: los términos, las restricciones y los ADR ya están en la narrativa

📋 PRD generado (ejemplo) 

# PRD: Importação CSV de leads

## Problema
Time comercial cola CSV no Slack; ninguém importa.
~40 leads/semana perdidos.

## Solução proposta
Endpoint POST /leads/import aceita CSV multipart.
Valida colunas obrigatórias (email, nome, fonte).
Deduplica por email. Retorna relatório.

## Fora de escopo
- UI de upload (vem em PRD futuro)
- Enriquecimento de dados

## Critérios de aceite
- [ ] CSV válido importa em <5s para 1000 linhas
- [ ] Linhas inválidas retornam no response, não 500
- [ ] Idempotente: re-upload não duplica

## Decisões herdadas
ADR-012: validação via Zod (não Yup).
ADR-019: jobs >2s vão pra fila, não inline.
CONCEPTO 1
Sintetiza, no entrevistes
CONCEPTO 2
Crea un issue en el tracker
CONCEPTO 3
Cita ADR heredados
CONCEPTO 4
Define "fuera de alcance"
4

🔪 Etapa 3 — /to-issues (dividir)

Un PRD no es ejecutable. /to-issues divide el PRD en vertical slices — cada slice es un issue independiente que aporta valor visible por sí solo.

✓ Slices verticales (HACER)

  • ✓ "Aceptar la carga de un CSV y devolver el conteo de filas" — comprobable de extremo a extremo
  • ✓ "Validar las columnas obligatorias con error 400" — ofrece un comportamiento visible
  • ✓ "Deduplicar por email en el insert" — se puede mergear por sí solo
  • ✓ Cada una tiene un criterio de aceptación en el PR

✗ Tareas técnicas aisladas (EVITAR)

  • ✗ "Crear un schema Zod" — no aporta nada por sí solo
  • ✗ "Agregar la dependencia csv-parse" — invisible
  • ✗ "Refactorizar el service de leads" — ¿se puede mergear? ¿Para qué?
  • ✗ "Configurar el endpoint sin lógica" — PR vacío

💡 Consejo práctico

Prueba cada slice con la pregunta: "Si hago merge solo de esta, ¿alguien la usa mañana?" Si la respuesta es "no, hay que incluir las otras también", el slice es horizontal: divídelo de nuevo.

CONCEPTO 1
Vertical, no horizontal
CONCEPTO 2
Cada slice se puede fusionar por separado
CONCEPTO 3
Criterio de aceptación por issue
CONCEPTO 4
Prueba: «¿alguien lo usará mañana?»
5

🚦 Etapa 4 — /triage (priorizar)

Las issues nuevas llegan con la etiqueta needs-triage. O /triage las mueve de a una máquina de estados de roles — cada estado describe en qué etapa del flujo está la issue y quién puede actuar.

1

needs-triage

Estado inicial — salió recién de /to-issues

Nadie lo ha revisado todavía. Puede estar mal dividido, duplicado o fuera de prioridad. Bloquea la ejecución.

2

needs-discussion

Hay una ambigüedad que /grill no resolvió

Necesita una conversación sincrónica con una persona. Vuelve al grilling si es necesario.

3

ready-for-human

Lista, pero necesita a un desarrollador sénior

Hay matices arquitectónicos: el agente por sí solo no basta. Se encarga una persona.

4

ready-for-afk

El agente trabaja solo, tú sales a almorzar

Criterio de aceptación claro, alcance breve, bajo riesgo. /tdd resuelve mientras no estás.

5

blocked

Depende de algo externo

API de terceros, decisión de producto, otra issue sin mergear. Vuelve a la cola cuando se desbloquee.

6

in-progress → done

Estados terminales del ciclo

PR abierto → en progreso. PR mergeado → listo. El issue se cierra automáticamente mediante «Closes #N».

CONCEPTO 1
Cada issue tiene un role
CONCEPTO 2
Los roles son etiquetas reales en el tracker
CONCEPTO 3
ready-for-afk = candidato a TDD
CONCEPTO 4
Los estados transitan, no se acumulan
6

🧪 Etapa 5 — Implementación con /tdd

Toma una issue ready-for-afk, crea una branch, ejecuta /tdd. La skill ejecuta el ciclo clásico red → green → refactor guiado por los criterios de aceptación del issue.

🔄 El loop por slice

  • RED Escribe una prueba que falle. El criterio de aceptación #1 se convierte en la primera prueba. Ejecútala — rojo.
  • GREEN Implementa lo mínimo para que pase. Nada más. Ejecútalo — todo en verde.
  • REFACTOR Limpia el código sin cambiar el comportamiento. Las pruebas siguen pasando. El siguiente criterio pasa a ser el siguiente RED.

💡 Consejo práctico

Si el /tdd intentar saltarse el RED ("solo voy a implementar y después pruebo"), detente. RED primero, siempre. Sin que la prueba falle antes, no sabes si sirve de algo.

CONCEPTO 1
Rama por issue
CONCEPTO 2
RED → GREEN → REFACTOR
CONCEPTO 3
Criterios de aceptación = pruebas
CONCEPTO 4
Sin RED, sin saltarse pasos
7

👀 Etapa 6 — Revisión y merge

Rama en verde, es hora de la PR. Usa /verify (ejecutar la app de verdad y ver que funciona) o code-review (revisión estática del diff). Comentarios atendidos, merge.

✓ Lista de verificación antes del merge

  • ✓Las pruebas pasan en CI
  • ✓Todos los criterios de aceptación del issue en verde
  • ✓/verify mostró el comportamiento real
  • ✓code-review sin hallazgos de alta severidad
  • ✓La descripción del PR menciona «Closes #N»

✗ No hagas merge si

  • ✗"Las pruebas locales pasan, pero CI está lento; igual va así"
  • ✗El criterio de aceptación #3 quedó para otra PR
  • ✗El diff tiene archivos no relacionados con el issue
  • ✗Cambió el comportamiento sin actualizarse CONTEXT.md
  • ✗PR sin enlace al issue («Closes»)

📊 /verify vs code-review

  • /verify: ejecuta la app, realiza la acción real y demuestra que funciona de extremo a extremo. Úsalo cuando el slice cambie el comportamiento visible.
  • code-review: análisis estático del diff, busca bugs sutiles y edge cases. Úsala siempre: es barato y rápido.
  • Ambos: en funcionalidades críticas. Bajo costo, mucha señal.
CONCEPTO 1
/verify demuestra el funcionamiento
CONCEPTO 2
code-review detecta bugs sutiles
CONCEPTO 3
"Closes #N" cierra automáticamente
CONCEPTO 4
El merge cambia el estado a done
8

🗺️ Visión general — el ciclo completo

Conectándolo todo: el ciclo se realimenta — el próximo grilling ya empieza con un CONTEXT.md más maduro, con ADR nuevos y un vocabulario refinado por la feature anterior.

🔀 Diagrama de flujo del workflow 

  ┌─────────────────────────────────────────────────────────┐
  │  /setup-matt-pocock-skills  (uma vez por repo)        │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /grill-with-docs           CONTEXT.md + ADRs        │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /to-prd                    issue com PRD             │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /to-issues                 N vertical slices         │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /triage                    role por issue            │
  │     needs-triage → ready-for-afk / ready-for-human       │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /tdd                       red → green → refactor    │
  │     (uma branch por issue)                               │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  /verify + code-review     PR review                 │
  └────────────────────────┬────────────────────────────────┘
                           ▼
  ┌─────────────────────────────────────────────────────────┐
  │  merge                      issue → done              │
  │  CONTEXT.md atualizado pelo próximo /grill              │
  └────────────────────────┬────────────────────────────────┘
                           │
                           └───── volta pro /grill-with-docs ─────┐
                                  (próxima feature)               │
                                                                  ▼
                                                          (ciclo se repete)

♻️ El ciclo se retroalimenta

Cada vuelta deja el CONTEXT.md más denso, los ADR más completos y el vocabulario del dominio más preciso. Grilling #10 es más rápido y profundo que grilling #1 — porque el agente ya entiende tu dominio. Este es el compuesto real de las skills de Matt Pocock.

CONCEPTO 1
8 etapas, 1 ciclo
CONCEPTO 2
CONTEXT.md como artefacto vivo
CONCEPTO 3
Cada vuelta deja el repo mejor
CONCEPTO 4
Compuesto, no lineal

🎓 Conclusión del curso

Terminaste la Ruta 1. Repasemos los 4 problemas que abrieron el curso — y cómo cada skill resuelve una parte.

1.
"El agente olvida todo entre sesiones" → CONTEXT.md + /grill-with-docs dan memoria versionada y refinable.
2.
"Las especificaciones ambiguas se convierten en código incorrecto" → hacer grilling antes del PRD detecta la ambigüedad desde el principio; /to-prd sintetiza con un alcance claro.
3.
"Las tareas grandes nunca terminan" → /to-issues en vertical slices hace que cada parte se pueda fusionar por sí sola.
4.
"No se puede confiar en lo que entrega el agente" → /tdd + /verify + code-review forman el trípode de confianza: pruebas que demuestran, ejecución que muestra, revisión que cuestiona.

🚀 Siguientes pasos

  • → Practica en un proyecto real. Elige un repo tuyo, ejecuta /setup-matt-pocock-skills, y usa el workflow en una feature pequeña (1-2 slices). No intentes aplicarlo todo de una vez en un proyecto grande.
  • → Itera el CONTEXT.md. Vuelve a leerlo después de cada feature integrada. Añade lo que aprendiste. Es tu mayor activo.
  • → Compártelo con el equipo. El workflow solo funciona si más personas lo usan: todos leyendo el mismo CONTEXT.md y respetando los mismos roles de /triage.

🔗 Enlaces útiles

← Módulo 1.5 Volver a la Ruta →