---
name: planear-fase
description: Crea el PLAN.md ejecutable para una fase de desarrollo. Descompone la fase en tareas atómicas con dependencias explícitas, las agrupa en oleadas de ejecución paralela cuando es posible, y aplica verificación goal-backward para garantizar que el plan completo satisface los criterios de éxito definidos en CONTEXTO.md.
version: "1.3.1"
evolved: true
evolved-from: "1.1.0"
evolved-at: "2026-05-10"
evolved-by: "aprender"
evolved-note: "Sección nueva 'Estimación de commits — bloques funcionales, no archivos' — anti-patrón confirmado en sesión ADR-0016 (estimación 12 commits resultó 7 reales, 1.7× sobreestimación por contar archivos en vez de bloques funcionales)"
herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
exclusiones:
  - "No cargar si no existe CONTEXTO.md para la fase — ejecutar `discutir-fase` primero."
  - "No cargar para replanificar una tarea individual dentro de una fase ya en ejecución; eso es desviación moderada, manejar con `ejecutar-fase`."
  - "No cargar para generar backlog de producto o roadmap de alto nivel; usar `nuevo-proyecto` o conversar directamente con el usuario."
  - "No cargar si el usuario pide 'ajustar' el PLAN.md ya aprobado sin nueva información — cada modificación al plan aprobado debe pasar por discusión primero."
evolvable: true  # default para skill estandar
---
# Habilidad: Planear Fase de Desarrollo

## Propósito

Un plan ejecutable no es una lista de tareas — es un grafo de dependencias con
criterios de verificación por tarea. Esta habilidad transforma el CONTEXTO.md de
una fase en un PLAN.md que el agente ejecutor puede seguir sin ambigüedad y sin
interrumpir al usuario para pedir aclaraciones.

## Cuándo activar

- Después de ejecutar `discutir-fase` y tener CONTEXTO.md listo
- Cuando el usuario pide "planear la fase N"
- Cuando un plan existente necesita revisión o replanificación

## Cuándo NO cargar

- No existe `.planning/fases/0N-CONTEXTO.md`; en ese caso usar `discutir-fase` antes. Un PLAN.md sin contexto es un plan con suposiciones implícitas.
- El usuario pide ajustar el PLAN.md aprobado solo porque cambia de opinión en mitad de la ejecución — eso es desviación mayor que requiere pausa en `ejecutar-fase`, no re-planificación completa.
- Se quiere generar únicamente un listado de tareas sin grafo de dependencias ni oleadas; ese backlog plano no es el producto de esta habilidad.
- La fase ya completó todos sus slices y se busca solo actualizar HOJA-RUTA.md — eso lo hace `ejecutar-fase` al cerrar.

## Prerrequisito obligatorio

Leer `.planning/fases/0N-CONTEXTO.md` antes de generar cualquier tarea. Si no existe,
activar primero `discutir-fase`.

---

## Principios de descomposición

### 1. Atomicidad

Una tarea es atómica si:
- Puede completarse en una sola sesión de trabajo (< 2 horas de desarrollo)
- Tiene un único criterio de verificación binario (funciona / no funciona)
- Puede hacerse commit de forma independiente sin romper el sistema

Si una tarea viola alguna de estas condiciones, subdividirla.

### 2. Dependencias explícitas

Cada tarea declara sus dependencias en formato `[T-XX, T-YY]`. Una tarea sin
dependencias puede ejecutarse en la primera oleada. El grafo NO puede tener ciclos.

### 3. Clasificación AFK / HITL

| Tipo | Definición |
|------|-----------|
| AFK (autónoma) | El agente puede completarla sin intervención humana |
| HITL (human-in-the-loop) | Requiere decisión, revisión o input del usuario |

Las tareas HITL son puntos de parada obligatoria en la ejecución.

### 4. Oleadas de ejecución

Agrupa tareas sin dependencias mutuas en la misma oleada. Las tareas de una
oleada pueden ejecutarse en paralelo (o en secuencia rápida si el contexto lo
requiere).

### 5. Estimación de commits — bloques funcionales, no archivos

Al estimar la cantidad de commits que requerirá una fase, contar **bloques
funcionales atómicos** (1 bloque = 1 commit), no archivos modificados. Un
refactor que toca 25 archivos pero implementa 7 bloques funcionales coherentes
genera 7 commits, no 25.

**Heurística**:

- Cada Bn (B1, B2, B3...) del plan = 1 commit atómico (incluye código + tests + manifests asociados)
- Modificaciones cross-archivo en el MISMO bloque funcional van al MISMO commit
- Tests del bloque van CON el bloque, no en commit separado (excepto TDD estricto)
- Bump de versión + docs + CHANGELOG = 1 commit final aparte (B-final)

**Anti-patrón observado** (sesión 2026-05-10, ADR-0016): estimación inicial
"~12 commits, ~25 archivos" para Opción C completa. Resultado real: 7 commits,
25 archivos (1.7× sobreestimación de commits). La cuenta de archivos fue
correcta; la de commits estaba inflada por contar "1 archivo nuevo = 1 commit"
en vez de "1 bloque funcional = 1 commit".

---

## Algoritmo de construcción del plan

**Paso 0 — Recopilar inteligencia del codebase (obligatorio)**
ANTES de planear, investigar el código existente para que el plan sea auto-contenido:

1. Ejecutar `Grep` y `Glob` para encontrar archivos relacionados con la feature
2. Leer los archivos encontrados y extraer:
   - Patrones de implementación reales (con `archivo:línea`)
   - Convenciones de naming, imports, estructura de archivos
   - Tests existentes como referencia de estilo
3. Documentar en el PLAN.md bajo `## Inteligencia del codebase`:
   - **Patrones a imitar**: snippets reales del código existente con `archivo:línea`
   - **Archivos a modificar**: lista con propósito de cada cambio
   - **Dependencias relevantes**: versiones y APIs que se usarán
   - **Convenciones observadas**: naming, estructura, error handling del proyecto

> El plan debe ser auto-contenido: el implementador puede ejecutar cada tarea
> sin investigar el codebase por su cuenta ni tomar decisiones de diseño.

**Paso 1 — Listar entregables**
Del CONTEXTO.md, extraer todos los entregables (features, endpoints, componentes,
migraciones, documentos).

**Paso 2 — Identificar capas**
Para cada entregable de software, descomponerlo en capas estándar:
- Tipos e interfaces / esquemas
- Modelos de datos y migraciones
- Lógica de negocio (services)
- Interfaz externa (endpoints / componentes UI)
- Tests
- Documentación

**Paso 3 — Asignar dependencias**
Aplicar regla: una capa no puede implementarse sin las capas de las que depende.
Orden típico: tipos → modelos → services → endpoints → UI → tests.

**Paso 4 — Agrupar en oleadas**
Usar topological sort mental: la Oleada N contiene todas las tareas cuyas
dependencias están en oleadas anteriores.

**Paso 5 — Verificación goal-backward (matriz REQ×T)**
Cuando el CONTEXTO.md tiene criterios con ID `REQ-NN:` (fases 10-11) o
`REQ-<fase>-NN:` (namespaceados por fase, fases ≥12 — DT-IDS-NAMESPACE), el
goal-backward deja de ser pregunta abierta y se vuelve **matriz verificable**:

1. Cada tarea declara `**Verifica REQ**: REQ-XX[, REQ-YY]` (qué criterios cubre).
2. El PLAN incluye la sección `## Matriz REQ×T` (tabla REQ → tareas que lo verifican).
3. **Todo REQ sin tarea = plan NO apto para aprobación** — agregar la tarea faltante
   o pedir al usuario retirar el REQ del CONTEXTO. `/swl:aprobar-plan` rechaza
   planes con REQ huérfanos.
4. Tareas sin REQ son válidas (infraestructura, refactor habilitante) pero la matriz
   las hace visibles.

En CONTEXTOs legacy sin REQ-IDs (fases 01-09): aplicar la pregunta abierta clásica
("¿el criterio de éxito queda satisfecho?") — cláusula de gracia, sin matriz.

---

## Estructura del PLAN.md

```markdown
# PLAN.md — Fase [N]: [Nombre]
**Generado**: [fecha]
**Basado en**: 0N-CONTEXTO.md
**Criterio de éxito**: [copiado del CONTEXTO.md]

## Resumen del plan
- Total de tareas: N
- Oleadas: M
- Tareas HITL: K (paradas de revisión)
- Duración estimada: X horas / Y días

## Matriz REQ×T (si el CONTEXTO tiene REQ-IDs)

| REQ | Tareas que lo verifican |
|-----|------------------------|
| REQ-01 | T-01, T-03 |
| REQ-02 | T-02 |

Todo REQ del CONTEXTO tiene ≥1 tarea. ✓

---

## Inteligencia del codebase

### Patrones a imitar
| Patrón | Archivo:línea | Ejemplo |
|--------|-------------|---------|
| [nombre del patrón] | `src/services/ejemplo.py:42` | [snippet real del código] |

### Archivos a modificar
| Archivo | Propósito del cambio |
|---------|---------------------|
| `src/...` | [qué se agrega/modifica y por qué] |

### Dependencias relevantes
| Dependencia | Versión | API que se usa |
|------------|---------|---------------|
| [nombre] | [versión] | [funciones/clases] |

### Convenciones observadas
- Naming: [convención real del proyecto]
- Imports: [orden y estilo]
- Error handling: [patrón usado]
- Tests: [framework, estructura, naming]

---

## Oleada 1 — Fundamentos (sin dependencias)

### T-01: [Nombre de la tarea]
- **Tipo**: AFK
- **Verifica REQ**: REQ-01[, REQ-03 — omitir el campo solo en CONTEXTOs legacy sin REQ-IDs]
- **Descripción**: [Qué hacer, sin ambigüedad. Incluir nombres de archivos si aplica.]
- **Entregable verificable**: [Qué existe cuando está completa]
- **Criterio de verificación**: [Comando de verificación o descripción observable]
- **Dependencias**: ninguna
- **Tiempo estimado**: 30 min

### T-02: [Nombre]
- **Tipo**: AFK
- **Descripción**:
- **Entregable verificable**:
- **Criterio de verificación**:
- **Dependencias**: ninguna
- **Tiempo estimado**:

---

## Oleada 2 — [Nombre conceptual]

### T-03: [Nombre]
- **Tipo**: AFK
- **Descripción**:
- **Entregable verificable**:
- **Criterio de verificación**:
- **Dependencias**: [T-01, T-02]
- **Tiempo estimado**:

---

## Oleada N — Verificación y cierre

### T-NN: Verificación goal-backward
- **Tipo**: HITL
- **Descripción**: Revisar que todos los criterios de éxito del CONTEXTO.md estén
  satisfechos. Presentar evidencia al usuario.
- **Entregable verificable**: Reporte de verificación firmado
- **Criterio de verificación**: Usuario confirma aprobación
- **Dependencias**: [todas las tareas anteriores]
- **Tiempo estimado**: 30 min

---

## Matriz de riesgos del plan

| Tarea | Riesgo | Probabilidad | Mitigación |
|-------|--------|-------------|-----------|
|       |        |             |           |

## Tareas excluidas explícitamente
- [Feature X]: diferida a siguiente fase por [razón]

## Notas de diseño del plan
[Decisiones tomadas durante la planeación que el ejecutor debe conocer]
```

---

## Anti-patrones a evitar en el plan

- **Tarea "Implementar módulo X"**: demasiado vaga, no atómica
- **Dependencias circulares**: T-03 depende de T-05 que depende de T-03
- **Tarea sin criterio de verificación**: no se puede saber si está hecha
- **Plan sin oleada de verificación final**: el plan puede estar completo pero
  los criterios de éxito sin satisfacer
- **Mezclar implementación y tests en una sola tarea**: deben ser tareas separadas

---

## Convivencia con placeholders previos del roadmap

Si al iniciar la planeación de la Fase N existe un archivo legado tipo
`PLAN-fase-N.md` (placeholder breve generado al definir el roadmap original),
NO coexistir con el `0N-PLAN.md` recién generado. La presencia de dos archivos
con scopes potencialmente contradictorios confunde a futuros lectores y agentes
(observado en SIGM mayo 2026: placeholder de Fase 5 describía "Portal CMS" del
roadmap v3.0 mientras `05-PLAN.md` ya describía "Complementarios" del roadmap v5.4).

Acciones obligatorias al generar `0N-PLAN.md`:

1. Verificar si existe `PLAN-fase-N.md` placeholder en `.planning/fases/`.
2. Si existe y su scope coincide con el plan nuevo: eliminarlo (`git rm`) ya que
   `0N-PLAN.md` lo supersede con detalle real.
3. Si existe y su scope difiere del roadmap actual (señal de renumeración previa):
   eliminarlo y notificar al usuario que el placeholder estaba desincronizado.
4. Reportar en el output: "Placeholder previo eliminado: `PLAN-fase-N.md`" o
   "Sin placeholder previo detectado".

Esto previene la deuda silenciosa de placeholders viejos coexistiendo con planes
reales — patrón confirmado en auditoría de gaps SIGM 2026-05-09 que detectó 3
placeholders desactualizados (`PLAN-fase-3/4/5.md`).

---

## Checklist antes de entregar el PLAN.md

- [ ] Todas las tareas son atómicas (< 2 horas)
- [ ] Todas las dependencias forman un DAG (sin ciclos)
- [ ] Cada tarea tiene criterio de verificación binario
- [ ] Las tareas HITL están identificadas y justificadas
- [ ] La verificación goal-backward confirma que el plan satisface CONTEXTO.md
- [ ] El plan está guardado en `.planning/fases/0N-PLAN.md`

---

## Gotchas / Errores comunes no obvios

- **Plan sin Paso 0 (inteligencia del codebase)**: el agente genera tareas basadas en supuestos de estructura de archivos sin leer el codebase real. Causa: se omite el Paso 0 por urgencia. Solución: ejecutar `Grep` y `Glob` sobre los módulos que la fase tocará antes de escribir la primera tarea; los nombres de archivos en el PLAN.md deben ser rutas reales, no inventadas.
- **Ciclo en el DAG de dependencias**: T-03 depende de T-05 que depende de T-03, imposibilitando cualquier oleada de inicio. Causa: se asignan dependencias sin verificar acyclicidad. Solución: hacer topological sort mental tras asignar dependencias; si aparece un ciclo, extraer la interfaz compartida como una tarea T-00 sin dependencias.
- **Oleada de verificación final mezclada con implementación**: la tarea de verificación goal-backward se agrupa en la misma oleada que la última tarea de implementación, permitiendo que el ejecutor la omita. Causa: se trata la verificación como un paso más, no como una oleada separada. Solución: la oleada de verificación siempre es la última, con dependencias de todas las oleadas anteriores.
- **Criterio de verificación observable por el ejecutor, no por el usuario**: el criterio dice "que funcione correctamente" en lugar de un comando ejecutable. Causa: redacción laxa. Solución: el criterio debe ser un comando concreto (`pytest tests/modulo/ -v`, `curl http://localhost:8000/endpoint`) o una observación binaria ("la tabla X aparece en alembic history").
- **PLAN.md aprobado sin estado: aprobado en frontmatter**: el ejecutor inicia sin verificar que el plan está aprobado, lo que puede llevar a ejecutar un plan en borrador. Causa: el frontmatter no incluye `estado: aprobado`. Solución: agregar `estado: aprobado` al frontmatter antes de entregar al ejecutor, ya que `seguridad-agentes.md` exige esta verificación.

## Reglas anti-placeholder (obligatorio)

Un plan con placeholders es un defecto. El implementador debe poder ejecutar cada tarea
sin tomar decisiones de diseno ni pedir aclaraciones.

### Placeholders prohibidos
- `TBD`, `PENDIENTE`, `por definir`, `implementar despues`
- "agregar manejo de errores" (debe decir QUE errores y COMO)
- "agregar validacion" (debe decir CUAL validacion con CUAL regla)
- "similar a la tarea N" (debe repetir el contenido relevante)
- "agregar tests apropiados" (debe especificar QUE tests con QUE escenarios)
- Referencias a tipos/funciones no definidos en el plan

### Auto-revision antes de entregar
1. `grep -rni "TBD\|PENDIENTE\|por definir\|implementar despues" PLAN.md`
2. Cada tarea: el implementador puede ejecutarla sin preguntas?
3. Interfaces entre tareas: tipos y nombres consistentes?
4. Cada requisito tiene al menos una tarea?
