User Execution Guide

• tasks.md — task breakdown, phases, exit criteria
• PRD.md — if already generated (read for summary context)
• design.md — for architecture context and technology decisions

If tasks.md is missing: report "SPO generation blocked — tasks.md not found. Run sdd-tasks first."

Step 2 — Identify waves

A wave is a group of tasks that must execute in the same session or can be batched together. Group tasks into waves based on dependencies and session budget:

Wave rules:

• Tasks with dependencies (Task 2 needs Task 1's output) → same wave, sequential
• Tasks that touch different files and can reset → separate waves (different sessions)
• Rule of thumb: each wave = 1 Claude Code session with fresh context
• If all tasks are simple and sequential → single wave is fine

For each wave, determine:

1. What session it opens in (new session vs continuing)
2. The exact command to paste to start it
3. The gates the operator will encounter
4. What to verify when it's done

Step 3 — Write SPO.md

Write to openspec/changes/{change-name}/SPO.md:

# SPO — {change-name}
*Guía de ejecución para el operador — generada el {ISO date}*
*Este documento es para TI, no para el agente. El agente lee PRD.md + tasks.md.*

---

## Resumen ejecutivo

**Qué se construye**: {1 oración: el resultado visible}
**Waves**: {N waves} — {breve descripción de qué hace cada una}
**Tiempo estimado**: {estimado realista por wave}
**Repo / Proyecto**: {nombre del proyecto}

---

## Preparación (antes de empezar)

- [ ] Repo clonado y actualizado (`git pull`)
- [ ] Branch de trabajo creado: `git checkout -b {branch-name}`
- [ ] Variables de entorno configuradas: {lista si aplica, o "N/A"}

---

## Wave 1: {nombre descriptivo}

### Sesión {1} — {qué logra esta sesión}

**Abre Claude Code en**: `{ruta del proyecto}`

**Pega este comando para iniciar**:

Lee PRD.md y tasks.md de {change-name}, implementa {Task N} hasta {Task M}

**Lo que verás primero**: {descripción de la primera respuesta del agente}

**Gates que encontrarás**:

| Gate | Qué te presenta el agente | Cómo aprobar |
|------|--------------------------|--------------|
| Execution Gate | Plan de archivos a modificar | Responde "dale" si el scope es correcto |
| {otro gate si aplica} | {qué muestra} | {cómo responder} |

**Al terminar esta sesión, verifica**:
- [ ] {condición verificable 1 — algo visible en el proyecto}
- [ ] {condición verificable 2}

---

## Wave 2: {nombre descriptivo} *(si aplica)*

{repetir estructura de Wave 1}

---

## Gates humanos (resumen)

| Gate | Wave | Qué aprobar | Señal de OK |
|------|------|-------------|-------------|
| Proposal | 1 | Scope y approach | "dale" o "proceed" |
| Task Plan | 1 | Lista de tareas | "dale" o "apruebo" |
| {gate específico} | {N} | {qué decisión} | {cómo aprobar} |

---

## Si algo falla

| Síntoma | Causa probable | Qué hacer |
|---------|----------------|-----------|
| El agente pide clarificación sobre {tema} | {causa} | {acción concreta} |
| Error en {paso} | {causa probable} | {resolver con este comando o acción} |
| El agente parece perdido / repite lo mismo | Contexto saturado | Abre sesión nueva: `lee CHECKPOINT.md de {change-name} y continúa` |

---

## Después de completar

- [ ] Correr verificación: {comando si aplica}
- [ ] Actualizar estado en Notion si aplica
- [ ] Abrir PR: `gh pr create`

Keep the SPO under 100 lines per wave. Focus on what the operator DOES, not on technical implementation detail.

Step 4 — Report

Return to pipeline-agent with:

STATUS: success
ARTIFACT: openspec/changes/{change-name}/SPO.md
WAVES: {N}
READY_MESSAGE: "SPO listo. Sigue la Wave 1 en SPO.md para iniciar la implementación."

Common Rationalizations

Red Flags

• SPO written in English when the operator (JNMZ) speaks Spanish — must be in Spanish
• Each wave > 100 lines — too detailed, operator will skip the verification steps
• "Lo que verás primero" section missing for any wave — operator has no signal that the agent is on track
• Gates table missing or generic ("approve when ready") — must specify the exact response ("dale", "proceed")
• "Si algo falla" section missing — operator has no recovery path when the agent stalls
• Wave 1 command doesn't reference PRD.md — the agent will start without the planning context
• Verification checklist for a wave contains internal-state items ("agent understood the requirement") instead of observable items ("file X was created")
• SPO generated without reading tasks.md first — sequencing is guessed not derived

Verification Checklist

• SPO.md written to openspec/changes/{change-name}/SPO.md
• Document is in Spanish (operator's primary language)
• Each wave is ≤100 lines
• Every wave has: session opening command, gates table, "lo que verás primero" preview, verification checklist
• Gates table specifies exact approval responses ("dale", "proceed", "apruebo")
• "Si algo falla" section present with at least 2 failure scenarios and recovery commands
• Wave 1 opening command references PRD.md so the agent has planning context
• Verification items are observable (file created, output produced) not internal (agent understood)
• Pipeline-agent received envelope with STATUS: success, ARTIFACT: <path>, WAVES: <N>, READY_MESSAGE: <text>