@saulwade/swl-ses 1.0.0

package/habilidades/brainstorming/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: brainstorming
+description: >
+  Brainstorming estructurado para diseño de features, arquitectura y soluciones técnicas.
+  Guía un proceso de ideación: preguntas clarificadoras, propuestas de enfoques,
+  visualización HTML, especificación y transición a plan. Cargar ANTES de implementar
+  cualquier feature no trivial o decisión de arquitectura.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+evolvable: true  # default para skill estandar
+exclusiones:
+  - "No cargar para bugs o errores con causa conocida — para debugging cargar `depurador-swl` o el skill de diagnóstico del stack."
+  - "No cargar para crear el plan de implementación — el brainstorming produce la spec aprobada; el plan lo genera `/swl:planear-fase`."
+  - "No cargar para decisiones de infraestructura operativa (despliegue, cloud, CI/CD) — para IaC cargar `terraform-experto` o `ci-cd-pipelines`."
+  - "No cargar cuando el diseño ya está aprobado y documentado en un PLAN.md vigente — ir directo a implementación."
+---
+# Habilidad: Brainstorming Estructurado
+
+Guía un proceso de ideación disciplinado que va de la ambigüedad al diseño aprobado,
+pasando por preguntas clarificadoras, comparación de enfoques y una spec escrita.
+Previene retrabajo al asegurar que el equipo acuerda el "qué" antes de escribir el "cómo".
+
+## Cuándo NO cargar
+
+- La causa del problema es conocida y se busca solución técnica directa: cargar el skill del stack (`fastapi-experto`, `angular-moderno`, etc.) o `depurador-swl`.
+- El diseño ya está documentado en un PLAN.md aprobado: ir a `/swl:ejecutar-fase` directamente.
+- La tarea es generar el plan con slices: eso lo hace `/swl:planear-fase`, no este skill.
+- La decisión es de infraestructura operativa (cloud, CI/CD, despliegue): cargar `terraform-experto`, `ci-cd-pipelines` o `kubernetes-orquestacion`.
+
+## Cuándo cargar
+
+Invoca `Skill("brainstorming")` cuando:
+
+- El usuario pide "brainstorming", "lluvia de ideas", "explorar opciones" o "diseñar X"
+- Antes de implementar cualquier feature que requiera decisiones de diseño no triviales
+- Antes de decisiones de arquitectura con múltiples alternativas viables
+- Cuando los requisitos son ambiguos o contradictorios
+- Cuando se evalúan tecnologías o patrones para un problema nuevo en el proyecto
+
+## Flujo obligatorio (GATE: no saltar ningún paso)
+
+Los 7 pasos se ejecutan en orden. Cada paso tiene una condición de salida.
+No avanzar al siguiente paso sin cumplir la condición.
+
+### Paso 1 — Explorar contexto
+
+Antes de preguntar nada al usuario:
+
+- Leer archivos relevantes: README, docs, commits recientes, código existente en el área
+- Identificar el dominio, las restricciones tecnológicas y los patrones ya establecidos
+- Detectar decisiones previas de arquitectura (ADRs en `.planning/adrs/`)
+
+Condición de salida: el agente puede describir el problema en sus propias palabras.
+
+### Paso 2 — Preguntas clarificadoras
+
+Reglas de formulación:
+
+- Preferir opciones enumeradas sobre preguntas abiertas: "¿A o B o C?" en vez de "¿Cómo?"
+- Máximo 3 preguntas por mensaje — no bombardear
+- Una pregunta a la vez si son preguntas de decisión crítica
+- No preguntar lo que ya puede inferirse del código o los docs
+
+Preguntas mínimas a responder antes de proponer enfoques:
+
+| # | Pregunta | Por qué importa |
+|---|----------|----------------|
+| 1 | ¿Qué problema resuelve esta feature para el usuario final? | Define el criterio de éxito |
+| 2 | ¿Quién la usará y con qué frecuencia? | Afecta decisiones de UX y performance |
+| 3 | ¿Hay restricciones de tiempo, tecnología o compatibilidad? | Elimina enfoques inviables |
+| 4 | ¿Cómo sabremos que funciona correctamente? | Define los criterios de aceptación |
+
+Condición de salida: las 4 preguntas tienen respuesta (cerrada o delegada al agente).
+
+### Paso 3 — Proponer 2-3 enfoques
+
+Cada enfoque incluye:
+
+- **Nombre**: identificador corto y descriptivo
+- **Descripción**: cómo resuelve el problema (2-4 oraciones)
+- **Pros**: lista de ventajas concretas
+- **Contras**: lista de desventajas y riesgos reales
+
+Tabla comparativa obligatoria:
+
+| Aspecto | Enfoque A | Enfoque B | Enfoque C |
+|---------|-----------|-----------|-----------|
+| Complejidad | Baja/Media/Alta | ... | ... |
+| Tiempo estimado | Xh | ... | ... |
+| Escalabilidad | Limitada/Buena/Excelente | ... | ... |
+| Riesgo técnico | Bajo/Medio/Alto | ... | ... |
+| Dependencias nuevas | Ninguna/X | ... | ... |
+
+Cerrar con una **recomendación explícita** y su justificación.
+Si solo hay un enfoque viable, decirlo abiertamente y explicar por qué se descartaron los demás.
+
+Condición de salida: el usuario elige un enfoque o pide ajustes.
+
+### Paso 4 — Presentar diseño
+
+Secciones del diseño presentadas de forma progresiva, con aprobación del usuario entre cada una:
+
+1. **Arquitectura de alto nivel**: componentes, responsabilidades, flujo de datos
+2. **Modelo de datos / interfaces**: entidades, tipos, contratos de API
+3. **Flujo de interacción**: secuencia de pasos del usuario o del sistema
+4. **Casos edge y errores**: qué pasa cuando algo falla o llega input inesperado
+
+No escribir código durante el diseño — solo pseudocódigo, diagramas de texto o interfaces.
+Formato preferido para diagramas:
+
+```
+[Cliente] --> [API Gateway] --> [Servicio A] --> [BD]
+                            --> [Servicio B] --> [Cache]
+```
+
+Condición de salida: el usuario aprueba el diseño (puede ser parcial si hay iteración).
+
+### Paso 5 — Escribir spec
+
+Guardar en `.planning/specs/YYYY-MM-DD-{tema}-spec.md`.
+Usar la plantilla de spec definida en la sección "Formato de spec" más abajo.
+
+No dejar campos con TBD, TODO ni pendiente de definir.
+Si algo no está definido: registrarlo como "decisión delegada al agente" con justificación.
+
+Condición de salida: spec guardada en disco sin placeholders.
+
+### Paso 6 — Auto-revision de spec
+
+Antes de presentar la spec al usuario, verificar:
+
+- [ ] Sin placeholders: TBD, TODO, implementar después, pendiente
+- [ ] Consistencia interna: los tipos mencionados en el modelo de datos coinciden con los flujos
+- [ ] Cobertura de requisitos: cada pregunta del Paso 2 tiene respuesta en la spec
+- [ ] Sin scope creep: la spec no incluye features que no se discutieron en los pasos anteriores
+- [ ] Criterios de éxito son verificables: observables sin ambigüedad
+
+Si se detecta alguna inconsistencia, corregirla antes de presentar la spec.
+
+Condición de salida: checklist completo sin ítems pendientes.
+
+### Paso 7 — Transición a plan
+
+Solo después de que el usuario apruebe la spec:
+
+1. Ofrecer explícitamente: "¿Quieres que planee la implementación ahora?"
+2. Si acepta: invocar `Skill("planear-fase")` o indicar el uso de `/swl:planear-fase`
+3. Nunca saltar directamente a implementación sin pasar por planear-fase
+
+Condición de salida: usuario decide si planear o pausar aquí.
+
+---
+
+## Visualización HTML (opcional)
+
+Cuando hay decisiones con componente visual (UI, diagramas de arquitectura, comparaciones):
+
+- Ofrecer generar un archivo HTML en `.planning/visual/YYYY-MM-DD-{tema}.html`
+- El HTML es complementario — el terminal es el canal principal de conversación
+- Generar HTML solo si el usuario lo solicita o si la decisión tiene componente visual clara
+- Componentes disponibles: ver [recursos/componentes-html.md](recursos/componentes-html.md)
+
+---
+
+## Reglas anti-shortcut
+
+Estas reglas previenen los errores más frecuentes del brainstorming apresurado:
+
+### No saltar el brainstorming porque "es simple"
+
+**Problema**: features que parecen simples esconden decisiones de diseño no obvias.
+**Por qué**: el retrabajo de reimplementar una feature mal diseñada cuesta 3-5x más que diseñarla bien.
+**Cómo verificar**: si hay más de una forma de implementarlo, merece al menos el Paso 3.
+
+### Mínimo 2 enfoques alternativos
+
+**Problema**: proponer una sola opción sesga la decisión hacia lo primero que se pensó.
+**Por qué**: comparar alternativas hace explícitas las restricciones y los trade-offs.
+**Cómo verificar**: la tabla comparativa del Paso 3 tiene al menos 2 columnas de enfoque.
+
+### No escribir código durante brainstorming
+
+**Problema**: el código durante el diseño ancla la conversación a detalles de implementación.
+**Por qué**: la spec debe ser independiente del lenguaje y de la librería elegida.
+**Cómo verificar**: SKILL.md no contiene bloques de código con lógica de negocio real.
+
+### No saltar a implementación sin aprobación de spec
+
+**Problema**: implementar sin spec aprobada resulta en features que no resuelven el problema correcto.
+**Por qué**: el costo de cambiar la dirección a mitad de implementación es alto.
+**Cómo verificar**: el Paso 7 solo se ejecuta después de que el usuario dice "aprobado".
+
+---
+
+## Formato de spec
+
+```markdown
+# Spec: {titulo}
+**Fecha**: YYYY-MM-DD
+**Estado**: Propuesta | Aprobada | Implementada
+
+## Contexto
+Qué problema resolvemos, por qué ahora y para quién.
+
+## Decisión
+Qué enfoque elegimos y por qué (referencia al Paso 3).
+
+## Diseño
+
+### Arquitectura
+[Descripción de componentes y flujo de datos]
+
+### Modelo de datos
+[Entidades, tipos, relaciones principales]
+
+### Interfaces / API
+[Contratos de entrada y salida de los componentes principales]
+
+### Flujo de interacción
+[Secuencia de pasos del usuario o del sistema]
+
+### Casos edge y errores
+[Comportamiento esperado cuando algo falla o llega input inesperado]
+
+## Criterios de éxito
+- [ ] Criterio 1 (verificable sin ambigüedad)
+- [ ] Criterio 2
+
+## Alternativas descartadas
+| Alternativa | Razón de descarte |
+|-------------|-------------------|
+| Enfoque B   | Mayor complejidad sin beneficio claro para el caso de uso actual |
+
+## Riesgos y mitigaciones
+| Riesgo | Probabilidad | Mitigación |
+|--------|-------------|------------|
+|        |             |            |
+```
+
+---
+
+## Anti-patrones conocidos
+
+### Proponer sin preguntar
+
+**Problema**: el agente lanza enfoques sin entender el problema real.
+**Síntoma**: la propuesta no resuelve lo que el usuario tenía en mente.
+**Causa**: saltarse el Paso 2 para parecer eficiente.
+
+### Enfoque único disfrazado
+
+**Problema**: se presenta "una opción" cuando en realidad hay alternativas válidas.
+**Síntoma**: la tabla comparativa tiene solo una columna, o las otras opciones están artificialmente debilitadas.
+**Causa**: el agente ya decidió internamente y presenta su preferencia como la única viable.
+
+### Spec con placeholders TBD
+
+**Problema**: la spec se guarda con campos sin completar.
+**Síntoma**: el plan posterior tiene tareas vagas que bloquean al implementador.
+**Causa**: saltarse la auto-revisión del Paso 6.
+
+### Brainstorming de 2 minutos para feature de 1 semana
+
+**Problema**: el tiempo invertido en diseño no es proporcional a la complejidad.
+**Síntoma**: la spec tiene 3 líneas para una feature de 40 horas de desarrollo.
+**Causa**: presión percibida de "moverse rápido" sin cuantificar el costo del retrabajo.
+
+---
+
+## Checklist de cierre de brainstorming
+
+Antes de invocar planear-fase, verificar:
+
+- [ ] Contexto explorado (código, docs, ADRs relevantes leídos)
+- [ ] Las 4 preguntas del Paso 2 tienen respuesta
+- [ ] Al menos 2 enfoques comparados con tabla de trade-offs
+- [ ] El usuario eligió un enfoque
+- [ ] Diseño presentado con las 4 secciones del Paso 4
+- [ ] Spec guardada en `.planning/specs/` sin placeholders
+- [ ] Auto-revisión del Paso 6 completada
+- [ ] Usuario aprobó la spec antes de transición a plan
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+**Completar el Paso 3 con solo un enfoque real disfrazado de dos**: la tabla comparativa tiene dos columnas, pero el "Enfoque B" está deliberadamente debilitado con contras exagerados para que el Enfoque A parezca la única opción. Causa: el agente ya decidió internamente y usa el Paso 3 para justificar, no para explorar. Fix: cada enfoque debe ser genuinamente viable para el contexto del usuario. Si el Enfoque B tiene una desventaja real pero también tiene un caso de uso donde sería mejor, mencionarlo explícitamente.
+
+**Guardar la spec con campos `TBD` o `[pendiente]` y considerar el Paso 5 completo**: el Paso 6 (auto-revisión) se omite bajo presión de tiempo y la spec llega al planificador con decisiones sin tomar. Causa: el brainstorming termina cuando el agente se cansa, no cuando la spec está completa. Fix: la condición de salida del Paso 5 es "spec sin placeholders" — si hay un campo genuinamente indefinido, marcarlo como "decisión delegada al implementador" con justificación explícita, no dejarlo en blanco.
+
+**El Paso 4 (diseño) se salta porque el enfoque elegido "parece obvio"**: el usuario elige el Enfoque A en el Paso 3 y el agente salta directamente al Paso 5 (spec) sin presentar el diseño detallado. Causa: los pasos intermedios parecen redundantes cuando el enfoque ya está decidido. Fix: el Paso 4 es obligatorio porque es donde se detectan inconsistencias entre la arquitectura de alto nivel y el modelo de datos. Un brainstorming sin Paso 4 produce specs con arquitectura implícita que el implementador debe inventar.
+
+**El usuario aprueba el brainstorming pero sin haber leído la spec completa**: el agente presenta el resumen del diseño y el usuario dice "sí" sin leer la spec guardada en `.planning/specs/`. Causa: la spec es un artefacto separado de la conversación y el usuario confía en el resumen verbal. Fix: antes de la transición al Paso 7, citar explícitamente los criterios de aceptación de la spec y pedir confirmación sobre cada uno, no sobre el diseño en general.
+
+*Skill creado con swl:crear-skill el 2026-03-31. Versión 1.0.0.*

package/habilidades/brainstorming/recursos/componentes-html.md

@@ -0,0 +1,247 @@
+# Componentes HTML para Brainstorming Visual
+
+Referencia de bloques HTML reutilizables para generar visualizaciones de apoyo
+en `.planning/visual/`. Estos componentes son complementarios al terminal —
+usar solo cuando la dimension visual aporta valor real a la decision.
+
+## Estructura base del archivo HTML
+
+```html
+<!DOCTYPE html>
+<html lang="es">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Brainstorming: {tema}</title>
+  <style>
+    body { font-family: system-ui, sans-serif; max-width: 960px; margin: 2rem auto; padding: 0 1rem; color: #1a1a1a; }
+    h1 { font-size: 1.5rem; border-bottom: 2px solid #e5e7eb; padding-bottom: .5rem; }
+    h2 { font-size: 1.1rem; color: #374151; margin-top: 2rem; }
+    .options { display: flex; gap: 1rem; flex-wrap: wrap; margin: 1rem 0; }
+    .option { flex: 1; min-width: 220px; border: 2px solid #e5e7eb; border-radius: 8px; padding: 1rem; }
+    .option:hover { border-color: #6366f1; }
+    .option .letter { font-size: 2rem; font-weight: bold; color: #6366f1; line-height: 1; }
+    .option h3 { margin: .5rem 0 .25rem; font-size: 1rem; }
+    .option p { margin: 0; font-size: .875rem; color: #6b7280; }
+    .pros-cons { display: flex; gap: 1rem; margin: 1rem 0; }
+    .pros, .cons { flex: 1; border-radius: 6px; padding: .75rem 1rem; }
+    .pros { background: #f0fdf4; border-left: 3px solid #22c55e; }
+    .cons { background: #fef2f2; border-left: 3px solid #ef4444; }
+    .pros h4 { color: #16a34a; margin: 0 0 .5rem; font-size: .875rem; }
+    .cons h4 { color: #dc2626; margin: 0 0 .5rem; font-size: .875rem; }
+    .pros ul, .cons ul { margin: 0; padding-left: 1.25rem; font-size: .875rem; }
+    .mockup { border: 1px solid #d1d5db; border-radius: 8px; overflow: hidden; margin: 1rem 0; }
+    .mockup-header { background: #f3f4f6; padding: .5rem 1rem; font-size: .8rem; color: #6b7280; border-bottom: 1px solid #d1d5db; }
+    .mockup-body { display: grid; grid-template-columns: 180px 1fr; min-height: 200px; }
+    .mock-nav { background: #1e293b; color: #94a3b8; padding: 1rem; font-size: .75rem; }
+    .mock-sidebar { background: #f8fafc; border-right: 1px solid #e2e8f0; padding: 1rem; font-size: .8rem; grid-row: span 2; }
+    .mock-content { padding: 1rem; font-size: .85rem; }
+    .split { display: grid; grid-template-columns: 1fr 1fr; gap: 1rem; margin: 1rem 0; }
+    table.comparison { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: .875rem; }
+    table.comparison th { background: #f3f4f6; padding: .5rem .75rem; text-align: left; border: 1px solid #e5e7eb; }
+    table.comparison td { padding: .5rem .75rem; border: 1px solid #e5e7eb; }
+    table.comparison tr:nth-child(even) td { background: #f9fafb; }
+    .badge { display: inline-block; padding: .15rem .5rem; border-radius: 9999px; font-size: .75rem; font-weight: 600; }
+    .badge-green { background: #dcfce7; color: #166534; }
+    .badge-yellow { background: #fef9c3; color: #854d0e; }
+    .badge-red { background: #fee2e2; color: #991b1b; }
+  </style>
+</head>
+<body>
+  <h1>Brainstorming: {tema}</h1>
+  <p><strong>Fecha</strong>: {fecha} &nbsp;|&nbsp; <strong>Estado</strong>: En progreso</p>
+  <!-- insertar componentes aquí -->
+</body>
+</html>
+```
+
+---
+
+## Componente: Opciones A / B / C
+
+Usar para comparar enfoques mutuamente excluyentes.
+
+```html
+<h2>Enfoques propuestos</h2>
+<div class="options">
+  <div class="option">
+    <div class="letter">A</div>
+    <h3>Nombre del enfoque A</h3>
+    <p>Descripción breve del enfoque en 1-2 oraciones.</p>
+  </div>
+  <div class="option">
+    <div class="letter">B</div>
+    <h3>Nombre del enfoque B</h3>
+    <p>Descripción breve del enfoque en 1-2 oraciones.</p>
+  </div>
+  <div class="option">
+    <div class="letter">C</div>
+    <h3>Nombre del enfoque C</h3>
+    <p>Descripción breve del enfoque en 1-2 oraciones.</p>
+  </div>
+</div>
+```
+
+---
+
+## Componente: Pros / Contras
+
+Usar para una sola opción cuando se quiere detallar sus ventajas y desventajas.
+
+```html
+<div class="pros-cons">
+  <div class="pros">
+    <h4>Ventajas</h4>
+    <ul>
+      <li>Ventaja 1</li>
+      <li>Ventaja 2</li>
+    </ul>
+  </div>
+  <div class="cons">
+    <h4>Desventajas</h4>
+    <ul>
+      <li>Desventaja 1</li>
+      <li>Desventaja 2</li>
+    </ul>
+  </div>
+</div>
+```
+
+---
+
+## Componente: Mockup (wireframe de pantalla)
+
+Usar para visualizar layouts de UI sin entrar en detalle de estilos.
+
+```html
+<h2>Mockup: {nombre de la pantalla}</h2>
+<div class="mockup">
+  <div class="mockup-header">Vista previa: {nombre}</div>
+  <div class="mockup-body">
+    <div class="mock-nav">
+      <div>Nav item 1</div>
+      <div>Nav item 2</div>
+      <div>Nav item 3</div>
+    </div>
+    <div class="mock-sidebar">
+      <strong>Filtros</strong>
+      <div>Opcion 1</div>
+      <div>Opcion 2</div>
+    </div>
+    <div class="mock-content">
+      Contenido principal aquí.
+      Tabla, lista, formulario, etc.
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## Componente: Split View (comparación lado a lado)
+
+Usar para comparar dos versiones del mismo flujo o pantalla.
+
+```html
+<div class="split">
+  <div>
+    <h2>Opción A</h2>
+    <div class="mockup">
+      <div class="mockup-header">Vista: Opción A</div>
+      <div class="mockup-body" style="grid-template-columns: 1fr;">
+        <div class="mock-content">Contenido opción A</div>
+      </div>
+    </div>
+  </div>
+  <div>
+    <h2>Opción B</h2>
+    <div class="mockup">
+      <div class="mockup-header">Vista: Opción B</div>
+      <div class="mockup-body" style="grid-template-columns: 1fr;">
+        <div class="mock-content">Contenido opción B</div>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+---
+
+## Componente: Tabla comparativa
+
+Usar para comparar múltiples enfoques en varios atributos cuantificables o cualitativos.
+
+```html
+<h2>Comparación de enfoques</h2>
+<table class="comparison">
+  <thead>
+    <tr>
+      <th>Aspecto</th>
+      <th>Enfoque A</th>
+      <th>Enfoque B</th>
+      <th>Enfoque C</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>Complejidad</td>
+      <td><span class="badge badge-green">Baja</span></td>
+      <td><span class="badge badge-yellow">Media</span></td>
+      <td><span class="badge badge-red">Alta</span></td>
+    </tr>
+    <tr>
+      <td>Tiempo estimado</td>
+      <td>2h</td>
+      <td>4h</td>
+      <td>8h</td>
+    </tr>
+    <tr>
+      <td>Escalabilidad</td>
+      <td>Limitada</td>
+      <td>Buena</td>
+      <td>Excelente</td>
+    </tr>
+    <tr>
+      <td>Riesgo técnico</td>
+      <td><span class="badge badge-green">Bajo</span></td>
+      <td><span class="badge badge-yellow">Medio</span></td>
+      <td><span class="badge badge-red">Alto</span></td>
+    </tr>
+  </tbody>
+</table>
+```
+
+---
+
+## Diagrama de arquitectura en texto
+
+Para decisiones técnicas sin componente visual de UI, el texto en el terminal es suficiente.
+Formato preferido para diagramas de arquitectura en texto plano:
+
+```
+[Cliente Web]
+     |
+     v
+[Load Balancer]
+     |
+     +---> [API Gateway]
+               |
+               +---> [Servicio Auth]  --> [Redis: sesiones]
+               |
+               +---> [Servicio Core]  --> [PostgreSQL]
+               |
+               +---> [Servicio Notif] --> [Queue: mensajes]
+```
+
+Este formato funciona en terminal y en markdown sin necesidad de HTML.
+
+---
+
+## Notas de uso
+
+- Los archivos HTML se guardan en `.planning/visual/YYYY-MM-DD-{tema}.html`
+- Abrir en el navegador con `open .planning/visual/archivo.html` (Mac/Linux) o doble clic (Windows)
+- El terminal es el canal principal de la conversacion — el HTML es referencia visual de apoyo
+- Generar HTML solo cuando lo visual aporta: UI, comparaciones de layout, diagramas complejos
+- Para decisiones puramente tecnicas (algoritmos, esquemas de datos, patrones), texto en terminal es suficiente
+- No incluir lógica de negocio ni datos reales en los archivos HTML — solo estructura y etiquetas