@saulwade/swl-ses 2.1.0 → 2.2.1

package/habilidades/planear-fase/SKILL.md

@@ -1,341 +1,336 @@
----
-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?
+---
+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"
+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?