@saulwade/swl-ses 1.1.3 → 1.2.0

package/habilidades/planear-fase/SKILL.md

@@ -1,269 +1,299 @@
----
-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.0.0"
-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).
-
----
-
-## 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**
-Preguntar: "Si ejecuto todas las tareas del plan, ¿el criterio de éxito del
-CONTEXTO.md queda satisfecho?" Si la respuesta es no, agregar las tareas faltantes.
-
----
-
-## 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
-
----
-
-## 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
-- **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
-
----
-
-## 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.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-09"
+evolved-by: "aprender"
+evolved-note: "Sección nueva 'Convivencia con placeholders previos del roadmap' — anti-patrón confirmado en auditoría SIGM 2026-05-09 (3 placeholders PLAN-fase-3/4/5.md desactualizados coexistiendo con 0N-PLAN.md reales)"
+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).
+
+---
+
+## 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**
+Preguntar: "Si ejecuto todas las tareas del plan, ¿el criterio de éxito del
+CONTEXTO.md queda satisfecho?" Si la respuesta es no, agregar las tareas faltantes.
+
+---
+
+## 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
+
+---
+
+## 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
+- **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?

package/habilidades/postgresql-experto/SKILL.md

@@ -1,7 +1,12 @@
 ---
 name: postgresql-experto
 description: PostgreSQL avanzado. JSONB, arrays, tipos personalizados, búsqueda de texto completo, window functions, CTEs recursivos, Row Level Security y funciones almacenadas.
-version: "1.0.0"
+version: "1.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-05-05"
+evolved-by: "aprender"
+evolved-note: "3 gotchas nuevos de la sesión SIGM 2026-05-05: RLS bypass por superusuarios, UUIDs hex en seeds, consultar enum_range antes de seedear (L2/L4/L8)"
 herramientasPermitidas: [Read, Grep]
 exclusiones:
   - "No cargar para optimización de queries SQL (EXPLAIN ANALYZE, índices, partitioning) — para optimización cargar `sql-optimizacion`."
@@ -144,6 +149,24 @@ ver [recursos/referencia-completa.md](recursos/referencia-completa.md).
 
 **`SET LOCAL app.empresa_id` para RLS no persiste fuera de una transacción**: `SET LOCAL` establece la variable solo para la transacción actual — si se ejecuta fuera de `BEGIN/COMMIT`, tiene el mismo efecto que `SET` (sesión completa). En aplicaciones con pooling (PgBouncer en transaction mode), la sesión se reutiliza entre conexiones y la variable puede persistir de una petición anterior. Causa: el pool de conexiones reutiliza sessions sin limpiar el estado. Fix: usar SIEMPRE `SET LOCAL` dentro de una transacción explícita (`async with session.begin()`) y verificar que el pool esté en transaction mode.
 
+**RLS NO se aplica a superusuarios — verificar siempre con rol app-only**: `FORCE ROW LEVEL SECURITY` hace que las policies apliquen al OWNER de la tabla, pero los superusuarios SIEMPRE bypassean RLS. En imágenes oficiales (`postgis/postgis`, `postgres`), el rol que se crea por defecto (con `POSTGRES_USER`) es superusuario. Caso real: `SET app.tenant_id = COAT` mostraba 20 predios del tenant MINA porque la query corría como `sigm` superuser. Fix: para verificar aislamiento RLS o exponer al backend de producción, crear un rol app-only sin BYPASSRLS:
+```sql
+CREATE ROLE sigm_app NOLOGIN;
+GRANT USAGE ON SCHEMA <s> TO sigm_app;
+GRANT SELECT, INSERT, UPDATE ON ALL TABLES IN SCHEMA <s> TO sigm_app;
+SET ROLE sigm_app;  -- ahora RLS aplica
+```
+NUNCA usar el rol propietario del schema (suele ser superuser) como rol de aplicación.
+
+**UUIDs deterministas en seeds DEBEN usar SOLO chars hex (0-9, a-f)**: la convención común de "prefijo legible" (`vut00000-...` para valores unitarios terreno, `z0000000-...` para zonas, `tv000000-...` para tipos vialidad) produce strings inválidos como UUID. PostgreSQL rechaza con `invalid input syntax for type uuid: "vut00000-..."`. Detectado en sesión 2026-05-04 con 30+ UUIDs inválidos cascadeando errores en seeds dependientes. Fix: usar dígitos hex como prefijo discriminador (`30000000-` zonas, `40000000-` manzanas, `b0000000-` colonias) o usar `gen_random_uuid()` y resolver vínculos via subqueries (`(SELECT id FROM ... WHERE clave = 'X')`).
+
+**Enum types: nunca presumir variantes — consultar `enum_range` antes de seedear**: PostgreSQL crea tipos enum con variantes específicas que pueden diferir del nombre de dominio. Ejemplos reales: `tipo_suelo` no tiene `'rústico'` (con acento) sino `'rural'`; `tipo_estatus_medidor` no tiene `'funcionando'` sino `'funcional'`. Fix: antes de incluir un valor literal en seed o INSERT, ejecutar:
+```sql
+SELECT enum_range(NULL::<schema>.<tipo>);
+-- {funcional,descompuesto,sin_medidor,retirado}
+```
+Si el valor que necesitas no existe, agregar la variante con `ALTER TYPE ... ADD VALUE` en una migración separada — no improvisar en seeds.
+
 **GIN index en columna JSONB no se usa con el operador `->>` en una cláusula WHERE**: `WHERE metadata ->> 'marca' = 'Dell'` extrae texto y compara — este operador no usa el índice GIN. Solo los operadores `@>`, `?`, `?|`, `?&` usan el índice GIN. Causa: `->>` convierte JSONB a texto y la comparación es una operación de texto sin índice JSONB. Fix: para búsquedas de igualdad con índice, usar `WHERE metadata @> '{"marca": "Dell"}'` que sí usa el índice GIN, o crear un índice de expresión B-Tree sobre `(metadata ->> 'marca')`.
 
 **`FORCE ROW LEVEL SECURITY` no protege al usuario dueño de la tabla (superuser/owner)**: el propietario de la tabla y los superusuarios de PostgreSQL bypasean RLS por defecto aunque esté `FORCE` habilitado. Causa: `FORCE` aplica a todos los usuarios excepto al dueño de la tabla y a superusuarios. Fix: si la aplicación conecta como el dueño de la tabla, cambiar el rol de conexión a un rol de aplicación sin privilegios de dueño (`GRANT CONNECT ON DATABASE ... TO app_user`), no usar el usuario `postgres` para conexiones de aplicación.