QUBIK SDD — Spec-Driven Development

Exploración estructurada del requerimiento. El Funcional y el equipo conversan con el framework para descubrir comportamientos esperados, casos borde y ambigüedades. El objetivo no es tener todas las respuestas — es alinear al equipo en el "qué" antes de la spec.

Qué hace

1. Lee project.config.md y el MCP del proyecto.
2. Pide descripción del requerimiento o problema.
3. Hace preguntas guiadas: comportamientos, usuarios afectados, casos borde.
4. Identifica ambigüedades y las lista como preguntas abiertas.
5. Cierra cuando el equipo está listo para /qubik-spec.

Inputs

• Descripción informal del requerimiento.
• Discovery previo (si existe).

Outputs

• specs/brainstorming/YYYYMMDD-slug/YYYYMMDD-v1.md
• Sin estado JIRA en esta etapa.

Ejemplo real

/qubik-brainstorm

Leyendo config... Proyecto: Safecore | Funcional: Ana Torres

¿Qué requerimiento querés explorar?
Necesitamos un filtro por fecha en el listado de pacientes.

¿Qué tipo de fecha? ¿Ingreso, última atención, turno?
Fecha de última atención.

¿Rango de fechas o fecha exacta?
Rango. Desde-hasta.

¿Si no hay resultados, qué ve el usuario?
Estado vacío con mensaje descriptivo.

✓ specs/brainstorming/20260618-filtro-fecha/20260618-v1.md

Prototipo funcional en el submodule prototype del proyecto. Valida visualmente el flujo antes de la spec. Usa el frontend real con data mockeada — se ve exactamente como en producción. El gate es PROTOTYPE.md con Estado: Aprobado.

Qué hace

1. Verifica que el submodule prototype esté inicializado.
2. Detecta el package manager y levanta el dev server (http://localhost:5173).
3. El Funcional describe qué prototipar.
4. Implementa: SOLID (nuevo), REWORK (ajuste), STUB (placeholder).
5. Itera hasta la aprobación del Funcional.
6. Genera PROTOTYPE.md con Estado: Aprobado.

Inputs

• Brainstorming aprobado (recomendado).
• Submodule prototype del proyecto inicializado.

Outputs

• prototype/hub/PROTOTYPE.md (Estado: Aprobado).
• Commits: proto(SOLID), proto(REWORK), proto(STUB).
• Sin estado JIRA en esta etapa.

Ejemplo real

/qubik-prototype

Verificando submodule prototype...
Detectando package manager... npm
Dev server: http://localhost:5173

¿Qué querés prototipar?
El filtro: selector de rango y cómo actualiza el listado.

proto(SOLID): filtro de fecha — DateRangePicker en PatientList

¿Iteramos o aprobamos?
Agregar badge de "filtro activo" cuando hay fechas.

proto(REWORK): badge filtro activo + botón de limpieza
✓ PROTOTYPE.md — Estado: Aprobado
  2 flujos validados · 2 SOLID, 1 REWORK

Formaliza el requerimiento como historia de usuario en JIRA con criterios de aceptación en formato DADO/CUANDO/ENTONCES. Crea la historia (To Refinement), publica en Confluence si está configurado, y genera specs/refinar/ con spec.md y origen.md.

Qué hace

1. Lee el brainstorming o el PROTOTYPE.md aprobado.
2. Si hay dudas de comportamiento, pregunta antes de escribir.
3. Pregunta qué repos se ven afectados (FE/BE/infra).
4. Redacta la spec: historia, CAs, casos borde, repos involucrados.
5. Muestra el borrador — el Funcional aprueba.
6. Crea la historia en JIRA (To Refinement) + Confluence.
7. Genera specs/refinar/SC-XXXX-slug/ con spec.md y origen.md.
8. Actualiza HISTORIAS.md.

Inputs

• specs/brainstorming/YYYYMMDD-slug/ ó PROTOTYPE.md aprobado.

Outputs

• SC-XXXX en JIRA — To Refinement.
• specs/refinar/SC-XXXX-slug/spec.md + origen.md.
• specs/HISTORIAS.md actualizado.

Ejemplo real

/qubik-spec

Inputs: [1] 20260618-filtro-fecha/ [2] prototype/hub/PROTOTYPE.md
¿Cuál usamos? El 1.
¿Repos afectados? hub (FE) y api (BE).

Redactando...
Como médico, quiero filtrar el listado por fecha de última
atención, para encontrar pacientes con atención reciente.

CA-1: DADO que estoy en el listado
      CUANDO selecciono un rango de fechas
      ENTONCES solo veo pacientes con última atención en ese rango

¿Aprobás? Sí.
✓ SC-1234 — To Refinement
✓ specs/refinar/SC-1234-filtro-fecha/ creada

Breakdown técnico con el Dev Lead y el equipo. La historia se descompone en sub-tasks por capa y repo. Si es muy grande, se propone dividirla. Las sub-tasks se crean en JIRA como hijos de la historia principal (no historias independientes). La carpeta se mueve a specs/planificar/.

Qué hace

1. Lista las historias en specs/refinar/ — el Dev Lead elige.
2. Lee spec.md + origen.md + el código de los repos involucrados + MCP.
3. Revisa la spec con el equipo, aclara dudas antes de descomponer.
4. Evalúa el tamaño: si es grande, propone dividir en sub-tasks de JIRA.
5. Propone sub-tasks por capa: [FE:hub], [BE:api].
6. El Dev Lead ajusta hasta estar conforme.
7. Crea las sub-tasks en JIRA como hijas de la historia.
8. Genera refinement.md con tabla, dependencias, riesgos, contratos de API.
9. Mueve la carpeta: specs/refinar/ → specs/planificar/.

Inputs

• specs/refinar/SC-XXXX-slug/ (spec.md + origen.md).
• Código de los repos involucrados (local_path).

Outputs

• Sub-tasks JIRA: SC-XXXX-1,-2,-3...
• specs/planificar/SC-XXXX-slug/refinement.md
• HISTORIAS.md actualizado.

Ejemplo real

/qubik-refinamiento

[1] SC-1234 — Filtro por fecha (hub FE, api BE)
¿Cuál refinamos? La 1.
Leyendo spec + código de hub y api...

Propuesta de sub-tasks:
  [FE:hub]  Componente DateRangePicker en el listado
  [BE:api]  Endpoint GET /api/pacientes con filtro fecha, paginado
  [BE:api]  Migración: índice de búsqueda por fecha
  [FE:hub]  Integración componente-lista (dep: BE endpoint)
¿Ajustamos o procedemos?
Procedemos.

✓ SC-1234-1,-2,-3,-4 creadas en JIRA
✓ specs/planificar/SC-1234-filtro-fecha/ listo

Selección de qué historias entran a desarrollo. Sin estimación, sin asignación — solo la decisión de qué entra y qué espera. El PM facilita, el equipo decide. Lo seleccionado pasa a Ready to Dev y sus carpetas se mueven a specs/desarrollar/.

Qué hace

1. Lista las historias en specs/planificar/ con resumen.
2. El equipo elige cuáles entran (multi-select o "todas").
3. Muestra un resumen para confirmar.
4. Historia + sub-tasks → Ready to Dev en JIRA.
5. Carpetas movidas a specs/desarrollar/.
6. Actualiza HISTORIAS.md.
7. Si hay preguntas abiertas sin resolver, avisa antes de confirmar.

Inputs

• specs/planificar/ con historias refinadas.

Outputs

• Historia + sub-tasks → Ready to Dev.
• specs/desarrollar/SC-XXXX-slug/
• HISTORIAS.md actualizado.

Ejemplo real

/qubik-planning

Historias listas:
  [1] SC-1234 — Filtro fecha (4 sub-tasks) — 18 Jun
  [2] SC-1235 — Exportar informe (2 sub-tasks) — 16 Jun
  [3] SC-1240 — Notificaciones (6 sub-tasks)

¿Cuáles pasan a desarrollo?
1, 2

Van a Ready to Dev: SC-1234 (4), SC-1235 (2) — ¿Confirmás?
Sí.

✓ SC-1234 → Ready to Dev + 4 sub-tasks
✓ SC-1235 → Ready to Dev + 2 sub-tasks
✓ Carpetas movidas a specs/desarrollar/

Los devs leen la spec y el refinement.md en specs/desarrollar/. Si encuentran un delta con la spec usan /qubik-desvio. Al terminar, QA verifica con /qubik-qa contra los criterios de aceptación.

Qué hace

1. El dev lee spec.md + refinement.md en specs/desarrollar/SC-XXXX/.
2. Toma los sub-tasks en JIRA y arranca.
3. Si algo de la spec no aplica → /qubik-desvio para registrarlo.
4. Al terminar, notifica a QA.
5. QA corre /qubik-qa — aprueba o genera rebote.

Inputs

• specs/desarrollar/SC-XXXX/spec.md
• specs/desarrollar/SC-XXXX/refinement.md

Outputs

• Código implementado.
• Sub-tasks Done en JIRA.
• /qubik-desvio si hay delta de spec.

Ejemplo real

cat specs/desarrollar/SC-1234-filtro-fecha/refinement.md

## Sub-tasks
SC-1234-1  [FE:hub]  Componente DateRangePicker
SC-1234-2  [BE:api]  GET /api/pacientes con filtro
SC-1234-3  [BE:api]  Migración índice fecha
SC-1234-4  [FE:hub]  Integración componente-lista

## Contratos de API
GET /api/pacientes?desde=2026-01-01&hasta=2026-06-18&page=1

# Si hay un desvío:
/qubik-desvio
El filtro del API ya existe pero solo acepta fecha exacta, no rango.
✓ Desvío registrado. Notificando al Funcional.

Para bugs y features claras, el Funcional va directo a spec sin brainstorming previo. El input es la descripción directa del bug. QUBIK lo registra como "input directo" en origen.md. El proceso de redacción es el mismo, solo más corto porque el qué ya está claro.

Qué hace

1. El Funcional describe el bug o feature directamente.
2. No busca brainstorming previo — registra como "input directo".
3. Redacta la spec: historia, CAs en DADO/CUANDO/ENTONCES, casos borde del bug.
4. Aprobación rápida del Funcional.
5. Crea la historia en JIRA (To Refinement).
6. Genera specs/refinar/SC-XXXX-slug/spec.md + origen.md.
7. Actualiza HISTORIAS.md.

Inputs

• Descripción directa del bug o feature (sin exploración previa).

Outputs

• SC-XXXX en JIRA — To Refinement.
• specs/refinar/SC-XXXX-slug/spec.md + origen.md.

Ejemplo real

/qubik-spec

No hay brainstormings disponibles.
Podés dictarme el requerimiento directamente.

¿Cuál es el bug?
Cuando el filtro de estado está en "inactivo",
el listado queda en loading infinito.

CA-1: DADO filtro en "inactivo"
      CUANDO la vista carga
      ENTONCES muestra pacientes inactivos (o vacío)
CA-2: DADO filtro en "inactivo"
      CUANDO el API falla
      ENTONCES muestra error (no loading infinito)

¿Aprobás? Sí.
✓ SC-1256 — To Refinement
✓ specs/refinar/SC-1256-bug-filtro-inactivo/ creada

Para bugs el refinamiento es más corto: el problema es puntual, los sub-tasks son pocos. El Dev Lead puede hacerlo solo si el bug es claro, o con el dev que lo va a tomar.

Qué hace

1. Lee la spec del bug.
2. Identifica la causa probable y el alcance del fix.
3. Propone 1-3 sub-tasks: diagnóstico, fix, test de regresión.
4. Crea las sub-tasks en JIRA como hijas de la historia.
5. Mueve la carpeta a specs/planificar/.

Inputs

• specs/refinar/SC-1256-bug-filtro-inactivo/spec.md
• Código del repo afectado (hub FE).

Outputs

• Sub-task JIRA SC-1256-1.
• specs/planificar/SC-1256-bug-filtro-inactivo/refinement.md

Ejemplo real

/qubik-refinamiento

[1] SC-1256 — Bug filtro inactivo (hub FE)
¿Cuál refinamos? La 1.
Leyendo spec y código de hub...
PatientList.tsx — data.patients puede ser null
pero el componente espera un array [].

Sub-task:
  [FE:hub] Fix: (data.patients ?? []).map(...)
¿Procedemos?
Sí.

✓ SC-1256-1 creada en JIRA
✓ specs/planificar/SC-1256-bug-filtro-inactivo/ listo

Para bugs críticos el planning es una decisión inmediata del PM. Puede entrar solo o agruparse con otras historias en la misma sesión.

Qué hace

1. Lista las historias en specs/planificar/.
2. El PM prioriza el bug (inmediato si es crítico en producción).
3. Historia + sub-task → Ready to Dev.
4. Carpeta movida a specs/desarrollar/.

Inputs

• specs/planificar/SC-1256-bug-filtro-inactivo/

Outputs

• SC-1256 + SC-1256-1 → Ready to Dev.
• specs/desarrollar/SC-1256-bug-filtro-inactivo/

Ejemplo real

/qubik-planning

[1] SC-1256 — Bug filtro inactivo (1 sub-task) 🐛

¿Cuáles pasan a desarrollo?
La 1, entra ya — bug crítico en producción.

✓ SC-1256 → Ready to Dev
✓ SC-1256-1 → Ready to Dev
✓ specs/desarrollar/SC-1256-bug-filtro-inactivo/ listo

El dev aplica el fix puntual. El ciclo puede completarse en horas. QA verifica específicamente los CAs del bug.

Qué hace

1. El dev lee refinement.md para entender el alcance del fix.
2. Aplica el fix en el repo afectado.
3. Verifica que los CAs del spec.md se cumplen.
4. Notifica a QA.
5. QA corre /qubik-qa — Done en horas si aprueba.

Inputs

• specs/desarrollar/SC-1256-bug-filtro-inactivo/spec.md + refinement.md

Outputs

• Fix implementado en hub.
• SC-1256 → Done.

Ejemplo real

# hub/src/features/patients/PatientList.tsx

// Antes (bug): null.map() → error → loading infinito
const rows = data.patients.map(p => ...)

// Después (fix):
const rows = (data.patients ?? []).map(p => ...)

/qubik-qa
Verificando SC-1256 vs spec...
  CA-1: ✓ filtro "inactivo" muestra lista correcta
  CA-2: ✓ error del API muestra mensaje (no loading)
✓ SC-1256 → Done (3 horas · camino corto)

Inicializar el proyecto. Configura desde cero: project.config.md, estructura de specs/, submodule prototype. El primer comando de cualquier proyecto.

Output

project.config.md · specs/ con carpetas base · HISTORIAS.md

Cuándo usarlo

Una vez por proyecto. Los nuevos integrantes corren --onboarding.

setup · onboarding · config

Explorar un requerimiento. Conversación estructurada para descubrir comportamientos, casos borde y preguntas abiertas. Output directo para /qubik-spec.

Output

specs/brainstorming/YYYYMMDD-slug/YYYYMMDD-v1.md

Cuándo usarlo

Cuando el requerimiento no es obvio o tiene múltiples interpretaciones.

exploración · funcional · camino-largo

Prototipar en vivo. Prototipo funcional en el submodule prototype. Valida visualmente antes de la spec. Gate: PROTOTYPE.md con Estado: Aprobado.

Output

prototype/hub/PROTOTYPE.md · commits proto(SOLID/REWORK/STUB)

Cuándo usarlo

Cuando el equipo necesita ver el flujo real antes de formalizar. Opcional en el camino largo.

prototipo · visual · gate · camino-largo

Formalizar la historia. Crea historia en JIRA (To Refinement), publica en Confluence, genera specs/refinar/. Soporta --update para rebotes de QA.

Output

SC-XXXX en JIRA (To Refinement) · specs/refinar/SC-XXXX-slug/ · HISTORIAS.md

Cuándo usarlo

Después del brainstorm o prototipo aprobado. O directo para bugs y features claras.

spec · jira · confluence · historia

Breakdown técnico. El Dev Lead descompone en sub-tasks por capa y repo. Sub-tasks en JIRA como hijas de la historia. No historias independientes.

Output

Sub-tasks JIRA (SC-XXXX-N) · specs/planificar/SC-XXXX/refinement.md

Cuándo usarlo

Cuando hay historias en specs/refinar/ (To Refinement).

refinamiento · sub-tasks · dev-lead

Seleccionar para desarrollo. PM + Dev Lead seleccionan qué historias entran. Sin estimación ni asignación. Solo priorización.

Output

Historia + sub-tasks → Ready to Dev · specs/desarrollar/SC-XXXX-slug/

Cuándo usarlo

Cuando hay historias en specs/planificar/ (To Planning).

planning · priorización · pm

Sincronizar el framework. Actualiza QUBIK SDD a la última versión. Migra templates sin pisar archivos del proyecto.

Output

Framework actualizado · templates migrados

Cuándo usarlo

Cuando hay actualizaciones, antes de un proyecto nuevo, o si un comando falla.

actualización · mantenimiento

Health check del proyecto. Verifica historias fuera de lugar, config incompleta, sub-tasks huérfanas, archivos inconsistentes.

Output

Reporte de salud con issues encontrados

Cuándo usarlo

Antes de un sprint, si hay inconsistencias, o como rutina.

salud · verificación

Pushear cambios de specs. Commitea y sube cambios del ciclo con el formato del framework. Verifica que los archivos estén en el lugar correcto.

Output

Commit + push con mensaje formateado

Cuándo usarlo

Después de cada comando del flujo. Al final del día.

git · commit · push

Registrar desvío de spec. El dev encontró que algo de la spec no aplica, es inviable o cambió. Se registra formalmente y se notifica al Funcional.

Output

Desvío registrado en la carpeta de la historia · notificación al Funcional

Cuándo usarlo

Durante el desarrollo, cuando hay un delta entre la spec y el código real.

desvío · spec · cambio

QA sign-off. QA verifica contra criterios de aceptación. Si hay gaps, genera rebote con /qubik-spec --update. Si aprueba, Done en JIRA.

Output

Historia → Done (aprueba) · o rebote a /qubik-spec --update (gap)

Cuándo usarlo

Cuando el dev marca la historia como terminada.

qa · verificación · done