---
name: ejecutar-task-iterativo
description: >
  Modo iterativo de ejecución por tarea (opt-in via /swl:ejecutar-fase --iterative)
  donde cada tarea atómica recibe contexto fresco, implementer dispatched como
  sub-agente independiente, revisión task-local con protocolo-revision-swl,
  auto-debug en BLOCKED, y commit por tarea. Alternativa al modo default
  (oleadas paralelas con verificación al final de fase). Cargar cuando la fase
  tiene tareas con dependencias secuenciales fuertes, módulos críticos donde
  cada tarea merece revisión adversarial inmediata, o cuando la fase tiene
  >12 tareas y el modo paralelo arriesga acumular deuda no detectada.
version: "1.0.0"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep, Agent]
exclusiones:
  - "No cargar si /swl:ejecutar-fase NO recibió el flag --iterative — el modo default sigue siendo oleadas paralelas."
  - "No cargar para fases pequeñas (<5 tareas) — el overhead per-task supera el beneficio."
  - "No cargar para tareas que no son atómicas o no tienen verificación clara — la iteración requiere boundary explícito por tarea."
  - "No cargar si PLAN.md no tiene `estado: aprobado` — requirement freeze obligatorio antes de ejecutar."
evolvable: true
---

# Ejecución iterativa per-task

## Propósito

El modo default de `/swl:ejecutar-fase` ejecuta tareas en **oleadas paralelas**
y verifica al final de la fase con `verificar-trabajo` goal-backward. Esto es
eficiente para fases con tareas independientes y bajo riesgo.

Sin embargo, hay casos donde la granularidad task-por-task es superior:

- Tareas con dependencias secuenciales fuertes (cada una depende del resultado de la anterior).
- Módulos críticos (dinero, permisos, datos irreversibles) donde cada tarea merece revisión adversarial.
- Fases con >12 tareas, donde el modo paralelo arriesga acumular deuda silenciosa.
- El usuario explícitamente pide "una a una, revisando cada una".

Este skill implementa ese modo: 1 tarea por iteración, contexto fresco,
implementer dispatchado como sub-agente, review task-local con
`protocolo-revision-swl`, auto-debug en `BLOCKED`, y commit por tarea.

Adaptado del patrón `kiro-impl` de cc-sdd, manteniendo identidad SWL.

## Cuándo cargar

- `/swl:ejecutar-fase N --iterative` (flag explícito del usuario)
- El usuario pide "ejecuta el plan tarea por tarea con revisión en cada una"
- El PLAN.md declara en su frontmatter `modo_ejecucion: iterativo`

## Cuándo NO cargar

Ver `exclusiones` en frontmatter.

---

## Precondiciones (verificar antes de iterar)

1. `.planning/fases/0N-PLAN.md` con `estado: aprobado` (requirement freeze).
2. `.planning/ESTADO.md` inicializado o actualizado.
3. Working tree limpio (`git status --porcelain` vacío) o el usuario explícitamente autoriza cambios pendientes.
4. Tests del proyecto en estado "verde de base" — capturar baseline antes del primer task para detectar regresiones limpiamente.
5. Validation commands descubiertos del proyecto (test, build, lint, smoke):

```bash
node -e "const p=require('./package.json');console.log(JSON.stringify(p.scripts||{}))" 2>/dev/null
```

Si no se pueden derivar comandos canónicos → reportar al usuario y pedir
guía antes de iterar.

---

## El loop iterativo (1 task por iteración)

### Disciplina del loop

- **Una sola sub-tarea por iteración** (ej. 3.1, luego 3.2, luego 3.3 — no batch).
- **Contexto fresco**: al inicio de cada iteración, re-leer `PLAN.md` para
  determinar la siguiente tarea actionable. NO confiar en memoria acumulada
  de iteraciones previas.
- **Memoria residual mínima**: tras cada iteración, retener solo 1 línea
  ("3.1: APPROVED, 3 archivos cambiados"). Descartar status report completo
  y detalles del reviewer.
- **Re-read tasks.md antes de cada nuevo dispatch** — el implementer previo
  pudo agregar `## Implementation Notes` que aplican a la siguiente tarea.

### Iteración estándar

Para cada sub-tarea pendiente, en orden:

#### Paso 1 — Identificar la siguiente tarea

```bash
# Re-leer PLAN.md y encontrar primera tarea no marcada [x]
grep -E "^\s*- \[ \]" .planning/fases/0N-PLAN.md | head -1
```

- Saltear tareas con anotación `_Blocked:_`.
- Verificar dependencias declaradas en `_Depends:_` — si una dependencia no está `[x]`, ejecutarla primero o pedir resolución al usuario.
- Leer `_Boundary:_` para identificar los paths/módulos que esta tarea puede tocar.

#### Paso 2 — Dispatch del implementer (como sub-agente fresh)

Construir prompt con:

- Texto literal de la tarea (no parafrasear).
- Boundary scope.
- Paths a spec files (`PLAN.md`, `CONTEXTO.md`, otros).
- IDs literales de requirements/design references (NO inventar `REQ-*` aliases).
- Validation commands del proyecto (test, build, smoke) relevantes a la tarea.
- Implementation Notes previas del PLAN.md que apliquen al boundary actual.
- Indicación de si la tarea es behavioral (requiere feature flag opcional) o no-behavioral.

Invocar el sub-agente vía `Agent` tool con `subagent_type` apropiado:

- Backend Python → `backend-python-swl`
- Backend Node → `backend-node-swl`
- Frontend React → `frontend-react-swl`
- ... (matriz `usar-sistema-swl.md`)
- Fallback: `implementador-swl`

El sub-agente debe devolver un **Status Report estructurado** con campo
`STATUS: READY_FOR_REVIEW | BLOCKED | NEEDS_CONTEXT`.

#### Paso 3 — Manejar el status del implementer

Parsear el status solo del bloque exacto `## Status Report` con campo `STATUS:`.
Si el status no es parseable, re-dispatch UNA VEZ pidiendo el bloque estructurado.
Sin status parseable tras 2 dispatches → escalar.

| Status | Acción |
|--------|--------|
| `READY_FOR_REVIEW` | Continuar al Paso 4 (review) |
| `NEEDS_CONTEXT` | Re-dispatch UNA VEZ con el contexto adicional solicitado. Si persiste → Paso 5 (debug) |
| `BLOCKED` | Saltar a Paso 5 (debug). NO marcar la tarea como saltada |

#### Paso 4 — Review task-local

Invocar el revisor apropiado al stack:

- `revisor-codigo-swl` (general)
- `revisor-react-swl` / `revisor-angular-swl` (frontend)
- `revisor-typescript-swl` / `revisor-python-*` / etc.
- `revisor-seguridad-swl` (si la tarea toca auth, secretos, input externo)

El revisor carga `Skill("protocolo-revision-swl")` y emite veredicto:

| Verdict | Acción |
|---------|--------|
| `APPROVED` con score ≥9.0 | Continuar al Paso 6 (commit) |
| `REJECTED` (1er ciclo) | Re-dispatch del implementer con las findings del revisor. Volver al Paso 3 |
| `REJECTED` (2do ciclo) | Saltar al Paso 5 (debug) — la remediación no convergió |

Veredictos persistidos en `.planning/audit/reviews/<task-id>-<ts>.json`.

#### Paso 5 — Auto-debug (cuando BLOCKED o REJECTED persiste)

Invocar `depurador-swl` con contexto fresh:

- Síntoma exacto del blocker o de los findings que no se resolvieron.
- Stack trace, output del comando fallido, exit code.
- Reviewer feedback si aplica.
- `_Boundary:_` de la tarea.
- Implementation Notes relacionadas.

El depurador retorna:

```
ROOT_CAUSE: <descripción>
FIX_PLAN: <pasos concretos>
VERIFICATION: <cómo verificar el fix>
NEXT_ACTION: RETRY_TASK | BLOCK_TASK | STOP_FOR_HUMAN
CONFIDENCE: HIGH | MEDIUM | LOW
```

- `RETRY_TASK` con CONFIDENCE HIGH/MEDIUM → re-dispatch implementer con el fix plan. Volver al Paso 3.
- `BLOCK_TASK` → marcar tarea con `_Blocked:_<razón>_` en PLAN.md. Actualizar ESTADO.md. Continuar con la SIGUIENTE tarea (no esta).
- `STOP_FOR_HUMAN` → pausar el loop y escalar al usuario con el informe del depurador.

#### Paso 6 — Commit atómico de la tarea

Tras APPROVED:

```bash
git add <archivos del diff de esta tarea>
git commit -m "<tipo>(<scope>): <descripción imperativa de la tarea>

Tarea: <task-id> — <texto literal>
Plan: .planning/fases/0N-PLAN.md
Review: .planning/audit/reviews/<task-id>-<ts>.json"
```

Marcar la tarea como `[x]` en PLAN.md en el mismo commit (o en commit
inmediato siguiente atómico).

#### Paso 7 — Update de ESTADO.md y memoria

- Marcar tarea `[x]` en PLAN.md.
- Actualizar ESTADO.md con: tarea completada, commit hash, archivos cambiados, score del review.
- Agregar al final del PLAN.md, en sección `## Implementation Notes`, cualquier learning relevante para tareas futuras del mismo boundary o dependencia.
- Retener solo 1 línea en memoria de iteración para el siguiente loop.

#### Paso 8 — Próxima iteración o cierre

- Si quedan tareas pendientes: volver al Paso 1.
- Si todas las tareas están `[x]` o `_Blocked:_`: cerrar el loop e invocar
  el flujo de cierre estándar de `ejecutar-fase` (RESUMEN.md, actualizar
  HOJA-RUTA.md, verificación goal-backward final con `verificar-trabajo` —
  ver Paso 6-8 del comando `/swl:ejecutar-fase`).

---

## Persistencia de aprendizajes entre tareas

A diferencia del modo paralelo (donde cada wave es relativamente
independiente), el modo iterativo propaga aprendizajes:

### En PLAN.md, sección `## Implementation Notes`:

```markdown
## Implementation Notes

- **Tarea 1.2 (POST /facturas)**: `Pydantic v2` cambia `parse_obj` → `model_validate`.
  Aplica a futuras tareas que validen schemas con v2.
- **Tarea 2.1 (migración)**: `Alembic` no detecta cambios en `JSONB` automáticamente —
  marcar con `nullable=False` explícito.
```

El implementer del paso 2 lee estas notes antes de empezar. Esto evita
repetir los mismos errores task-a-task.

---

## Diferencias clave con el modo default (paralelo por oleadas)

| Aspecto | Modo default (paralelo) | Modo iterativo (este skill) |
|---------|------------------------|----------------------------|
| Granularidad | Oleada (varias tareas en paralelo) | 1 tarea por iteración |
| Contexto del implementer | Acumulado entre tareas de la misma oleada | Fresco por tarea (sub-agente nuevo) |
| Review | Al final de fase con `verificar-trabajo` | Tras cada tarea con `protocolo-revision-swl` |
| Auto-debug | Manual o post-mortem | Automático en BLOCKED |
| Commit | Atómico por slice/tarea (similar) | Atómico estricto por tarea + review JSON |
| Implementation Notes | No requeridas | Propagadas entre tareas |
| Costo en tokens | Menor | Mayor (~1.5-2× por contexto fresh) |
| Cuándo preferir | Fases con tareas independientes, riesgo bajo | Tareas con dependencias fuertes, módulos críticos, fases grandes |

---

## Gotchas / Errores comunes no obvios

- **Re-usar contexto acumulado del implementer entre iteraciones**: el implementer del task 3.2 NO debe tener en su contexto el reporte completo del task 3.1 — solo el `## Implementation Notes` relevante. Causa: ahorro falso de tokens. Solución: dispatch fresh siempre, los notes son el canal explícito de propagación.
- **Saltar el Paso 4 (review) "porque la tarea es chica"**: el review per-task es lo que distingue este modo del default. Sin review per-task, el modo iterativo es solo "lento sin beneficio". Solución: si la tarea es realmente trivial, no usar modo iterativo.
- **Auto-debug que sugiere FIX y se aplica sin re-review**: tras debug → fix → COMMIT directo es anti-patrón. Solución: cada FIX debe volver al Paso 4 (review) antes de commit.
- **Boundary violations toleradas porque "el implementer tenía que tocar eso"**: si un archivo fuera del boundary aparece en el diff y el revisor lo marca como finding, no se puede aceptar sin extender el boundary EN EL PLAN.md (decisión documentada). Solución: si el boundary necesita extenderse, actualizar PLAN.md primero y volver a iterar.
- **`MERGED` en main sin marcar la tarea `[x]` en PLAN.md**: deja ESTADO.md y PLAN.md desincronizados. Solución: marcar `[x]` está en el MISMO commit del cambio (no commit aparte).

---

## Relación con otros componentes SWL

| Componente | Relación |
|-----------|----------|
| `ejecutar-fase` | Skill padre — el flag `--iterative` cede el control a este skill |
| `protocolo-revision-swl` | Invocado en Paso 4 por el revisor |
| `verificar-trabajo` | Invocado al cerrar el loop como verificación goal-backward final |
| `depurador-swl` | Invocado en Paso 5 cuando hay BLOCKED o REJECTED persistente |
| `implementador-swl` y agentes de stack | Dispatchados como sub-agentes en Paso 2 |
| `notificador-swl` | Invocado en STOP_FOR_HUMAN o ESCALATE |
| `reglas/seguridad-agentes.md` § Recovery Catalog | Marco de escalada (reprompt → reduce-autonomy → escalate → terminate) |

## Checklist de cierre del loop

- [ ] Todas las tareas pendientes están `[x]` o `_Blocked:_<razón>_`
- [ ] Cada tarea tiene su review JSON en `.planning/audit/reviews/`
- [ ] PLAN.md tiene `## Implementation Notes` con aprendizajes relevantes
- [ ] ESTADO.md actualizado con commit hashes y scores
- [ ] Verificación goal-backward final ejecutada (`verificar-trabajo`)
- [ ] RESUMEN.md generado (paso del flujo estándar de `ejecutar-fase`)
- [ ] Working tree limpio o con cambios pendientes documentados
