---
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.*
