brainstorming

Visión general

Qué hace la skill brainstorming

La skill brainstorming impone una regla clara: primero van el diseño y la especificación, después la implementación. Cuando está activa, brainstorming te guía para explorar la intención del usuario, los requisitos y el diseño de alto nivel antes de escribir código, crear scaffolding de proyectos o invocar cualquier skill de implementación.

Está construida alrededor de un diálogo colaborativo. Empiezas con una idea general, vas refinando el contexto y las restricciones mediante preguntas dirigidas y, finalmente, converges en un diseño explícito y una especificación que el usuario puede revisar y aprobar. Solo después de ese punto de aprobación firme tiene sentido pasar a trabajo de construcción o refactorización.

Para quién es brainstorming

Utiliza la skill brainstorming si:

• Trabajas con Claude u otros agentes similares en funcionalidades de producto, componentes, flujos de UI o cambios de arquitectura
• Quieres evitar el antipatrón de “esto es demasiado simple como para necesitar un diseño”
• Necesitas conversaciones de diseño repetibles y auditables antes de cambiar código
• Con frecuencia construyes o ajustas frontend, UI/UX o sistemas muy dependientes de flujos de trabajo

Encaja bien con desarrolladores en solitario, product engineers, diseñadores y equipos que quieren un flujo de trabajo ligero pero consistente con prioridad en el diseño.

Problemas que resuelve esta skill

La skill brainstorming está diseñada para evitar:

• Saltar directamente al código sin aclarar primero los objetivos
• Suposiciones ocultas que solo aparecen tarde en la implementación
• Cambios de UI/UX construidos sin journeys de usuario claros ni dirección visual
• Especificaciones demasiado vagas para planificar con fiabilidad o delegar

Al forzar un checkpoint de diseño, brainstorming reduce retrabajo, implementaciones desalineadas y deuda de diseño.

Cuándo encaja bien (o mal) brainstorming

Encaja muy bien cuando:

• Estás planificando nuevas funcionalidades, modificando comportamientos o diseñando flujos de UI/UX
• Quieres una plantilla estructurada para ideación, recopilación de contexto y aprobación de diseño
• Te ayudan los mockups o diagramas visuales para pensar distintas opciones

Encaja peor cuando:

• Estás haciendo ediciones puramente mecánicas (corrección de typos, renombrar una variable, actualizar una constante sin cambio de comportamiento)
• Ya tienes una especificación detallada y aprobada y solo necesitas ejecutarla (en ese caso, quizá te convenga usar skills centradas en la implementación)

Incluso tareas aparentemente triviales, como un pequeño cambio de configuración o una utilidad de una sola función, pueden beneficiarse de un breve pase de diseño, pero puedes mantenerlo corto y seguir usando el proceso de brainstorming.

Cómo usarla

Instalación y configuración

1. Instalar la skill brainstorming

Utiliza el CLI skills para añadir la skill brainstorming desde el repositorio obra/superpowers:

npx skills add https://github.com/obra/superpowers --skill brainstorming

Esto descarga la definición de la skill junto con los prompts de soporte y scripts auxiliares opcionales bajo el directorio skills/brainstorming.

2. Explorar los archivos clave

Tras la instalación, revisa estos archivos para entender el flujo de trabajo y los helpers disponibles:

• SKILL.md – Descripción central del proceso de brainstorming, incluido el hard gate de diseño-antes-del-código y la checklist de pasos requeridos.
• spec-document-reviewer-prompt.md – Prompt plantilla para un subagente de revisión de especificaciones que comprueba completitud, consistencia y claridad de tu spec.
• visual-companion.md – Guía para usar un visual companion en el navegador para mostrar mockups, diagramas y opciones visuales.
• scripts/frame-template.html – Plantilla HTML de frame que usa el visual companion para layouts coherentes centrados en UI.
• scripts/helper.js – Helper del lado del cliente para manejar eventos de selección y live reload en el visual companion.
• scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh – Scripts para ejecutar y administrar el servidor del visual companion.

No necesitas modificar estos archivos para empezar a usar el flujo de trabajo de brainstorming, pero conocer qué hay disponible facilita integrarlo en tu propia configuración.

Flujo de trabajo central de brainstorming

1. Comienza con el contexto del proyecto

Empieza cualquier sesión con brainstorming orientándote en el proyecto actual. La checklist en SKILL.md enfatiza:

• Inspeccionar archivos y documentación relevantes
• Echar un vistazo rápido a los commits recientes para obtener contexto
• Identificar qué partes del sistema están implicadas

Cuando uses Claude u otro agente, pídele que explore primero el contexto del proyecto en lugar de solicitar cambios de código de inmediato.

2. Ofrece el visual companion para cuestiones visuales

Si la tarea incluye temas de UI/UX u otros intrínsecamente visuales, ofrece usar el visual companion como paso separado. La regla de visual-companion.md es:

Decide por pregunta, no por sesión. Pregunta: ¿entendería el usuario esto mejor viéndolo que leyéndolo?

Utiliza el companion basado en navegador para:

• Mockups de UI y opciones de layout
• Diagramas de arquitectura y flujos
• Comparaciones en paralelo de distintas direcciones de diseño
• Conversaciones sobre espaciado, jerarquía y pulido visual

Quédate en el terminal (solo texto) para:

• Alcance, requisitos y definición de términos
• Tradeoffs conceptuales y decisiones de modelado de APIs/datos
• Preguntas de aclaración donde las respuestas son texto, no visuales

3. Haz preguntas de aclaración de una en una

La skill brainstorming espera una conversación disciplinada, no un único mega-prompt. Utiliza una secuencia de preguntas enfocadas, por ejemplo:

• "Who are the primary users of this feature?"
• "What constraints do we have on performance or deployment?"
• "Which platforms and screen sizes matter most?"

Haz una pregunta cada vez, espera las respuestas y ve refinando tu comprensión de forma incremental.

4. Produce un diseño y una especificación concretos

Cuando tengas contexto suficiente, sintetízalo en un diseño que el usuario pueda aprobar realmente. Según la tarea, puede incluir:

• Objetivos de alto nivel y criterios de éxito
• User stories o flujos de ejemplo
• Descripciones de layout de UI y dirección visual (opcionalmente respaldadas por el visual companion)
• Estructuras de datos, interfaces o puntos de integración
• Requisitos no funcionales que afecten a la implementación

Redáctalo como un documento de especificación estructurado en tu ubicación preferida (por ejemplo, bajo docs/superpowers/specs/ si sigues la convención del repositorio).

5. Haz cumplir el hard gate de diseño

Una regla clave de SKILL.md es el hard gate:

Do NOT invoke any implementation skill, write any code, scaffold any project, or take any implementation action until you have presented a design and the user has approved it.

Esto se aplica incluso cuando el trabajo parece simple. El diseño puede ser solo unas frases para un cambio trivial, pero debe existir y ser confirmado explícitamente antes de avanzar.

Uso de la plantilla de revisión de especificaciones

1. Redacta tu spec

Tras el brainstorming, redacta tu spec con la estructura que mejor se adapte a tu proyecto. Guárdala en una ruta de archivo a la que puedas hacer referencia, por ejemplo:

docs/superpowers/specs/my-feature-spec.md

2. Lanza un subagente revisor de la spec

Cuando la spec esté lista para validación, utiliza spec-document-reviewer-prompt.md como plantilla para crear un subagente revisor de especificaciones. Sustituye [SPEC_FILE_PATH] en el prompt por la ruta a tu archivo de spec.

Este revisor:

• Buscará secciones que falten, TODOs o placeholders tipo “TBD”
• Detectará contradicciones y requisitos inconsistentes
• Señalará requisitos ambiguos que puedan provocar mala implementación
• Comprobará que el alcance sea lo bastante acotado para un plan único y coherente

La salida del revisor incluye un estado Approved | Issues Found y una lista de issues, cada uno vinculado a por qué es relevante para la planificación de la implementación.

3. Itera hasta obtener la aprobación

Si el revisor detecta problemas, actualiza la spec y vuelve a ejecutar la revisión. Una vez aprobada tu spec, tendrás una base sólida para las skills de implementación y las herramientas de planificación.

Uso del visual brainstorming companion

1. Inicia el servidor del visual companion

Desde el directorio scripts, puedes iniciar el servidor de brainstorming con:

./start-server.sh --project-dir /path/to/your/project

Algunas opciones útiles son:

• --project-dir <path> – Almacena los archivos de sesión bajo <path>/.superpowers/brainstorm/ en lugar de /tmp para mantenerlos persistentes.
• --host <bind-host> – Vincula a una interfaz específica (por ejemplo, 0.0.0.0 en contenedores o entornos remotos).
• --url-host <display-host> – Controla el hostname que se muestra en el JSON de URL devuelto.
• --foreground o --background – Elige si el servidor se ejecuta en la terminal actual o como proceso en segundo plano.

Al arrancar, el script imprime JSON con la URL de la sesión. Abre esa URL en un navegador para acceder al frame visual de brainstorming.

2. Renderiza opciones visuales

El servidor vigila un directorio en busca de archivos HTML y siempre sirve el más reciente. El patrón típico es:

1. Claude (o tu agente) escribe un archivo HTML en el screen_dir configurado usando frame-template.html como base.
2. El navegador se recarga automáticamente mediante helper.js cuando se crea un archivo nuevo.
3. Los usuarios pueden hacer clic en opciones o cards dentro de la UI, y esos eventos se envían de vuelta por WebSocket para que el agente los consuma.

Esto facilita mostrar:

• Varias opciones de layout como cards clicables
• Diagramas de flujo y máquinas de estados
• Comparaciones visuales de color, espaciado o variantes de componentes

3. Detén el servidor cuando termines

Cuando la sesión haya terminado, detén limpiamente el servidor de brainstorming con:

./stop-server.sh <session_dir>

Para sesiones bajo /tmp, esto también limpia los archivos generados. Los directorios persistentes bajo .superpowers/ se conservan para que puedas revisar más tarde mockups y diagramas.

Integrar brainstorming en tu propio flujo de trabajo

• Como paso estándar antes del commit: Exige un pase de brainstorming y una spec aprobada antes de fusionar ramas de funcionalidad.
• Con otras skills: Ejecuta brainstorming primero, captura la spec y luego dale el relevo a skills de implementación, refactorización o testing.
• Para trabajo de UI/UX: Combina el brainstorming conversacional con el visual companion para validar ideas de layout e interacción antes de escribir CSS o código de componentes.

Ajusta las rutas de carpetas, nombres y formato de la spec para que encajen con tus repos existentes, manteniendo el patrón central: contexto → preguntas → diseño/spec → revisión → implementación.

FAQ

¿La skill brainstorming es solo para proyectos grandes y complejos?

No. La skill brainstorming está diseñada explícitamente para evitar el antipatrón de “esto es demasiado simple como para necesitar un diseño”. Incluso un pequeño cambio de configuración o una utilidad puntual pueden ocultar suposiciones. Para tareas muy pequeñas, el diseño puede ser solo una descripción concisa, pero deberías igualmente articularlo y confirmarlo antes de implementar.

¿Puedo saltarme brainstorming si ya tengo una spec?

Si ya tienes una spec completa, actualizada y aprobada, puede que no necesites una sesión de brainstorming completa. Sin embargo, puedes seguir usando la plantilla de revisión de specs de spec-document-reviewer-prompt.md para validar esa spec antes de la implementación. Si la revisión revela lagunas o ambigüedades, realiza un pase de brainstorming más corto para cerrarlas.

¿Cómo se relaciona brainstorming con las skills de implementación?

La skill brainstorming está pensada para ejecutarse antes de cualquier skill de implementación. Produce:

• Un diseño claro y aprobado por el usuario
• Un documento de especificación que puede revisarse e iterarse

Solo después de superar ese gate de aprobación deberías invocar skills de código o refactorización. Esta separación ayuda a mantener explícita la intención de diseño y reduce los idas y vueltas durante la implementación.

¿Tengo que usar el visual companion para beneficiarme de brainstorming?

No. El visual companion es opcional.

• Si tu trabajo es sobre todo lógica de backend, APIs o infraestructura, puedes usar brainstorming como un flujo de trabajo puramente basado en texto.
• Si haces UI/UX, diseño de producto o frontend, usar el visual companion descrito en visual-companion.md y el directorio scripts/ puede facilitar mucho comparar opciones y recopilar feedback.

Decide en función de si lo visual realmente aportará claridad a la conversación.

¿Qué pasa si ignoro el hard gate y empiezo a programar igualmente?

Ignorar el hard gate de diseño elimina el principal beneficio de la skill brainstorming: detectar desalineaciones pronto. Puedes acabar con:

• Funcionalidades que no coinciden con las expectativas del usuario
• Implementaciones de UI que haya que rehacer tras recibir feedback
• Specs que se queden por detrás del código y se conviertan en deuda de documentación

Trata el gate como una regla de proceso: no escribas ni pidas código hasta que el diseño esté escrito, revisado y explícitamente aprobado.

¿Puedo personalizar los criterios de revisión de la spec?

Sí. spec-document-reviewer-prompt.md define categorías como completitud, consistencia, claridad, alcance y consideraciones YAGNI. Puedes adaptar esta plantilla a tu propio dominio (por ejemplo, añadiendo chequeos de seguridad, rendimiento o cumplimiento normativo) manteniendo el mismo flujo de revisión.

¿Brainstorming está ligado a un framework o stack tecnológico específico?

No. La skill brainstorming es agnóstica al stack. Se centra en recopilar contexto, aclarar requisitos, articular el diseño y explorar opciones visuales, no en código específico de frameworks. Puedes usarla para apps frontend, servicios backend, integraciones o sistemas mixtos.

¿Cómo desinstalo o desactivo la skill brainstorming?

La skill forma parte del conjunto de skills obra/superpowers. Para dejar de usarla, puedes:

• Eliminar o comentar su configuración en tu agente o cargador de skills
• Dejar de llamarla en tus flujos de trabajo y pipelines

La skill brainstorming no realiza cambios globales en el sistema, así que dejar de usarla se reduce a ajustes de configuración y de uso.