| name | design-spec |
| description | Redacta design specs de producto a partir del output de brainstorming. Documenta el qué y el cómo con criterios de aceptación verificables, sin detalles técnicos. Genera un archivo markdown en docs/specs/. Usar después de brainstorming, cuando el enfoque esté acordado y antes del plan técnico o la implementación. |
Design Spec
Objetivo
Convertir los requisitos acordados en brainstorming en un design spec claro, conciso y aprobable. El documento describe qué se construye y cómo debe comportarse — desde la perspectiva del usuario o negocio.
No incluir: archivos, stack, APIs, arquitectura, nombres de funciones, esquemas de datos ni decisiones de implementación.
Cuándo usar
Siempre, como fase ② después de brainstorming y la confirmación del enfoque. Flujo obligatorio en AGENTS.md.
En tareas pequeñas, el spec puede ser corto; el archivo en docs/specs/ se crea igual.
Entrada esperada
Usar el output de brainstorming:
- Objetivo y problema
- Comportamiento esperado
- Enfoque elegido (qué resuelve + cómo funciona)
- Fuera de alcance
- Criterios de éxito mencionados
Si falta información, hacer 1 ronda breve de preguntas (máx. 3) sobre qué/cómo antes de escribir el archivo.
Salida
Crear un archivo markdown en:
docs/specs/[YYYY-MM-DD]-[feature-name].md
Convenciones de nombre
| Parte | Regla | Ejemplo |
|---|
| Fecha | Fecha actual en YYYY-MM-DD | 2026-06-19 |
| Feature | kebab-case, minúsculas, sin acentos | routing-por-complejidad |
Ejemplo: docs/specs/2026-06-19-routing-por-complejidad.md
Crear la carpeta docs/specs/ si no existe.
Flujo
- Revisar el output de brainstorming (o conversación previa)
- Confirmar el nombre del feature con el usuario si es ambiguo
- Redactar el design spec usando la plantilla
- Escribir el archivo en
docs/specs/
- Presentar al usuario el path del archivo y pedir aprobación explícita antes de continuar al plan técnico
Plantilla del design spec
Usar esta estructura en el archivo generado:
# [Nombre de la feature]
**Estado:** Borrador
**Fecha:** [YYYY-MM-DD]
## Problema
[Qué dolor o necesidad motiva esta feature. 2-4 frases.]
## Objetivo
[Qué se quiere lograr. 1-2 frases, medible si es posible.]
## Solución propuesta
[Enfoque elegido en brainstorming. Describe el qué y el cómo a nivel de comportamiento o experiencia — no implementación.]
## Comportamiento
### Caso principal
1. ...
2. ...
### Casos alternativos y errores
- Si ... → ...
- Si ... → ...
## Criterios de aceptación
- [ ] [Criterio verificable sin jerga técnica]
- [ ] ...
## Fuera de alcance
- ...
## Supuestos
- [Solo supuestos acordados o explícitos]
## Preguntas abiertas
- [Solo si quedan pendientes; si no, omitir sección]
Reglas de redacción
- Criterios de aceptación: verificables, en lenguaje de negocio ("el usuario ve...", "el agente responde...", "se rechaza cuando...")
- Comportamiento: flujos concretos, no abstractos
- Concisión: spec corta; si supera ~80 líneas, revisar si hay detalle técnico de más
- Estado: dejar en
Borrador hasta aprobación del usuario; cambiar a Aprobado solo cuando confirme
Aprobación
Tras escribir el archivo, mostrar al usuario:
- Path del archivo creado
- Resumen de 2-3 bullets de lo documentado
- Pregunta explícita: "¿Apruebas este design spec para pasar al plan técnico?"
No avanzar a implementación ni plan técnico sin aprobación.
Anti-patrones
- Incluir detalles técnicos (archivos, librerías, endpoints)
- Copiar verbatim los 2-3 enfoques del brainstorming — solo documentar el elegido
- Criterios de aceptación vagos ("funciona bien", "es rápido")
- Spec sin casos de error o límites
- Omitir fuera de alcance
- Crear el archivo sin informar al usuario la ruta
Relación con el flujo del proyecto
brainstorming → design-spec (este skill) → plan técnico → implementación + tests
Ver AGENTS.md para el flujo completo del proyecto.
