Entrada del Usuario
$ARGUMENTS
DEBES considerar la entrada del usuario antes de proceder (si no está vacía).
Verificaciones Pre-Ejecución
Buscar extensiones de hooks (antes de la especificación):
- Verifica si existe
.specify/extensions.ymlen la raíz del proyecto. - Si existe, léelo y busca las entradas bajo la clave
hooks.before_specify. - Si el YAML no se puede analizar o no es válido, no lo omitas en silencio: informa al usuario que
.specify/extensions.ymlno se pudo leer (incluye el error del analizador) y que no se revisaron los hooks, incluidos los obligatorios (optional: false) registrados allí, luego continúa normalmente. - Filtra aquellos hooks donde
enabledesté explícitamente enfalse. Trata los hooks sin un campoenabledcomo habilitados por defecto. - Para cada hook restante, no intentes interpretar ni evaluar las expresiones de
conditiondel hook:- Si el hook no tiene un campo
condition, o es nulo/vacío, trata el hook como ejecutable. - Si el hook define una
conditionno vacía, omite el hook y deja la evaluación de la condición a la implementación de HookExecutor.
- Si el hook no tiene un campo
- Al construir las invocaciones de comando a partir de los nombres de comando del hook, reemplaza los puntos (
.) con guiones (-). Por ejemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook ejecutable, genera lo siguiente según su indicador
optional:- Hook opcional (
optional: true):## Extension Hooks **Pre-Hook Opcional**: {extension} Comando: `/{command}` Descripción: {description} Mensaje: {prompt} Para ejecutar: `/{command}` - Hook obligatorio (
optional: false):
Después de emitir el bloque anterior DEBES invocar el hook y esperar a que termine antes de continuar. Ejecútalo de la misma manera que ejecutarías el comando tú mismo en este agente/sesión (la invocación puede diferir del ID literal## Extension Hooks **Pre-Hook Automático**: {extension} Ejecutando: `/{command}` EXECUTE_COMMAND: {command} Espera el resultado del comando del hook antes de proceder al Esquema.{command}mostrado arriba, por ejemplo, un agente en modo habilidades lo ejecuta como/skill:speckit-...o$speckit-...). Emitir el bloque solo no ejecuta el hook.
- Hook opcional (
- Si no hay hooks registrados o
.specify/extensions.ymlno existe, omite en silencio.
Esquema
El texto que el usuario escribió después de /speckit-specify en el mensaje desencadenante es la descripción de la funcionalidad. Asume que siempre lo tienes disponible en esta conversación incluso si $ARGUMENTS aparece literalmente a continuación. No le pidas al usuario que lo repita a menos que haya proporcionado un comando vacío.
Dada esa descripción de la funcionalidad, haz lo siguiente:
-
Genera un nombre corto y conciso (2-4 palabras) para la funcionalidad:
- Analiza la descripción de la funcionalidad y extrae las palabras clave más significativas.
- Crea un nombre corto de 2 a 4 palabras que capture la esencia de la funcionalidad.
- Usa el formato acción-sustantivo cuando sea posible (por ejemplo, "add-user-auth", "fix-payment-bug").
- Conserva términos técnicos y acrónimos (OAuth2, API, JWT, etc.).
- Mantenlo conciso pero lo suficientemente descriptivo para entender la funcionalidad de un vistazo.
- Ejemplos:
- "Quiero agregar autenticación de usuario" → "user-auth"
- "Implementar integración OAuth2 para la API" → "oauth2-api-integration"
- "Crear un panel de análisis" → "analytics-dashboard"
- "Corregir el error de tiempo de espera en el procesamiento de pagos" → "fix-payment-timeout"
-
Creación de rama (opcional, mediante hook):
Si un hook
before_specifyse ejecutó correctamente en las Verificaciones Pre-Ejecución anteriores, habrá creado/cambiado a una rama git y generado JSON que contieneBRANCH_NAMEyFEATURE_NUM. Ten en cuenta estos valores como referencia, pero el nombre de la rama no determina el nombre del directorio de la especificación.Si el usuario proporcionó explícitamente
GIT_BRANCH_NAME, pásalo al hook para que el script de la rama use el valor exacto como nombre de la rama (omitiendo toda generación de prefijos/sufijos). -
Crea el directorio de especificaciones de la funcionalidad:
Las especificaciones residen en el directorio predeterminado
specs/a menos que el usuario proporcione explícitamenteSPECIFY_FEATURE_DIRECTORY.Orden de resolución para
SPECIFY_FEATURE_DIRECTORY:- Si el usuario proporcionó explícitamente
SPECIFY_FEATURE_DIRECTORY(por ejemplo, mediante una variable de entorno, argumento o configuración), úsalo tal cual. - De lo contrario, genera automáticamente bajo
specs/:- Verifica
.specify/init-options.jsonparafeature_numbering(preferido) obranch_numbering(obsoleto, solo migración — se eliminará en una versión futura). - Si es
"timestamp": el prefijo esYYYYMMDD-HHMMSS(marca de tiempo actual). - Si es
"sequential"o está ausente: el prefijo esNNN(siguiente número de 3 dígitos disponible después de escanear los directorios existentes enspecs/). - Construye el nombre del directorio:
<prefijo>-<nombre-corto>(por ejemplo,003-user-autho20260319-143022-user-auth). - Establece
SPECIFY_FEATURE_DIRECTORYenspecs/<nombre-del-directorio>. - Si se usó
branch_numbering(yfeature_numberingestaba ausente), emite una advertencia de una línea: "⚠️branch_numberingen init-options.json está obsoleto. Renómbralo afeature_numbering."
- Verifica
Crea el directorio y el archivo de especificación:
mkdir -p SPECIFY_FEATURE_DIRECTORY- Resuelve el
spec-templateactivo a través de la pila de resolución de plantillas/preset de Spec Kit (equivalente aspecify preset resolve spec-template). - Copia el archivo
spec-templateresuelto enSPECIFY_FEATURE_DIRECTORY/spec.mdcomo punto de partida. - Establece
SPEC_FILEenSPECIFY_FEATURE_DIRECTORY/spec.md. - Persiste la ruta resuelta en
.specify/feature.json:Escribe el valor real de la ruta del directorio resuelto (por ejemplo,{ "feature_directory": "<directorio de funcionalidad resuelto>" }specs/003-user-auth), no la cadena literalSPECIFY_FEATURE_DIRECTORY. Esto permite que los comandos posteriores (/speckit-plan,/speckit-tasks, etc.) localicen el directorio de la funcionalidad sin depender de las convenciones de nombres de ramas git.
IMPORTANTE:
- Solo debes crear una funcionalidad por invocación de
/speckit-specify. - El nombre del directorio de la especificación y el nombre de la rama git son independientes: pueden ser iguales, pero eso es decisión del usuario.
- El directorio y el archivo de especificación siempre los crea este comando, nunca el hook.
- Si el usuario proporcionó explícitamente
-
Carga el archivo
spec-templateactivo resuelto para comprender las secciones requeridas. -
SI EXISTE: Carga
.specify/memory/constitution.mdpara los principios del proyecto y las restricciones de gobernanza. -
Sigue este flujo de ejecución:
- Analiza la descripción del usuario a partir de los argumentos. Si está vacía: ERROR "No se proporcionó una descripción de la funcionalidad".
- Extrae los conceptos clave de la descripción. Identifica: actores, acciones, datos, restricciones.
- Para aspectos poco claros:
- Haz suposiciones informadas basadas en el contexto y los estándares de la industria.
- Solo marca con [NECESITA ACLARACIÓN: pregunta específica] si:
- La elección afecta significativamente el alcance de la funcionalidad o la experiencia del usuario.
- Existen múltiples interpretaciones razonables con diferentes implicaciones.
- No existe un valor predeterminado razonable.
- LÍMITE: Máximo 3 marcadores [NECESITA ACLARACIÓN] en total.
- Prioriza las aclaraciones por impacto: alcance > seguridad/privacidad > experiencia del usuario > detalles técnicos.
- Completa la sección de Escenarios de Usuario y Pruebas. Si no hay un flujo de usuario claro: ERROR "No se pueden determinar los escenarios de usuario".
- Genera los Requisitos Funcionales. Cada requisito debe ser comprobable. Usa valores predeterminados razonables para detalles no especificados (documenta las suposiciones en la sección de Suposiciones).
- Define los Criterios de Éxito. Crea resultados medibles y agnósticos a la tecnología. Incluye tanto métricas cuantitativas (tiempo, rendimiento, volumen) como medidas cualitativas (satisfacción del usuario, finalización de tareas). Cada criterio debe ser verificable sin detalles de implementación.
- Identifica las Entidades Clave (si los datos están involucrados).
- Devuelve: ÉXITO (especificación lista para planificar).
-
Escribe la especificación en
SPEC_FILEusando la estructura de la plantilla, reemplazando los marcadores de posición con detalles concretos derivados de la descripción de la funcionalidad (argumentos) mientras conservas el orden de las secciones y los encabezados. -
Validación de Calidad de la Especificación: Después de escribir la especificación inicial, valídala según los criterios de calidad:
a. Crear Lista de Verificación de Calidad de la Especificación: Genera un archivo de lista de verificación en
SPECIFY_FEATURE_DIRECTORY/checklists/requirements.mdusando la estructura de la plantilla de lista de verificación con estos elementos de validación:# Lista de Verificación de Calidad de la Especificación: [NOMBRE DE LA FUNCIONALIDAD] **Propósito**: Validar la integridad y calidad de la especificación antes de proceder a la planificación **Creado**: [FECHA] **Funcionalidad**: [Enlace a spec.md] ## Calidad del Contenido - [ ] Sin detalles de implementación (lenguajes, frameworks, API) - [ ] Enfocado en el valor para el usuario y las necesidades del negocio - [ ] Escrito para partes interesadas no técnicas - [ ] Todas las secciones obligatorias completadas ## Integridad de los Requisitos - [ ] No quedan marcadores [NECESITA ACLARACIÓN] - [ ] Los requisitos son comprobables e inequívocos - [ ] Los criterios de éxito son medibles - [ ] Los criterios de éxito son agnósticos a la tecnología (sin detalles de implementación) - [ ] Todos los escenarios de aceptación están definidos - [ ] Se identifican los casos extremos - [ ] El alcance está claramente delimitado - [ ] Dependencias y suposiciones identificadas ## Preparación de la Funcionalidad - [ ] Todos los requisitos funcionales tienen criterios de aceptación claros - [ ] Los escenarios de usuario cubren los flujos principales - [ ] La funcionalidad cumple con los resultados medibles definidos en los Criterios de Éxito - [ ] No hay filtraciones de detalles de implementación en la especificación ## Notas - Los elementos marcados como incompletos requieren actualizaciones en la especificación antes de `/speckit-clarify` o `/speckit-plan`b. Ejecutar Verificación de Validación: Revisa la especificación según cada elemento de la lista de verificación:
- Para cada elemento, determina si pasa o falla.
- Documenta los problemas específicos encontrados (cita las secciones relevantes de la especificación).
c. Manejar Resultados de Validación:
-
Si todos los elementos pasan: Marca la lista de verificación como completa y procede a la sección de Hooks Obligatorios Post-Ejecución.
-
Si los elementos fallan (excluyendo [NECESITA ACLARACIÓN]):
- Enumera los elementos que fallan y los problemas específicos.
- Actualiza la especificación para solucionar cada problema.
- Vuelve a ejecutar la validación hasta que todos los elementos pasen (máximo 3 iteraciones).
- Si aún falla después de 3 iteraciones, documenta los problemas restantes en las notas de la lista de verificación y advierte al usuario.
-
Si quedan marcadores [NECESITA ACLARACIÓN]:
-
Extrae todos los marcadores [NECESITA ACLARACIÓN: ...] de la especificación.
-
VERIFICACIÓN DE LÍMITE: Si existen más de 3 marcadores, conserva solo los 3 más críticos (por alcance/seguridad/impacto en UX) y haz suposiciones informadas para el resto.
-
Para cada aclaración necesaria (máximo 3), presenta opciones al usuario en este formato:
## Pregunta [N]: [Tema] **Contexto**: [Cita la sección relevante de la especificación] **Lo que necesitamos saber**: [Pregunta específica del marcador NECESITA ACLARACIÓN] **Respuestas Sugeridas**: | Opción | Respuesta | Implicaciones | |--------|------------|---------------| | A | [Primera respuesta sugerida] | [Lo que esto significa para la funcionalidad] | | B | [Segunda respuesta sugerida] | [Lo que esto significa para la funcionalidad] | | C | [Tercera respuesta sugerida] | [Lo que esto significa para la funcionalidad] | | Personalizada | Proporciona tu propia respuesta | [Explica cómo proporcionar entrada personalizada] | **Tu elección**: _[Esperar respuesta del usuario]_ -
CRÍTICO - Formato de Tabla: Asegúrate de que las tablas de Markdown tengan el formato adecuado:
- Usa espaciado consistente con barras verticales alineadas.
- Cada celda debe tener espacios alrededor del contenido:
| Contenido |no|Contenido|. - El separador de encabezado debe tener al menos 3 guiones:
|--------|. - Prueba que la tabla se renderice correctamente en la vista previa de Markdown.
-
Numera las preguntas secuencialmente (Q1, Q2, Q3 - máximo 3 en total).
-
Presenta todas las preguntas juntas antes de esperar las respuestas.
-
Espera a que el usuario responda con sus elecciones para todas las preguntas (por ejemplo, "Q1: A, Q2: Personalizada - [detalles], Q3: B").
-
Actualiza la especificación reemplazando cada marcador [NECESITA ACLARACIÓN] con la respuesta seleccionada o proporcionada por el usuario.
-
Vuelve a ejecutar la validación después de que se resuelvan todas las aclaraciones.
-
d. Actualizar Lista de Verificación: Después de cada iteración de validación, actualiza el archivo de la lista de verificación con el estado actual de pasa/falla.
Hooks Obligatorios Post-Ejecución
DEBES completar esta sección antes de informar la finalización al usuario.
Verifica si existe .specify/extensions.yml en la raíz del proyecto.
- Si no existe, o no hay hooks registrados bajo
hooks.after_specify, salta al Informe de Finalización. - Si existe, léelo y busca las entradas bajo la clave
hooks.after_specify. - Si el YAML no se puede analizar o no es válido, no lo omitas en silencio: informa al usuario que
.specify/extensions.ymlno se pudo leer (incluye el error del analizador) y que no se revisaron los hooks, incluidos los obligatorios (optional: false) registrados allí, luego continúa al Informe de Finalización. - Filtra aquellos hooks donde
enabledesté explícitamente enfalse. Trata los hooks sin un campoenabledcomo habilitados por defecto. - Para cada hook restante, no intentes interpretar ni evaluar las expresiones de
conditiondel hook:- Si el hook no tiene un campo
condition, o es nulo/vacío, trata el hook como ejecutable. - Si el hook define una
conditionno vacía, omite el hook y deja la evaluación de la condición a la implementación de HookExecutor.
- Si el hook no tiene un campo
- Al construir las invocaciones de comando a partir de los nombres de comando del hook, reemplaza los puntos (
.) con guiones (-). Por ejemplo,speckit.git.commit→/speckit-git-commit. - Para cada hook ejecutable, genera lo siguiente según su indicador
optional:- Hook obligatorio (
optional: false) — DEBES emitirEXECUTE_COMMAND:para cada hook obligatorio:## Extension Hooks **Hook Automático**: {extension} Ejecutando: `
- Hook obligatorio (
...
(El contenido continúa, pero se ha truncado para la traducción)