El comando /speckit.clarify

Por qué clarificar antes de planificar

La primera versión de una especificación generada por /speckit.specify captura la intención general de la funcionalidad, pero rara vez cubre todos los detalles necesarios. Existen zonas grises que el prompt original no abordó: comportamientos en situaciones límite, interacciones entre funcionalidades, restricciones de negocio implícitas y decisiones de diseño que el equipo no ha tomado conscientemente.

Si estas ambigüedades llegan a la fase de planificación sin resolver, el agente IA las resolverá por su cuenta. El modelo de lenguaje no se detendrá ante un requisito vago: inventará una interpretación plausible y continuará. Esa interpretación puede ser correcta o no, pero en cualquier caso será una decisión que nadie ha validado.

Resolver ambigüedades en la especificación cuesta minutos. Resolverlas en la implementación cuesta horas. Resolverlas en producción cuesta días.

El comando /speckit.clarify existe para cerrar esas zonas grises de forma estructurada y documentada. En lugar de que el equipo revise el spec.md manualmente buscando puntos vagos, el agente IA analiza la especificación de forma sistemática y genera preguntas concretas sobre los aspectos que necesitan más detalle.

Cómo funciona el comando

El comando /speckit.clarify se ejecuta después de haber generado (o actualizado) un spec.md con /speckit.specify. Se escribe directamente en el chat del agente:

/speckit.clarify

No requiere argumentos adicionales. El agente realiza las siguientes acciones al recibir el comando:

• 1. Lee el spec.md actual de la feature activa en la rama de trabajo.

• 2. Analiza cada sección buscando puntos ambiguos, infraespecificados o que contengan marcadores [NEEDS CLARIFICATION].

• 3. Genera una serie de preguntas sobre los aspectos que necesitan aclaración. Cada pregunta incluye opciones de respuesta predefinidas para facilitar la toma de decisiones.

• 4. Espera las respuestas del usuario para cada pregunta. El usuario puede seleccionar una opción propuesta o proporcionar su propia respuesta.

• 5. Actualiza el spec.md con las decisiones tomadas, resolviendo los marcadores [NEEDS CLARIFICATION] y añadiendo nuevos criterios de aceptación o edge cases según las respuestas.

flowchart TB
    SPEC["spec.md con<br>ambigüedades"] --> CLARIFY["/speckit.clarify"]
    CLARIFY --> Q1["Pregunta 1<br>con opciones A, B, C"]
    CLARIFY --> Q2["Pregunta 2<br>con opciones A, B, C"]
    CLARIFY --> Q3["Pregunta 3<br>con opciones A, B, C"]
    Q1 --> RESP["Respuestas<br>del usuario"]
    Q2 --> RESP
    Q3 --> RESP
    RESP --> SPEC2["spec.md<br>actualizado"]

Ejemplo de una sesión de clarificación

Supongamos que se ha especificado un sistema de notificaciones para una plataforma educativa. Tras ejecutar /speckit.clarify, el agente podría generar las siguientes preguntas:

He identificado 4 áreas que necesitan clarificación
en la especificación actual:

Pregunta 1: Las notificaciones en tiempo real,
¿deben entregarse también cuando la aplicación
está cerrada (push notifications), o solo cuando
el usuario tiene la aplicación abierta?

  A) Solo dentro de la aplicación (in-app)
  B) In-app + push notifications en navegador
  C) In-app + push notifications en navegador y móvil

Pregunta 2: Cuando un profesor envía una notificación
a un grupo, ¿los alumnos que se unan al grupo después
del envío deben recibir las notificaciones anteriores?

  A) No, solo reciben notificaciones futuras
  B) Sí, reciben todas las notificaciones históricas
  C) Reciben las notificaciones de los últimos 30 días

Pregunta 3: Las estadísticas de lectura, ¿deben
actualizarse en tiempo real o es aceptable un retraso?

  A) Tiempo real (actualización instantánea)
  B) Actualización cada 5 minutos
  C) Actualización bajo demanda cuando el profesor
     consulta las estadísticas

Pregunta 4: ¿Existe un límite en la longitud del
contenido de una notificación?

  A) Sin límite
  B) Máximo 500 caracteres
  C) Máximo 2000 caracteres con soporte de formato
     (negrita, enlaces)

El usuario responde seleccionando una opción para cada pregunta (por ejemplo, "1: B, 2: A, 3: C, 4: C") o proporcionando una respuesta personalizada. El agente incorpora estas decisiones al spec.md, transformando puntos ambiguos en requisitos concretos.

Qué busca el agente al clarificar

El agente IA aplica un conjunto de heurísticas para detectar puntos que necesitan clarificación. Los patrones más comunes que identifica son:

Comportamientos no definidos en estados límite: la especificación describe el flujo principal (happy path) pero no dice qué ocurre cuando algo falla o cuando los datos están en un estado inesperado. Por ejemplo: "el usuario sube una imagen de perfil" pero no define qué pasa si la imagen es demasiado grande, tiene un formato no soportado o está corrupta.

Decisiones de diseño implícitas: la especificación asume que ciertos comportamientos son obvios, pero existen múltiples alternativas válidas. Por ejemplo: "el usuario puede filtrar productos por precio" no define si el filtro es un rango con dos campos, un slider, una lista de rangos predefinidos o una combinación de estos.

Requisitos cuantitativos ausentes: la especificación menciona atributos de calidad sin cuantificarlos. "El sistema debe ser rápido" no es accionable. "La búsqueda debe devolver resultados en menos de 300ms" sí lo es.

Interacciones entre user stories: cada user story funciona de forma aislada, pero la especificación no define cómo interactúan entre sí. Por ejemplo: si US-1 define "crear un evento" y US-3 define "compartir un evento por enlace", la especificación no dice qué ocurre si se modifica un evento que ya ha sido compartido.

Alcance no delimitado: la especificación describe una funcionalidad sin definir sus límites. "Los usuarios pueden personalizar su perfil" abre un abanico de posibilidades (avatar, biografía, tema visual, idioma, zona horaria). El comando /speckit.clarify pregunta qué elementos concretos abarca la personalización.

El comando /speckit.clarify no inventa requisitos. Identifica los puntos donde la especificación actual no proporciona suficiente información para que el agente IA tome decisiones durante la planificación.

Cuándo usar clarify

El comando /speckit.clarify es opcional en el flujo SDD. No es necesario ejecutarlo para cada especificación. La decisión de usarlo depende de la complejidad de la feature y de la confianza del equipo en la completitud de la especificación.

Situaciones donde clarify aporta valor:

• La feature interactúa con múltiples componentes existentes del sistema.
• El prompt de especificación fue breve o dejó aspectos abiertos intencionalmente.
• El equipo no tiene experiencia con el dominio de la funcionalidad.
• La especificación contiene múltiples marcadores [NEEDS CLARIFICATION].

Situaciones donde clarify puede omitirse:

• La feature es sencilla y el equipo tiene claro cómo debe funcionar.
• El prompt de especificación fue muy detallado y la especificación generada es completa.
• El equipo prefiere resolver las ambigüedades manualmente editando el spec.md.

Ejecutar clarify varias veces

El comando /speckit.clarify puede ejecutarse más de una vez sobre la misma especificación. Cada ejecución analiza la versión actual del spec.md y genera preguntas sobre los puntos que siguen siendo ambiguos. A medida que el spec.md se va completando con las respuestas del usuario, las ejecuciones posteriores de clarify generan menos preguntas y más específicas.

flowchart TB
    C1["/speckit.clarify<br>5 preguntas"] --> R1["Respuestas"]
    R1 --> SPEC1["spec.md<br>actualizado"]
    SPEC1 --> C2["/speckit.clarify<br>2 preguntas"]
    C2 --> R2["Respuestas"]
    R2 --> SPEC2["spec.md<br>completo"]
    SPEC2 --> PLAN["/speckit.plan"]

Este patrón iterativo es natural y esperado. La primera ejecución resuelve las ambigüedades más evidentes. La segunda puede descubrir nuevas ambigüedades que surgieron como consecuencia de las decisiones tomadas en la primera ronda.

Cómo el clarify actualiza el spec.md

Tras recibir las respuestas del usuario, el agente IA modifica el spec.md de tres formas principales:

Resuelve marcadores [NEEDS CLARIFICATION]: cada marcador asociado a una pregunta que el usuario ha respondido se reemplaza por un criterio de aceptación concreto. Si la pregunta era "Should shared links expire?" y la respuesta fue "Yes, after 7 days", el marcador se convierte en un criterio: "Shared links expire after 7 days of inactivity".

Añade nuevos criterios de aceptación: las respuestas del usuario pueden revelar requisitos que no existían en la versión original. Estos se incorporan a las user stories correspondientes como nuevos criterios.

Documenta edge cases resueltos: las decisiones sobre comportamiento en situaciones límite se documentan en la sección de edge cases del spec.md, con la situación y la decisión explícita.

El resultado es un spec.md más denso y preciso que su versión anterior. Cada ejecución de clarify reduce la brecha entre la intención del equipo y lo que está documentado, acercando la especificación al nivel de detalle que la fase de planificación necesita para producir un plan técnico sólido.

Clarify como herramienta de comunicación

Más allá de su función técnica, el comando /speckit.clarify es una herramienta de comunicación entre los diferentes roles del equipo. Las preguntas que genera el agente funcionan como una lista de puntos de decisión que puede compartirse con product managers, diseñadores o stakeholders.

En lugar de enviar un spec.md completo y pedir "revisadlo", el equipo puede ejecutar clarify, copiar las preguntas generadas y enviarlas a las personas responsables de cada área. Las respuestas se incorporan al spec.md, creando un registro documentado de quién decidió qué y por qué.

Este registro tiene valor a largo plazo. Cuando meses después alguien pregunta "por qué las notificaciones no se envían como push notifications fuera de la aplicación", la respuesta está documentada en el spec.md: "Pregunta de clarificación: solo in-app por decisión del equipo de producto (fecha)".