Entrada del usuario
$ARGUMENTS
DEBES considerar la entrada del usuario antes de continuar (si no está vacía).
Comprobaciones previas a la ejecución
Verificar ganchos de extensión (antes de la clarificación):
- Comprueba si existe
.specify/extensions.ymlen la raíz del proyecto. - Si existe, léelo y busca entradas bajo la clave
hooks.before_clarify. - Si el YAML no se puede analizar o no es válido, no lo omitas en silencio: informa al usuario de que
.specify/extensions.ymlno se pudo leer (incluye el error del analizador) y que no se comprobaron ganchos, incluidos los obligatorios (optional: false) registrados allí, luego continúa normalmente. - Filtra los ganchos donde
enabledsea explícitamentefalse. Trata los ganchos sin un campoenabledcomo habilitados por defecto. - Para cada gancho restante, no intentes interpretar o evaluar las expresiones de
conditiondel gancho:- Si el gancho no tiene un campo
condition, o es nulo/vacío, trata el gancho como ejecutable. - Si el gancho define una
conditionno vacía, omítelo y deja la evaluación de la condición a la implementación de HookExecutor.
- Si el gancho no tiene un campo
- Al construir invocaciones de comandos a partir de nombres de comando de gancho, reemplaza los puntos (
.) con guiones (-). Por ejemplo,speckit.git.commit→/speckit-git-commit. - Para cada gancho ejecutable, muestra lo siguiente según su indicador
optional:- Gancho opcional (
optional: true):## Extension Hooks **Optional Pre-Hook**: {extension} Command: `/{command}` Description: {description} Prompt: {prompt} To execute: `/{command}` - Gancho obligatorio (
optional: false):
Después de emitir el bloque anterior, DEBES invocar el gancho 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## Extension Hooks **Automatic Pre-Hook**: {extension} Executing: `/{command}` EXECUTE_COMMAND: {command} Wait for the result of the hook command before proceeding to the Outline.{command}literal mostrado arriba, por ejemplo, un agente en modo skills lo ejecuta como/skill:speckit-...o$speckit-...). Emitir el bloque solo no ejecuta el gancho.
- Gancho opcional (
- Si no hay ganchos registrados o no existe
.specify/extensions.yml, omítelo en silencio.
Esquema
Objetivo: Detectar y reducir la ambigüedad o los puntos de decisión faltantes en la especificación activa de la característica y registrar las aclaraciones directamente en el archivo de especificación.
Nota: Se espera que este flujo de trabajo de aclaración se ejecute (y se complete) ANTES de invocar /speckit-plan. Si el usuario indica explícitamente que está omitiendo la aclaración (por ejemplo, un spike exploratorio), puedes continuar, pero debes advertir que aumenta el riesgo de retrabajo posterior.
Pasos de ejecución:
-
Ejecuta
.specify/scripts/bash/check-prerequisites.sh --json --paths-onlydesde la raíz del repositorio una vez (modo combinado--json --paths-only/-Json -PathsOnly). Analiza los campos mínimos de la carga útil JSON:FEATURE_DIRFEATURE_SPEC- (Opcionalmente, captura
IMPL_PLAN,TASKSpara flujos encadenados futuros). - Si el análisis JSON falla, aborta e indica al usuario que vuelva a ejecutar
/speckit-specifyo que verifique el entorno de la rama de la característica. - Para comillas simples en argumentos como "I'm Groot", usa la sintaxis de escape: ej. 'I'''m Groot' (o entre comillas dobles si es posible: "I'm Groot").
-
SI EXISTE: Carga
.specify/memory/constitution.mdpara conocer los principios del proyecto y las restricciones de gobierno. -
Carga el archivo de especificación actual. Realiza un escaneo estructurado de ambigüedad y cobertura utilizando esta taxonomía. Para cada categoría, marca el estado: Claro / Parcial / Ausente. Produce un mapa de cobertura interno utilizado para la priorización (no muestres el mapa sin procesar a menos que no se hagan preguntas).
Alcance funcional y comportamiento:
- Objetivos principales del usuario y criterios de éxito
- Declaraciones explícitas fuera del alcance
- Roles de usuario / diferenciación de personas
Modelo de dominio y datos:
- Entidades, atributos, relaciones
- Reglas de identidad y unicidad
- Transiciones de ciclo de vida/estado
- Suposiciones de volumen de datos/escala
Interacción y flujo de UX:
- Recorridos/secuencias de usuario críticos
- Estados de error/vacío/carga
- Notas de accesibilidad o localización
Atributos de calidad no funcionales:
- Rendimiento (objetivos de latencia, rendimiento)
- Escalabilidad (horizontal/vertical, límites)
- Fiabilidad y disponibilidad (tiempo de actividad, expectativas de recuperación)
- Observabilidad (señales de registro, métricas, trazado)
- Seguridad y privacidad (autenticación/autorización, protección de datos, suposiciones de amenazas)
- Restricciones de cumplimiento/regulatorias (si las hay)
Integración y dependencias externas:
- Servicios/API externos y modos de fallo
- Formatos de importación/exportación de datos
- Suposiciones de protocolo/versionado
Casos extremos y manejo de fallos:
- Escenarios negativos
- Límite de velocidad / estrangulamiento
- Resolución de conflictos (ej., ediciones concurrentes)
Restricciones y compensaciones:
- Restricciones técnicas (lenguaje, almacenamiento, alojamiento)
- Compensaciones explícitas o alternativas rechazadas
Terminología y coherencia:
- Términos del glosario canónico
- Sinónimos evitados / términos obsoletos
Señales de finalización:
- Capacidad de prueba de los criterios de aceptación
- Indicadores medibles de estilo Definición de Hecho
Varios / Marcadores de posición:
- Marcadores TODO / decisiones no resueltas
- Adjetivos ambiguos ("robusto", "intuitivo") que carecen de cuantificación
Para cada categoría con estado Parcial o Ausente, agrega una oportunidad de pregunta candidata a menos que:
- La aclaración no cambie materialmente la estrategia de implementación o validación.
- El elemento se trate específicamente sobre el método de implementación, la comparación de pilas tecnológicas o el desglose de tareas (anótalo internamente).
-
Genera (internamente) una cola priorizada de preguntas de aclaración candidatas (máximo 5). NO las muestres todas a la vez. Aplica estas restricciones:
- Máximo de 5 preguntas en total en toda la sesión.
- Cada pregunta debe poder responderse con:
- Una selección breve de opción múltiple (2–5 opciones distintas y mutuamente excluyentes), O
- Una respuesta de una palabra / frase corta (restringe explícitamente: "Responde en <=5 palabras").
- Solo incluye preguntas cuyas respuestas impacten materialmente en la arquitectura, el modelado de datos, el desglose de tareas, el diseño de pruebas, el comportamiento de UX, la preparación operativa o la validación de cumplimiento.
- Asegura un equilibrio de cobertura de categorías: intenta cubrir primero las categorías no resueltas de mayor impacto; evita hacer dos preguntas de bajo impacto cuando una sola área de alto impacto (ej., postura de seguridad) no está resuelta.
- Excluye preguntas ya respondidas, preferencias estilísticas triviales o detalles de ejecución a nivel de plan (a menos que bloqueen la corrección).
- Favorece las aclaraciones que reduzcan el riesgo de retrabajo posterior o eviten pruebas de aceptación desalineadas.
- Si más de 5 categorías permanecen sin resolver, selecciona las 5 principales según la heurística (Impacto * Incertidumbre).
-
Bucle de preguntas secuencial (interactivo):
-
Presenta EXACTAMENTE UNA pregunta a la vez.
-
Calidad de redacción de la pregunta (se aplica a cada pregunta, de opción múltiple o respuesta corta):
- Comienza con
**Pregunta:**seguido de una interrogativa completa que termine con?. El texto de la pregunta antes del?debe tener sentido por sí mismo. - NUNCA uses una etiqueta de tema, un encabezado de sección o un id de requisito como la pregunta en sí. Por ejemplo,
Matriz de dispositivo/tiempo de ejecución de aceptación (FR-023)es INVÁLIDO: es una etiqueta, no una pregunta. - Después del
?, el único sufijo permitido es un id de requisito/pregunta opcional entre paréntesis. Formato exacto:**Pregunta:** <interrogativa>?o**Pregunta:** <interrogativa>? (FR-023). Nunca pongas el id antes del?, y nunca uses el id (solo o con una etiqueta de tema) como todo el aviso. - Inmediatamente después de la línea de la pregunta, agrega una oración en lenguaje sencillo de "Por qué es importante" (la apuesta por la aceptación o el lanzamiento) antes de la recomendación/opciones.
- Usa redacción cotidiana; introduce jerga solo si se define en la misma oración. Autocomprobación: un lector que no conozca Spec Kit debe poder responder solo con la línea de la pregunta. La brevedad está bien; las etiquetas crípticas no.
- Comienza con
-
Para preguntas de opción múltiple:
- Analiza todas las opciones y determina la opción más adecuada en función de:
- Mejores prácticas para el tipo de proyecto
- Patrones comunes en implementaciones similares
- Reducción de riesgos (seguridad, rendimiento, mantenibilidad)
- Alineación con los objetivos o restricciones explícitos del proyecto visibles en la especificación
- Presenta tu opción recomendada de manera prominente en la parte superior con un razonamiento claro (1-2 oraciones que expliquen por qué esta es la mejor opción).
- Formatéalo como:
**Recomendada:** Opción [X] - <razonamiento> - Luego renderiza todas las opciones como una tabla de Markdown:
Opción Descripción A <Descripción de la opción A> B <Descripción de la opción B> C <Descripción de la opción C> (agrega D/E según sea necesario hasta 5) Corta Proporciona una respuesta corta diferente (<=5 palabras) (Incluir solo si la alternativa de formato libre es apropiada) - Después de la tabla, agrega:
Puedes responder con la letra de la opción (ej., "A"), aceptar la recomendación diciendo "sí" o "recomendada", o proporcionar tu propia respuesta corta.
- Analiza todas las opciones y determina la opción más adecuada en función de:
-
Para el estilo de respuesta corta (sin opciones discretas significativas):
- Proporciona tu respuesta sugerida según las mejores prácticas y el contexto.
- Formatéalo como:
**Sugerida:** <tu respuesta propuesta> - <razonamiento breve> - Luego muestra:
Formato: Respuesta corta (<=5 palabras). Puedes aceptar la sugerencia diciendo "sí" o "sugerida", o proporcionar tu propia respuesta.
-
Después de que el usuario responda:
- Si el usuario responde con "sí", "recomendada" o "sugerida", usa tu recomendación/sugerencia previamente indicada como respuesta.
- De lo contrario, valida que la respuesta se asigne a una opción o cumpla con la restricción de <=5 palabras.
- Si es ambiguo, pide una desambiguación rápida (el conteo aún pertenece a la misma pregunta; no avances).
- Una vez satisfactoria, regístrala en la memoria de trabajo (aún no la escribas en el disco) y pasa a la siguiente pregunta en cola.
-
Deja de hacer más preguntas cuando:
- Todas las ambigüedades críticas se resuelvan temprano (los elementos restantes en cola se vuelven innecesarios), O
- El usuario indique finalización ("hecho", "bien", "no más"), O
- Llegues a 5 preguntas formuladas.
-
Nunca reveles las preguntas futuras en cola con anticipación.
-
Si no existen preguntas válidas al inicio, informa inmediatamente que no hay ambigüedades críticas.
-
-
Integración después de CADA respuesta aceptada (enfoque de actualización incremental):
- Mantén una representación en memoria de la especificación (cargada una vez al inicio) más el contenido del archivo sin procesar.
- Para la primera respuesta integrada en esta sesión:
- Asegúrate de que exista una sección
## Aclaraciones(crea justo después de la sección contextual/de descripción general de más alto nivel según la plantilla de especificación si falta). - Debajo de ella, crea (si no está presente) un subtítulo
### Sesión YYYY-MM-DDpara hoy.
- Asegúrate de que exista una sección
- Agrega una línea de viñeta inmediatamente después de la aceptación:
- P: <pregunta> → R: <respuesta final>. - Luego aplica inmediatamente la aclaración a la(s) sección(es) más apropiada(s):
- Ambigüedad funcional → Actualiza o agrega una viñeta en Requisitos funcionales.
- Interacción del usuario / distinción de actor → Actualiza las subsecciones de Historias de usuario o Actores (si están presentes) con el rol, la restricción o el escenario aclarados.
- Forma de datos / entidades → Actualiza el Modelo de datos (agrega campos, tipos, relaciones) conservando el orden; anota las restricciones agregadas de manera concisa.
- Restricción no funcional → Agrega/modifica criterios medibles en Criterios de éxito > Resultados medibles (convierte el adjetivo vago en métrica o objetivo explícito).
- Caso extremo / flujo negativo → Agrega una nueva viñeta bajo Casos extremos / Manejo de errores (o crea dicha subsección si la plantilla proporciona un marcador de posición para ella).
- Conflicto de terminología → Normaliza el término en toda la especificación; conserva el original solo si es necesario agregando
(anteriormente conocido como "X")una vez.
- Si la aclaración invalida una declaración ambigua anterior, reemplaza esa declaración en lugar de duplicarla; no dejes texto obsoleto contradictorio.
- Guarda el archivo de especificación DESPUÉS de cada integración para minimizar el riesgo de pérdida de contexto (sobrescritura atómica).
- Conserva el formato: no reordenes secciones no relacionadas; mantén la jerarquía de encabezados intacta.
- Mantén cada aclaración insertada mínima y comprobable (evita la deriva narrativa).
-
Validación (realizada después de CADA escritura más una pasada final):
- La sesión de aclaraciones contiene exactamente una viñeta por respuesta aceptada (sin duplicados).
- Total de preguntas formuladas (aceptadas) ≤ 5.
- Las secciones actualizadas no contienen marcadores de posición vagos persistentes que la nueva respuesta debía resolver.
- No queda ninguna declaración contradictoria anterior (revisa si hay opciones alternativas ahora inválidas eliminadas).
- Estructura de Markdown válida; solo se permiten nuevos encabezados:
## Aclaraciones,### Sesión YYYY-MM-DD. - Coherencia terminológica: se usa el mismo término canónico en todas las secciones actualizadas.
-
Escribe la especificación actualizada de nuevo en
FEATURE_SPEC. -
Revalidar la lista de verificación de calidad de la especificación (si existe):
- Comprueba si existe
FEATURE_DIR/checklists/requirements.md. - Si NO existe, omite este paso en silencio.
- Si existe:
- Lee el archivo de la lista de verificación.
- Identifica todas las líneas de casillas de verificación de lista de tareas de GitHub: líneas que coinciden con
- [ ],- [x]o- [X](sin distinción entre mayúsculas y minúsculas, tolerante con espacios en blanco iniciales para elementos anidados) fuera de los bloques de código. Ignora todo el otro contenido (encabezados, notas, viñetas que no sean casillas de verificación, metadatos). - Para cada línea de casilla de verificación, registra su estado de marcador actual (marcada o desmarcada) y el texto del elemento en una lista de instantánea anterior.
- Reevalúa cada elemento de la casilla de verificación contra la especificación actualizada (la versión recién guardada en el paso 7).
- Para cada elemento de la casilla de verificación, actualiza solo si el estado marcado/desmarcado cambia realmente:
- Si el elemento ahora pasa y estaba desmarcado: cambia
[ ]a[x]. - Si el elemento ahora falla y estaba marcado: cambia
[x]/[X]a[ ]. - Si el estado no cambia:
- Si el elemento ahora pasa y estaba desmarcado: cambia
- Comprueba si existe
…
[truncado para la traducción]