@saulwade/swl-ses 1.0.0

package/habilidades/diagrama-arquitectura/SKILL.md

@@ -0,0 +1,165 @@
+---
+name: diagrama-arquitectura
+description: >
+  Genera diagramas de arquitectura profesionales como archivos HTML auto-contenidos
+  con gráficos SVG inline. Usar cuando se necesiten diagramas de sistema, infraestructura
+  cloud, topología de red, flujos de seguridad, o cualquier diagrama técnico que muestre
+  componentes y sus relaciones. Ideal para documentación, presentaciones y onboarding.
+version: "1.0.0"
+herramientasPermitidas: [Read, Grep]
+user-invocable: false
+license: MIT (basado en architecture-diagram-generator de Cocoon AI)
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para diagramas de flujo de datos ETL o pipelines de datos — para diagramas de datos cargar `datos-etl` que incluye su propia notación de capas."
+  - "No cargar para diagramas de entidad-relación de base de datos — para ER cargar `generacion-mermaid` con sintaxis erDiagram o `dbml-experto`."
+  - "No cargar para wireframes o mockups de interfaz de usuario — para UI prototyping cargar `wireframes-flujos`."
+  - "No cargar para diagramas de secuencia de API o flujos de autenticación en texto plano (Mermaid) — para diagramas Mermaid cargar `generacion-mermaid`."
+---
+# Diagrama de Arquitectura
+
+Genera diagramas técnicos de arquitectura como archivos HTML standalone con SVG inline y CSS.
+Basado en architecture-diagram-generator (MIT, Cocoon AI) — adaptado al sistema SWL.
+
+## Cuándo NO cargar
+
+- Los diagramas son de entidad-relación de base de datos: cargar `generacion-mermaid` (sintaxis `erDiagram`) o `dbml-experto`.
+- Los diagramas son de flujo de datos ETL o pipelines de datos: `datos-etl` tiene su propia notación Medallion.
+- Los diagramas son wireframes o mockups de UI: cargar `wireframes-flujos`.
+- Los diagramas son de secuencia o flujo en texto Mermaid: cargar `generacion-mermaid`.
+
+## Cuándo cargar
+
+- El usuario pide un diagrama de arquitectura del proyecto
+- `arquitecto-swl` necesita visualizar la arquitectura propuesta
+- `documentador-swl` genera documentación visual
+- `/swl:wiki` o `/swl:dashboard` necesitan representación gráfica
+- Cualquier tarea de RFC, ADR o propuesta arquitectónica
+
+## Sistema de diseño
+
+### Paleta semántica de colores
+
+| Tipo de componente | Fill (rgba) | Stroke |
+|-------------------|-------------|--------|
+| Frontend | `rgba(8, 51, 68, 0.4)` | `#22d3ee` (cyan-400) |
+| Backend | `rgba(6, 78, 59, 0.4)` | `#34d399` (emerald-400) |
+| Base de datos | `rgba(76, 29, 149, 0.4)` | `#a78bfa` (violet-400) |
+| Cloud/AWS/GCP/Azure | `rgba(120, 53, 15, 0.3)` | `#fbbf24` (amber-400) |
+| Seguridad | `rgba(136, 19, 55, 0.4)` | `#fb7185` (rose-400) |
+| Bus de mensajes | `rgba(251, 146, 60, 0.3)` | `#fb923c` (orange-400) |
+| Externo/Genérico | `rgba(30, 41, 59, 0.5)` | `#94a3b8` (slate-400) |
+
+### Tipografía
+
+JetBrains Mono (monoespaciada, estética técnica):
+```html
+<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+```
+
+Tamaños: 12px nombres de componentes, 9px sub-etiquetas, 8px anotaciones, 7px etiquetas pequeñas.
+
+### Elementos visuales
+
+**Fondo:** `#020617` (slate-950) con patrón de grilla sutil:
+```svg
+<pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+  <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
+</pattern>
+```
+
+**Cajas de componentes:** Rectángulos redondeados (`rx="6"`) con stroke 1.5px, fills semi-transparentes.
+
+**Grupos de seguridad:** Stroke punteado (`stroke-dasharray="4,4"`), fill transparente, color rose.
+
+**Límites de región:** Stroke punteado largo (`stroke-dasharray="8,4"`), color amber, `rx="12"`.
+
+**Flechas:** Marker SVG para puntas:
+```svg
+<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+  <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
+</marker>
+```
+
+**Z-order de flechas:** Dibujar flechas temprano en el SVG (después de la grilla) para que queden detrás de componentes.
+
+**Enmascarar flechas bajo fills transparentes:** Dado que las cajas usan fills semi-transparentes, las flechas se ven a través. Para enmascarar, dibujar un rect opaco (`fill="#0f172a"`) debajo del rect estilizado:
+```svg
+<!-- Fondo opaco para enmascarar flechas -->
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="#0f172a"/>
+<!-- Componente estilizado encima -->
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
+```
+
+### Reglas de espaciado
+
+**CRÍTICO:** Al apilar componentes verticalmente, asegurar espaciado correcto:
+
+- **Altura estándar de componente:** 60px para servicios, 80-120px para componentes grandes
+- **Gap vertical mínimo entre componentes:** 40px
+- **Conectores inline (buses de mensajes):** Colocar EN el gap, sin solapar
+- **Leyendas:** FUERA de todos los boundary boxes, al menos 20px debajo del más bajo
+- **ViewBox SVG:** Extender si es necesario para acomodar leyendas
+
+### Patrón de componente
+
+```svg
+<rect x="X" y="Y" width="W" height="H" rx="6" fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
+<text x="CENTER_X" y="Y+20" fill="white" font-size="11" font-weight="600" text-anchor="middle">ETIQUETA</text>
+<text x="CENTER_X" y="Y+36" fill="#94a3b8" font-size="9" text-anchor="middle">sub-etiqueta</text>
+```
+
+### Estructura del layout
+
+1. **Encabezado** — Título con punto pulsante, subtítulo
+2. **Diagrama SVG principal** — Contenido en tarjeta con borde redondeado
+3. **Tarjetas de resumen** — Grid de 3 tarjetas debajo con detalles clave
+4. **Pie** — Línea de metadatos mínima
+
+## Template
+
+Usar y personalizar el template en `assets/template.html`. Puntos de personalización:
+
+1. Actualizar `<title>` y texto del encabezado
+2. Modificar dimensiones del viewBox SVG si es necesario (default: `1000 x 680`)
+3. Agregar/quitar/reposicionar cajas de componentes
+4. Dibujar flechas de conexión entre componentes
+5. Actualizar las tres tarjetas de resumen
+6. Actualizar metadatos del pie
+
+## Salida
+
+Siempre producir un archivo `.html` auto-contenido con:
+- CSS embebido (sin hojas de estilo externas excepto Google Fonts)
+- SVG inline (sin imágenes externas)
+- Sin JavaScript requerido (animaciones puras CSS)
+
+El archivo debe renderizar correctamente al abrirlo directamente en cualquier navegador moderno.
+
+## Flujo de uso en swl-ses
+
+```
+1. arquitecto-swl analiza el codebase → genera descripción textual de la arquitectura
+2. Se carga Skill("diagrama-arquitectura")
+3. Se genera HTML personalizado a partir del template + descripción
+4. Se guarda en .planning/diagramas/ o docs/ del proyecto
+5. Se actualiza en cada fase de verificación si hay cambios estructurales
+```
+
+## Casos de uso
+
+- **Documentación de proyecto:** Diagrama visual para README o wiki
+- **Propuesta arquitectónica:** Visualizar RFC o ADR antes de implementar
+- **Onboarding:** Mostrar a nuevos desarrolladores cómo se conectan los componentes
+- **Revisión de arquitectura:** Validar visualmente que el diseño cumpla requisitos
+- **Presentaciones:** Diagrama profesional sin depender de herramientas externas (Lucidchart, Draw.io)
+
+## Gotchas / Errores comunes no obvios
+
+**Las flechas de conexión se ven a través de los componentes porque los fills son semi-transparentes**: cuando las flechas se dibujan en el SVG después de las cajas, se ven detrás de los fills transparentes y el diagrama parece correcto en el SVG editor, pero en el browser la línea atraviesa visualmente la caja. Causa: el orden de elementos SVG determina el z-order — los elementos dibujados después están "encima". Fix: dibujar todas las flechas **antes** de las cajas en el SVG (justo después del patrón de grilla). Además, para cada caja, agregar un `<rect>` opaco (`fill="#0f172a"`) detrás del `<rect>` con fill semitransparente para enmascarar las líneas que pasan por debajo.
+
+**El viewBox del SVG es muy pequeño y las leyendas o etiquetas largas se recortan fuera del área visible**: si el diagrama tiene más componentes de los previstos, o los nombres son más largos que los del template, los elementos se solapan o quedan fuera del borde derecho/inferior del SVG. Causa: el viewBox por defecto `0 0 1000 680` es un punto de partida, no un límite flexible. Fix: calcular el espacio necesario antes de definir el viewBox. La leyenda debe quedar al menos 20px debajo del componente más bajo. Si el diagrama crece, extender el viewBox verticalmente: `0 0 1000 800` o más.
+
+**Los textos centrados en componentes se desplazan cuando los nombres tienen acento o caracteres Unicode**: `text-anchor="middle"` en SVG calcula el centro basado en el ancho visual del texto, pero algunos navegadores calculan el ancho de manera diferente para caracteres no ASCII. Causa: SVG delega el cálculo de ancho de texto al motor de renderizado del navegador, que puede diferir entre Chrome, Firefox y Safari para caracteres especiales. Fix: para garantizar consistencia, usar nombres de componentes en inglés o en formato `Servicio: Nombre` donde el componente crítico es la palabra en inglés. Si se necesitan nombres en español, verificar el diagrama en Chrome y Firefox antes de publicarlo.
+
+**El archivo HTML generado no renderiza correctamente al compartirlo por correo o subirlo a Confluence**: algunos sistemas de correo y wikis sanitizan el HTML y eliminan etiquetas `<svg>` o atributos inline de estilo. Causa: el HTML auto-contenido con SVG inline es correcto en el browser, pero los sanitizadores de contenido de Confluence/Outlook remueven elementos SVG por política de seguridad. Fix: para compartir en estas plataformas, renderizar el HTML en un browser y hacer captura de pantalla como PNG, o usar el comando de exportación de Confluence que soporta SVG como adjunto separado.

package/habilidades/diagrama-arquitectura/assets/template.html

@@ -0,0 +1,276 @@
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>[NOMBRE DEL PROYECTO] — Diagrama de Arquitectura</title>
+  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
+  <style>
+    * {
+      margin: 0;
+      padding: 0;
+      box-sizing: border-box;
+    }
+
+    body {
+      font-family: 'JetBrains Mono', monospace;
+      background: #020617;
+      min-height: 100vh;
+      padding: 2rem;
+      color: white;
+    }
+
+    .container {
+      max-width: 1200px;
+      margin: 0 auto;
+    }
+
+    .header {
+      margin-bottom: 2rem;
+    }
+
+    .header-row {
+      display: flex;
+      align-items: center;
+      gap: 1rem;
+      margin-bottom: 0.5rem;
+    }
+
+    .pulse-dot {
+      width: 12px;
+      height: 12px;
+      background: #22d3ee;
+      border-radius: 50%;
+      animation: pulse 2s infinite;
+    }
+
+    @keyframes pulse {
+      0%, 100% { opacity: 1; }
+      50% { opacity: 0.5; }
+    }
+
+    h1 {
+      font-size: 1.5rem;
+      font-weight: 700;
+      letter-spacing: -0.025em;
+    }
+
+    .subtitle {
+      color: #94a3b8;
+      font-size: 0.875rem;
+      margin-left: 1.75rem;
+    }
+
+    .diagram-container {
+      background: rgba(15, 23, 42, 0.5);
+      border-radius: 1rem;
+      border: 1px solid #1e293b;
+      padding: 1.5rem;
+      overflow-x: auto;
+    }
+
+    svg {
+      width: 100%;
+      min-width: 900px;
+      display: block;
+    }
+
+    .cards {
+      display: grid;
+      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+      gap: 1rem;
+      margin-top: 2rem;
+    }
+
+    .card {
+      background: rgba(15, 23, 42, 0.5);
+      border-radius: 0.75rem;
+      border: 1px solid #1e293b;
+      padding: 1.25rem;
+    }
+
+    .card-header {
+      display: flex;
+      align-items: center;
+      gap: 0.5rem;
+      margin-bottom: 0.75rem;
+    }
+
+    .card-dot {
+      width: 8px;
+      height: 8px;
+      border-radius: 50%;
+    }
+
+    .card-dot.cyan { background: #22d3ee; }
+    .card-dot.emerald { background: #34d399; }
+    .card-dot.violet { background: #a78bfa; }
+    .card-dot.amber { background: #fbbf24; }
+    .card-dot.rose { background: #fb7185; }
+
+    .card h3 {
+      font-size: 0.875rem;
+      font-weight: 600;
+    }
+
+    .card ul {
+      list-style: none;
+      color: #94a3b8;
+      font-size: 0.75rem;
+    }
+
+    .card li {
+      margin-bottom: 0.375rem;
+    }
+
+    .footer {
+      text-align: center;
+      margin-top: 1.5rem;
+      color: #475569;
+      font-size: 0.75rem;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <!-- Encabezado -->
+    <div class="header">
+      <div class="header-row">
+        <div class="pulse-dot"></div>
+        <h1>[NOMBRE DEL PROYECTO] — Arquitectura</h1>
+      </div>
+      <p class="subtitle">[Descripción del subtítulo]</p>
+    </div>
+
+    <!-- Diagrama principal -->
+    <div class="diagram-container">
+      <svg viewBox="0 0 1000 680">
+        <!-- Definiciones -->
+        <defs>
+          <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+            <polygon points="0 0, 10 3.5, 0 7" fill="#64748b" />
+          </marker>
+          <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+            <path d="M 40 0 L 0 0 0 40" fill="none" stroke="#1e293b" stroke-width="0.5"/>
+          </pattern>
+        </defs>
+
+        <!-- Grilla de fondo -->
+        <rect width="100%" height="100%" fill="url(#grid)" />
+
+        <!-- ===============================================================
+             COMPONENTES — Copiar y personalizar estos patrones
+             =============================================================== -->
+
+        <!-- Componente externo/genérico -->
+        <rect x="30" y="280" width="100" height="50" rx="6" fill="rgba(30, 41, 59, 0.5)" stroke="#94a3b8" stroke-width="1.5"/>
+        <text x="80" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Usuarios</text>
+        <text x="80" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">Navegador/Móvil</text>
+
+        <!-- Componente de seguridad -->
+        <rect x="30" y="80" width="100" height="60" rx="6" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1.5"/>
+        <text x="80" y="105" fill="white" font-size="11" font-weight="600" text-anchor="middle">Auth Provider</text>
+        <text x="80" y="121" fill="#94a3b8" font-size="9" text-anchor="middle">OAuth 2.0</text>
+
+        <!-- Límite de región/cloud -->
+        <rect x="160" y="40" width="820" height="620" rx="12" fill="rgba(251, 191, 36, 0.05)" stroke="#fbbf24" stroke-width="1" stroke-dasharray="8,4"/>
+        <text x="172" y="58" fill="#fbbf24" font-size="10" font-weight="600">Región Cloud</text>
+
+        <!-- Servicio cloud -->
+        <rect x="200" y="280" width="110" height="50" rx="6" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1.5"/>
+        <text x="255" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">CDN</text>
+        <text x="255" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">CloudFront</text>
+
+        <!-- Backend -->
+        <rect x="510" y="280" width="110" height="50" rx="6" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1.5"/>
+        <text x="565" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">API Server</text>
+        <text x="565" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">FastAPI :8000</text>
+
+        <!-- Base de datos -->
+        <rect x="700" y="280" width="120" height="50" rx="6" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1.5"/>
+        <text x="760" y="300" fill="white" font-size="11" font-weight="600" text-anchor="middle">Base de datos</text>
+        <text x="760" y="316" fill="#94a3b8" font-size="9" text-anchor="middle">PostgreSQL</text>
+
+        <!-- Frontend -->
+        <rect x="200" y="520" width="200" height="110" rx="8" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1.5"/>
+        <text x="300" y="545" fill="white" font-size="12" font-weight="600" text-anchor="middle">Frontend</text>
+        <text x="300" y="565" fill="#94a3b8" font-size="9" text-anchor="middle">React + TypeScript</text>
+
+        <!-- ===============================================================
+             FLECHAS
+             =============================================================== -->
+        <line x1="130" y1="305" x2="198" y2="305" stroke="#22d3ee" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <text x="164" y="299" fill="#94a3b8" font-size="9" text-anchor="middle">HTTPS</text>
+
+        <line x1="310" y1="305" x2="508" y2="305" stroke="#34d399" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <line x1="620" y1="305" x2="698" y2="305" stroke="#a78bfa" stroke-width="1.5" marker-end="url(#arrowhead)"/>
+        <text x="655" y="299" fill="#94a3b8" font-size="9">TLS</text>
+
+        <!-- ===============================================================
+             LEYENDA
+             =============================================================== -->
+        <text x="720" y="70" fill="white" font-size="10" font-weight="600">Leyenda</text>
+
+        <rect x="720" y="82" width="16" height="10" rx="2" fill="rgba(8, 51, 68, 0.4)" stroke="#22d3ee" stroke-width="1"/>
+        <text x="742" y="90" fill="#94a3b8" font-size="8">Frontend</text>
+
+        <rect x="720" y="98" width="16" height="10" rx="2" fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" stroke-width="1"/>
+        <text x="742" y="106" fill="#94a3b8" font-size="8">Backend</text>
+
+        <rect x="720" y="114" width="16" height="10" rx="2" fill="rgba(120, 53, 15, 0.3)" stroke="#fbbf24" stroke-width="1"/>
+        <text x="742" y="122" fill="#94a3b8" font-size="8">Servicio Cloud</text>
+
+        <rect x="720" y="130" width="16" height="10" rx="2" fill="rgba(76, 29, 149, 0.4)" stroke="#a78bfa" stroke-width="1"/>
+        <text x="742" y="138" fill="#94a3b8" font-size="8">Base de datos</text>
+
+        <rect x="720" y="146" width="16" height="10" rx="2" fill="rgba(136, 19, 55, 0.4)" stroke="#fb7185" stroke-width="1"/>
+        <text x="742" y="154" fill="#94a3b8" font-size="8">Seguridad</text>
+      </svg>
+    </div>
+
+    <!-- Tarjetas informativas -->
+    <div class="cards">
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot rose"></div>
+          <h3>Seguridad</h3>
+        </div>
+        <ul>
+          <li>- Autenticación OAuth 2.0</li>
+          <li>- TLS en tránsito</li>
+          <li>- Cifrado en reposo</li>
+        </ul>
+      </div>
+
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot amber"></div>
+          <h3>Infraestructura</h3>
+        </div>
+        <ul>
+          <li>- CDN para activos estáticos</li>
+          <li>- Auto-scaling horizontal</li>
+          <li>- Monitoreo centralizado</li>
+        </ul>
+      </div>
+
+      <div class="card">
+        <div class="card-header">
+          <div class="card-dot violet"></div>
+          <h3>Datos</h3>
+        </div>
+        <ul>
+          <li>- PostgreSQL principal</li>
+          <li>- Backups automatizados</li>
+          <li>- Réplica de lectura</li>
+        </ul>
+      </div>
+    </div>
+
+    <!-- Pie -->
+    <p class="footer">
+      [Nombre del proyecto] — Generado con swl-ses
+    </p>
+  </div>
+</body>
+</html>

package/habilidades/discutir-fase/SKILL.md

@@ -0,0 +1,188 @@
+---
+name: discutir-fase
+description: Cuestionario adaptativo que se ejecuta antes de planear una fase de desarrollo. Extrae decisiones técnicas y de negocio del usuario, clasifica respuestas como "cerradas" (no negociables) o "abiertas" (decisión delegada al agente), y produce un archivo CONTEXTO.md que alimenta al planificador.
+version: "1.0.0"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar si el usuario ya tiene un CONTEXTO.md poblado para la fase en curso — ir directo a `planear-fase`."
+  - "No cargar para tareas one-shot que no forman parte de un plan de fases (ej: 'arregla este bug')."
+  - "No cargar para diagnóstico rápido o exploración libre; en ese caso usar `workflow-claude-code` o simplemente conversar."
+  - "No cargar si la fase ya está en ejecución y se busca retomar el estado; usar `ejecutar-fase` + ESTADO.md."
+evolvable: true  # default para skill estandar
+---
+# Habilidad: Discutir Fase Antes de Planear
+
+## Propósito
+
+El planificador no puede crear un plan ejecutable sin contexto de decisiones.
+Esta habilidad hace las preguntas correctas, en el orden correcto, para extraer
+ese contexto antes de que se escriba una sola línea del PLAN.md. Evita el
+antipatrón de planear con suposiciones implícitas que luego se contradicen.
+
+## Cuándo activar
+
+- Antes de ejecutar la habilidad `planear-fase`
+- Cuando el usuario dice "vamos a la siguiente fase" sin dar detalles
+- Cuando el HOJA-RUTA.md describe una fase de forma vaga
+- Cuando hay decisiones de diseño no resueltas que bloquean el plan
+
+## Cuándo NO cargar
+
+- El CONTEXTO.md de la fase ya existe en `.planning/fases/` con decisiones cerradas — ir directo a `planear-fase`.
+- El usuario pide hacer una tarea puntual sin ciclo de fases formal (no tiene HOJA-RUTA.md).
+- La fase ya está en ejecución; las preguntas de esta habilidad son pre-planeación, no retoma. Usar `ejecutar-fase`.
+- El usuario quiere diagnóstico rápido de qué sigue; no se necesita el cuestionario completo, basta revisar HOJA-RUTA.md.
+
+---
+
+## Protocolo de entrevista adaptativa
+
+### Regla 1 — Máximo 4 preguntas por mensaje
+
+No bombardear al usuario. Agrupa preguntas relacionadas. Espera respuesta antes
+de continuar con el siguiente bloque.
+
+### Regla 2 — Clasifica cada respuesta al recibirla
+
+| Tipo | Definición | Cómo registrar |
+|------|-----------|---------------|
+| CERRADA | Decisión no negociable del usuario | `[CERRADA]` en CONTEXTO.md |
+| ABIERTA | El usuario delega la decisión al agente | `[ABIERTA - decisión del agente]` |
+| PENDIENTE | Sin respuesta todavía | `[PENDIENTE - bloquea plan]` |
+
+### Regla 3 — No avanzar con PENDIENTE en ítems críticos
+
+Si una decisión es crítica para el plan y está marcada PENDIENTE, detente y
+notifica explícitamente antes de proceder.
+
+---
+
+## Bloque 1 — Contexto de la fase (siempre preguntar)
+
+1. ¿Cuál es el objetivo principal de esta fase en una oración?
+2. ¿Qué debe existir y funcionar al finalizar esta fase para considerarla exitosa?
+3. ¿Hay alguna restricción de tiempo (deadline, demo, sprint)?
+4. ¿Alguna decisión tomada en fases anteriores afecta el alcance de esta?
+
+---
+
+## Bloque 2 — Decisiones técnicas (preguntar si aplica)
+
+Preguntar solo si la fase involucra código nuevo o cambios de arquitectura:
+
+5. ¿Se crean nuevas entidades de base de datos? ¿Cuáles?
+6. ¿Se expone una nueva API pública o se modifican endpoints existentes?
+7. ¿Hay integraciones con sistemas externos en esta fase?
+8. ¿Se espera algún cambio en la autenticación o los permisos?
+9. ¿Hay requerimientos de rendimiento específicos para esta fase?
+
+---
+
+## Bloque 3 — Calidad y proceso (preguntar si aplica)
+
+Preguntar si el equipo tiene proceso definido o si la fase es crítica:
+
+10. ¿Se requieren tests unitarios, de integración o ambos en esta fase?
+11. ¿Hay features que requieren revisión de seguridad antes de merge?
+12. ¿Se va a hacer deployment de esta fase de forma independiente o junto con otras?
+13. ¿Hay features marcadas como "nice to have" que pueden salir del scope si hay tiempo?
+
+---
+
+## Bloque 4 — Dependencias y riesgos (siempre preguntar)
+
+14. ¿Hay tareas en esta fase que dependen de trabajo de otro equipo o sistema externo?
+15. ¿Hay algún riesgo técnico conocido que podría bloquear alguna tarea?
+16. ¿Hay deuda técnica existente que DEBE resolverse antes o durante esta fase?
+
+---
+
+## Técnicas de extracción cuando las respuestas son vagas
+
+### Si el usuario dice "como siempre" o "igual que antes"
+Preguntar: "¿Puedes confirmar qué patrón específico seguimos? Quiero asegurarme
+de documentarlo correctamente en el CONTEXTO.md."
+
+### Si el usuario dice "lo que tú veas mejor"
+Registrar como ABIERTA y anotar la decisión que tomará el agente con su
+justificación en el CONTEXTO.md.
+
+### Si el usuario da información contradictoria
+Señalar la contradicción explícitamente: "Mencionaste X antes pero ahora Y.
+¿Cuál aplica para esta fase?"
+
+---
+
+## Plantilla de salida: `.planning/fases/0N-CONTEXTO.md`
+
+```markdown
+# CONTEXTO.md — Fase [N]: [Nombre]
+**Fecha de discusión**: [fecha]
+**Participantes**: [usuario, agente]
+
+## Objetivo de la fase
+[Respuesta del usuario a pregunta 1 y 2]
+
+## Criterio de éxito
+[Lo que debe existir y funcionar al terminar]
+
+## Restricciones de tiempo
+- Deadline: [fecha o "sin deadline definido"]
+- Sprint: [número si aplica]
+
+## Decisiones técnicas
+
+| ID  | Decisión | Tipo | Notas |
+|-----|---------|------|-------|
+| D-01 | [decisión] | CERRADA | [contexto] |
+| D-02 | [decisión] | ABIERTA | [el agente decidirá X porque Y] |
+| D-03 | [decisión] | PENDIENTE | [bloquea tarea T] |
+
+## Alcance confirmado
+### Incluido en esta fase
+- Feature A
+- Feature B
+
+### Explícitamente excluido
+- Feature C (pasa a siguiente fase)
+
+## Dependencias externas
+| Dependencia | Equipo/Sistema | Estado | Riesgo |
+|------------|---------------|--------|--------|
+|            |               |        |        |
+
+## Riesgos identificados
+| Riesgo | Probabilidad | Impacto | Mitigación |
+|--------|-------------|---------|-----------|
+|        |             |         |           |
+
+## Deuda técnica a resolver
+- [ ] [deuda 1] — obligatoria
+- [ ] [deuda 2] — si hay tiempo
+
+## Decisiones pendientes (bloqueos)
+- [ ] [decisión] — necesaria antes de [tarea]
+
+## Notas de la discusión
+[Contexto adicional, cambios de opinión, razonamiento detrás de decisiones]
+```
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Respuesta "como siempre" archivada sin verificar**: el usuario dice "igual que en la fase anterior" y el agente asume que el patrón aplica sin leer el CONTEXTO.md previo. Causa: confianza en el modelo mental sin verificación. Solución: siempre leer el CONTEXTO.md de la fase anterior antes de aceptar la respuesta.
+- **Decisiones PENDIENTE que bloquean el plan ignoradas**: el agente avanza a `planear-fase` con ítems de los Bloques 1 o 4 en estado PENDIENTE. Causa: no se aplicó la Regla 3. Solución: verificar explícitamente que ningún ítem crítico quede PENDIENTE antes de cerrar la discusión.
+- **CONTEXTO.md escrito sin confirmar criterio de éxito verificable**: el usuario da un objetivo vago ("mejorar rendimiento") y se registra sin cuestionarlo. Causa: el agente no aplica la prueba de observabilidad. Solución: pedir reformulación hasta que el criterio sea binario y observable.
+- **Bloque 2 omitido cuando sí aplica**: si la fase incluye nuevas entidades de BD o endpoints pero el agente saltó el Bloque 2 por considerarlo "técnico". Causa: interpretación laxa de "preguntar si aplica". Solución: si hay código nuevo, el Bloque 2 siempre aplica.
+
+## Checklist de cierre de discusión
+
+Antes de pasar a `planear-fase`, verificar:
+
+- [ ] El objetivo de la fase es una oración accionable (no "mejorar el sistema")
+- [ ] El criterio de éxito es verificable (observable sin ambigüedad)
+- [ ] No hay decisiones PENDIENTE en ítems de los Bloques 1 y 4
+- [ ] Todas las decisiones ABIERTA tienen una nota de qué decidirá el agente
+- [ ] Las features excluidas están documentadas explícitamente
+- [ ] CONTEXTO.md guardado en `.planning/fases/`