---
name: swl:planear-fase
description: Recibe el número de una fase y genera un plan de implementación detallado y accionable. Delega al agente planificador-swl, verifica el plan con el revisor y permite hasta 3 iteraciones de refinamiento.
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
---

# /swl:planear-fase <n> — Generar plan detallado de implementación

Eres el coordinador de planeación SWL. Tu trabajo es orquestar la generación de un plan de implementación de alta calidad para una fase específica, usando el agente planificador-swl y validando el resultado con el revisor antes de presentarlo al usuario.

## Uso

```
/swl:planear-fase 1
/swl:planear-fase 2
```

## Paso 0 — Carga de habilidades

```
Skill("planear-fase")
```

Si no existe, carga `Skill("patrones-python")` si el stack es Python, o `Skill("angular-moderno")` si el stack es Angular/TS. Siempre carga también:

```
Skill("api-rest-diseno")
```

## Paso 1 — Verificación de prerrequisitos

Verifica los siguientes archivos en orden. Si alguno falta, detente con un error claro:

1. `.planning/PROYECTO.md` — debe existir. Sin esto: "Ejecuta `/swl:nuevo-proyecto` primero."
2. `.planning/HOJA-RUTA.md` — debe existir y la fase N debe estar listada.
3. `.planning/fases/0N-CONTEXTO.md` — debe existir. Sin esto: "Ejecuta `/swl:discutir-fase N` primero para capturar el contexto de la fase."

Lee los tres archivos completos antes de continuar.

Verifica también:
- Si existe `.planning/fases/0N-PLAN.md` ya — si existe, pregunta al usuario: "Ya existe un plan para esta fase. ¿Deseas regenerarlo desde cero o refinar el existente?" Espera respuesta.
- Lee `CLAUDE.md` del proyecto si existe — puede tener restricciones de implementación.
- Si hay fases anteriores con PLAN.md o RESUMEN.md, léelas para entender patrones establecidos.

### Reglas obligatorias sobre paths y listas en PLAN.md

**Ubicación del PLAN.md** (aprendizaje HIGH 2026-05-18):

- Iniciativas que califican como fase (cualquier trabajo cross-módulo, >50 LOC, multi-archivo, o que produce un release) van a `.planning/fases/0N-PLAN.md` donde N es el siguiente número libre.
- `.planning/PLAN.md` raíz solo aceptable para hotfixes con un solo commit o ediciones triviales.
- Al delegar al `planificador-swl`, instruir explícitamente: *"produce `.planning/fases/0N-PLAN.md` donde N es el siguiente número libre visible en `ls .planning/fases/`"*. NUNCA dejar la decisión de path al sub-agente sin esta instrucción.
- Si la sesión arrancó libre (sin `/swl:discutir-fase`), crear retrospectivamente `0N-CONTEXTO.md` con tabla comparativa, 3 opciones presentadas y decisiones HITL — es válido si documenta honestamente lo que pasó en vivo.

**Listas de agentes/componentes por campo de frontmatter** (aprendizaje HIGH 2026-05-18):

- Cuando un PLAN.md liste componentes por algún campo de frontmatter (nivelRiesgo, evolvable, fase, dominio, etc.), DEBE generarse con `grep -l "^<campo>: <valor>" <dir>/*.md` con **ancla `^` al inicio de línea**.
- Sin ancla, el grep matchea menciones en el cuerpo (ej: comentarios, secciones de revisión) y devuelve falsos positivos.
- Si el CONTEXTO recibe la lista en el prompt del usuario, el planificador DEBE verificarla con grep anclado antes de incluirla en PLAN.md.
- Precedente documentado: PR Opción B (2026-05-18) — CONTEXTO listaba 6 agentes ALTO; verificación real reveló 8 distintos (solo 1 solapamiento). Slice HITL de verificación de scope es OBLIGATORIO antes de F2 si la lista llega del prompt.

## Paso 2 — Análisis del contexto

Antes de delegar, analiza el CONTEXTO.md de la fase y extrae:

1. **Tipo de trabajo predominante**: backend, frontend, infraestructura, integración, mixto.
2. **Complejidad estimada**: BAJA (1-3 días), MEDIA (1-2 semanas), ALTA (>2 semanas).
3. **Dependencias externas**: ¿hay APIs de terceros, bases de datos nuevas, servicios cloud?
4. **Riesgos que afectan la planeación**: lista los riesgos marcados como ALTO del CONTEXTO.md.
5. **Decisiones pendientes**: si hay decisiones marcadas como "[POR DEFINIR]", enuméralas aquí.

Si hay más de 2 decisiones "[POR DEFINIR]" en áreas críticas (arquitectura, modelo de datos, permisos), detente y pregunta al usuario:

```
Encontré [N] decisiones pendientes que afectan la arquitectura del plan:
1. [decisión 1]
2. [decisión 2]

Estas deben resolverse antes de planear. ¿Puedes darme tu decisión para cada una?
```

## Paso 3 — Delegación al agente planificador-swl

Delega al agente `planificador-swl` con el siguiente contexto:

**Instrucción al agente planificador-swl:**

```
Genera un PLAN.md detallado para la Fase N del proyecto [nombre].

Archivos de contexto a leer:
- .planning/PROYECTO.md
- .planning/HOJA-RUTA.md
- .planning/REQUISITOS.md
- .planning/fases/0N-CONTEXTO.md
[si aplica] - .planning/research/ARQUITECTURA.md
[si aplica] - .planning/fases/0(N-1)-RESUMEN.md (fase anterior)

El plan debe seguir el formato especificado en la sección "Formato del PLAN.md" de este comando.

Restricciones adicionales detectadas:
[lista de restricciones del PROYECTO.md y CLAUDE.md]

Riesgos que deben reflejarse en el plan:
[lista de riesgos ALTO del CONTEXTO.md]
```

Mientras el agente trabaja, monitorea el progreso. El agente debe producir `.planning/fases/0N-PLAN.md`.

## Paso 4 — Formato del PLAN.md

El agente planificador-swl debe generar el plan con esta estructura exacta:

```markdown
# Plan de implementación — Fase N: [nombre]

**Proyecto**: [nombre]
**Fase**: N de M
**Fecha de generación**: [fecha]
**Iteración del plan**: 1
**Estimación total**: [rango de días/horas]

## Resumen ejecutivo
[2-4 oraciones describiendo qué se va a construir y cómo]

## Orden de implementación (vertical slices)

### Slice 1 — [nombre del slice]
**Tipo**: AFK | HITL
**Estimación**: [horas]
**Descripción**: [qué hace este slice]

#### Tareas
1. [ ] [tarea específica con archivo o componente objetivo]
2. [ ] [tarea específica]
...

#### Criterio de verificación
[cómo saber que este slice está completo y funciona]

#### Dependencias
[qué slices o archivos deben existir antes]

### Slice 2 — [nombre]
[misma estructura]

...

## Modelos y esquemas de datos
[tablas, campos, tipos, constraints — si la fase introduce datos nuevos.
Los schemas declarados aquí (Pydantic/Zod/JSON Schema/OpenAPI) son **contrato
verificable**, parte de la spec: la tarea que los implementa se verifica con
contract testing (`Skill("calidad-contract-testing")`), no solo con tests
unitarios. Declarar el schema con la estrictez de la promesa real (requeridos
marcados, sin campos extra implícitos).]

## Endpoints a implementar
| Método | Ruta | Descripción | Roles permitidos |
|--------|------|-------------|-----------------|
[si aplica]

## Componentes frontend a implementar
| Componente | Ruta del archivo | Propósito |
|------------|-----------------|-----------|
[si aplica]

## Tests requeridos
[lista de tests que deben existir al finalizar la fase]

## Escenarios Gherkin (opt-in — solo si la fase tiene criterios de aceptación de negocio)
[Si el CONTEXTO.md/PRD trae criterios de aceptación con reglas de negocio
distinguibles, convertirlos en escenarios Given–When–Then siguiendo
`habilidades/tdd-workflow/recursos/gherkin-bdd.md` y presentarlos al usuario
para validación ANTES de aprobar el plan. Cada escenario validado se referencia
desde la tarea que lo implementa (será su test RED). Omitir esta sección en
fases técnicas puras — Gherkin sin lector de negocio es ceremonia.]

## Riesgos y mitigaciones
| Riesgo | Impacto | Probabilidad | Mitigación |
|--------|---------|-------------|-----------|

## Matriz REQ×T (obligatoria si el CONTEXTO tiene criterios REQ-NN)
[tabla REQ → tareas que lo verifican. Cada tarea declara `**Verifica REQ**: REQ-XX`.
Todo REQ sin tarea = plan NO apto para aprobación (aprobar-plan lo rechaza).
La convención de cierre de cadena (fases ≥12, IDs namespaceados por fase): commits
con prefijo `[F<fase>·T-NN]` y footer `Refs: REQ-<fase>-NN`, tests con marker
`# verifica: REQ-<fase>-NN` (Python) / `// verifica: REQ-<fase>-NN` (JS/TS) —
validada por `scripts/verificar-trazabilidad.js` (acepta también el formato plano
`REQ-NN`/`[T-NN]` de fases 01-11). Omitir solo en CONTEXTOs legacy sin REQ-IDs.]

| REQ | Tareas que lo verifican |
|-----|------------------------|

## Criterios de aceptación de la fase
[copia del CONTEXTO.md, verificados contra el plan]

## Comandos de verificación
[comandos concretos para verificar que la fase funciona: cómo correr tests, cómo verificar endpoints, etc.]
```

## Paso 5 — Revisión del plan generado

Una vez que el agente planificador-swl produce el PLAN.md, ejecuta una revisión con el revisor. Verifica los siguientes puntos de calidad:

### Checklist de revisión del plan

- [ ] ¿Cada tarea es atómica y tiene un archivo o componente destino claro?
- [ ] ¿El orden de implementación respeta las dependencias (BD → service → endpoint → frontend)?
- [ ] ¿Hay criterios de verificación para cada slice?
- [ ] ¿Los criterios de aceptación de la fase están cubiertos por los slices?
- [ ] Si el CONTEXTO tiene REQ-IDs: ¿la matriz REQ×T cubre TODOS los REQ (cero huérfanos)?
- [ ] ¿Los riesgos ALTO del CONTEXTO.md están mitigados en el plan?
- [ ] ¿Hay tests especificados para cada área crítica?
- [ ] ¿Hay tareas HITL claramente marcadas?
- [ ] ¿Los modelos de datos son consistentes con los requisitos del CONTEXTO.md?
- [ ] ¿El estimado de tiempo es realista dado el número y complejidad de tareas?

Si hay deficiencias en el plan (más de 2 puntos fallidos del checklist), itera.

## Paso 6 — Bucle de iteración (máximo 3 rondas)

Mantén un contador de iteraciones. Para cada iteración:

1. Identifica los problemas específicos del plan.
2. Genera instrucciones de mejora precisas para el agente planificador-swl.
3. El agente regenera o ajusta el PLAN.md.
4. Vuelve al Paso 5.

Si después de 3 iteraciones el plan aún tiene problemas:
- Guarda el plan como está con nota "[REQUIERE REVISIÓN HUMANA]" al inicio.
- Reporta al usuario los problemas encontrados con detalle.
- Pregunta si quiere continuar con el plan imperfecto o abortar la planeación.

Actualiza el campo `**Iteración del plan**` en el PLAN.md con cada ciclo.

## Paso 7 — Actualización del HOJA-RUTA.md

Una vez aprobado el plan, actualiza el estado de la fase N en `.planning/HOJA-RUTA.md`:
- Cambia el estado de "Pendiente" a "Planeada"
- Agrega la fecha de planeación
- Agrega el número de slices y estimación total

## Paso 8 — Reporte al usuario

Al terminar, reporta:

1. Ruta absoluta del PLAN.md generado.
2. Resumen del plan:
   - Número de slices
   - Número total de tareas
   - Estimación de tiempo total
   - Número de tareas HITL (si hay, listarlas — requieren decisión humana)
3. Iteraciones que tomó el plan (1 = ideal, 2-3 = normal, 3 con advertencia = revisar contexto).
4. Si hay tareas HITL, presentarlas como lista de decisiones pendientes.
5. Próximo paso: "Cuando estés listo, ejecuta `/swl:ejecutar-fase N`"

## Reglas de comportamiento

- NUNCA generes código fuente en este paso — solo el plan de implementación.
- El plan debe ser ejecutable por cualquier desarrollador que lo lea, sin conocer la conversación.
- Si una tarea es ambigua en el plan, el revisor DEBE rechazarla hasta que sea específica.
- Las estimaciones de tiempo deben ser honestas — no subestimes para complacer al usuario.
- Tareas HITL son aquellas que requieren decisión humana: elección de tecnología, cambio de arquitectura, aprobación de modelo de datos. Márcalas explícitamente.
- NUNCA marques una tarea como completa en el plan — eso lo hace `/swl:ejecutar-fase`.
