JZKK720/cubecloud-skilldbundle-setup

De la Idea al Diseño

Convierte ideas en diseños y especificaciones completamente formados a través de un diálogo colaborativo natural.

Comienza comprendiendo el contexto actual del proyecto, luego haz preguntas una a la vez para refinar la idea. Una vez que entiendas lo que estás construyendo, presenta el diseño y obtén la aprobación del usuario.

Anti-Patrón: "Esto es demasiado simple para necesitar un diseño"

Cada proyecto pasa por este proceso. Una lista de tareas, una utilidad de una sola función, un cambio de configuración... todos. Los proyectos "simples" son donde las suposiciones no examinadas causan la mayor cantidad de trabajo desperdiciado. El diseño puede ser corto (unas pocas frases para proyectos verdaderamente simples), pero DEBES presentarlo y obtener aprobación.

Lista de verificación

DEBES crear una tarea para cada uno de estos elementos y completarlos en orden:

1. Explorar el contexto del proyecto — revisa archivos, documentos, commits recientes
2. Hacer preguntas aclaratorias — una a la vez, entender el propósito, las restricciones y los criterios de éxito
3. Proponer 2-3 enfoques — con compensaciones y tu recomendación
4. Presentar el diseño — en secciones escaladas a su complejidad, obtener la aprobación del usuario después de cada sección
5. Escribir el documento de diseño — guardar en docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md y hacer commit
6. Autorevisión de la especificación — verificación rápida en línea de marcadores de posición, contradicciones, ambigüedad, alcance
7. El usuario revisa la especificación escrita — pide al usuario que revise el archivo de especificación antes de continuar
8. Transición a la implementación — invocar la habilidad de escritura de planes para crear un plan de implementación

Flujo del proceso

flowchart TD
    A[Explorar el contexto del proyecto] --> B[Hacer preguntas aclaratorias]
    B --> C[Proponer 2-3 enfoques]
    C --> D[Presentar secciones del diseño]
    D --> E{¿Usuario aprueba el diseño?}
    E -- no, revisar --> D
    E -- sí --> F[Escribir documento de diseño]
    F --> G[Autorevisión de especificación<br/>corregir en línea]
    G --> H{¿Usuario revisa la especificación?}
    H -- cambios solicitados --> F
    H -- aprobada --> I[Invocar habilidad de escritura de planes]

El estado terminal es invocar la habilidad de escritura de planes. NO invoques ninguna habilidad de implementación. La ÚNICA habilidad que invocas después de esto es la de escritura de planes.

El Proceso

Comprendiendo la idea:

• Revisa primero el estado actual del proyecto (archivos, documentos, commits recientes)
• Antes de hacer preguntas detalladas, evalúa el alcance: si la solicitud describe múltiples subsistemas independientes (por ejemplo, "construye una plataforma con chat, almacenamiento de archivos, facturación y análisis"), márcalo de inmediato. No gastes preguntas refinando detalles de un proyecto que primero necesita ser descompuesto.
• Si el proyecto es demasiado grande para una sola especificación, ayuda al usuario a descomponerlo en subproyectos: cuáles son las piezas independientes, cómo se relacionan, en qué orden deben construirse. Luego, diseña el primer subproyecto a través del flujo normal. Cada subproyecto obtiene su propio ciclo de especificación → plan → implementación.
• Para proyectos con el alcance adecuado, haz preguntas una a la vez para refinar la idea
• Prefiere preguntas de opción múltiple cuando sea posible, pero las abiertas también están bien
• Solo una pregunta por mensaje — si un tema necesita más exploración, divídelo en varias preguntas
• Concéntrate en comprender: propósito, restricciones, criterios de éxito

Explorando enfoques:

• Propón 2-3 enfoques diferentes con compensaciones
• Presenta las opciones de manera conversacional con tu recomendación y razonamiento
• Lidera con tu opción recomendada y explica por qué

Presentando el diseño:

• Una vez que creas que entiendes lo que estás construyendo, presenta el diseño
• Escala cada sección a su complejidad: unas pocas frases si es directa, hasta 200-300 palabras si es matizada
• Pregunta después de cada sección si se ve correcta hasta ahora
• Cubre: arquitectura, componentes, flujo de datos, manejo de errores, pruebas
• Estate listo para retroceder y aclarar si algo no tiene sentido

Diseño para el aislamiento y la claridad:

• Divide el sistema en unidades más pequeñas que cada una tenga un propósito claro, se comuniquen a través de interfaces bien definidas y puedan entenderse y probarse de forma independiente
• Para cada unidad, deberías poder responder: ¿qué hace?, ¿cómo se usa?, ¿de qué depende?
• ¿Alguien puede entender lo que hace una unidad sin leer sus internos? ¿Puedes cambiar los internos sin romper a los consumidores? Si no, los límites necesitan trabajo.
• Las unidades más pequeñas y bien delimitadas también son más fáciles de manejar para ti: razonas mejor sobre el código que puedes mantener en contexto a la vez, y tus ediciones son más confiables cuando los archivos están enfocados. Cuando un archivo crece mucho, a menudo es una señal de que está haciendo demasiado.

Trabajando en bases de código existentes:

• Explora la estructura actual antes de proponer cambios. Sigue los patrones existentes.
• Donde el código existente tenga problemas que afecten el trabajo (por ejemplo, un archivo que ha crecido demasiado, límites poco claros, responsabilidades enredadas), incluye mejoras específicas como parte del diseño — la forma en que un buen desarrollador mejora el código en el que trabaja.
• No propongas refactorizaciones no relacionadas. Mantente enfocado en lo que sirve al objetivo actual.

Después del Diseño

Documentación:

• Escribe el diseño validado (especificación) en docs/superpowers/specs/YYYY-MM-DD-<topic>-design.md
  • (Las preferencias del usuario para la ubicación de la especificación anulan este valor predeterminado)
• Haz commit del documento de diseño en git

Autorevisión de la especificación: Después de escribir el documento de especificación, míralo con ojos nuevos:

1. Escaneo de marcadores de posición: ¿Algún "TBD", "TODO", secciones incompletas o requisitos vagos? Corrígelos.
2. Consistencia interna: ¿Alguna sección se contradice con otra? ¿La arquitectura coincide con las descripciones de las características?
3. Verificación de alcance: ¿Está lo suficientemente enfocado para un solo plan de implementación, o necesita descomposición?
4. Verificación de ambigüedad: ¿Algún requisito podría interpretarse de dos maneras diferentes? Si es así, elige una y hazla explícita.

Corrige cualquier problema en línea. No es necesario volver a revisar: solo corrige y continúa.

Puerta de revisión del usuario: Después de que pase el bucle de revisión de la especificación, pide al usuario que revise la especificación escrita antes de continuar:

"Especificación escrita y commiteada en <ruta>. Por favor, revísala y házme saber si quieres hacer algún cambio antes de que comencemos a escribir el plan de implementación."

Espera la respuesta del usuario. Si solicitan cambios, hazlos y vuelve a ejecutar el bucle de revisión de la especificación. Solo continúa una vez que el usuario apruebe.

Implementación:

• Invoca la habilidad de escritura de planes para crear un plan de implementación detallado
• NO invoques ninguna otra habilidad. La escritura de planes es el siguiente paso.

Principios Clave

• Una pregunta a la vez — No abrumes con múltiples preguntas
• Opción múltiple preferida — Más fácil de responder que abierta cuando sea posible
• YAGNI implacablemente — Elimina características innecesarias de todos los diseños
• Explora alternativas — Siempre propón 2-3 enfoques antes de decidir
• Validación incremental — Presenta el diseño, obtén aprobación antes de continuar
• Sé flexible — Retrocede y aclara cuando algo no tenga sentido

Lo que se eliminó de la habilidad original

La habilidad original de brainstorming (obra/superpowers) incluía una función "Compañero Visual": un servidor de navegador Node.js (scripts/server.cjs, scripts/start-server.sh, scripts/stop-server.sh) para mostrar maquetas en una pestaña del navegador durante la lluvia de ideas. SkillSpector bloqueó la habilidad por abuso de parámetros de herramientas en stop-server.sh.

Esta versión elimina por completo el Compañero Visual. La metodología central — diálogo de diseño colaborativo, puerta dura, autorevisión de especificación, puerta de revisión del usuario, transición a la escritura de planes — es una guía de proceso pura, sin scripts, sin shells y sin servidor externo. Es segura por construcción.

Si necesitas mostrar maquetas o diagramas durante una conversación de diseño, usa las herramientas nativas del agente (las herramientas MCP del navegador, generación de imágenes o diagramas Mermaid/ASCII en línea en el chat) en lugar de un servidor empaquetado.