@saulwade/swl-ses 1.4.1 → 1.5.0

package/habilidades/ejecutar-task-iterativo/SKILL.md

@@ -0,0 +1,278 @@
+---
+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