El comando /speckit.checklist

Unit tests para requisitos

En el desarrollo de software, los tests unitarios validan que el código cumple con su especificación. El comando /speckit.checklist aplica la misma idea a una fase anterior del proceso: valida que las especificaciones cumplen con los estándares de calidad necesarios para producir una buena implementación.

La diferencia fundamental es lo que se evalúa. Los tests unitarios verifican si el código funciona correctamente. Las checklists de /speckit.checklist verifican si los requisitos están bien escritos: si son completos, claros, consistentes, cubren los edge cases y tienen criterios medibles de aceptación.

Un requisito mal escrito produce una implementación técnicamente correcta pero funcionalmente inadecuada. Los unit tests del código pasarán, porque el código hace lo que el requisito decía. Pero el requisito decía algo incorrecto o incompleto.

La detección temprana de problemas en los requisitos tiene un impacto directo en el coste del proyecto. Corregir un requisito ambiguo antes de la implementación cuesta minutos. Corregirlo después de la implementación puede requerir reescribir servicios, endpoints, tests y documentación.

Cómo ejecutar el comando

El comando se ejecuta en el chat del agente IA después de la fase de planificación:

/speckit.checklist

El flujo recomendado sitúa la checklist después de /speckit.plan y antes de /speckit.tasks:

flowchart LR
    SPECIFY["/speckit.specify"] --> PLAN["/speckit.plan"]
    PLAN --> CHECKLIST["/speckit.checklist"]
    CHECKLIST -->|Sin gaps| TASKS["/speckit.tasks"]
    CHECKLIST -->|Gaps detectados| FIX["Corregir spec.md"]
    FIX --> PLAN

Al recibir el comando, el agente:

• 1. Lee el spec.md de la feature activa para extraer las user stories, criterios de aceptación y requisitos no funcionales.

• 2. Lee el plan.md para verificar la coherencia entre lo especificado y lo planificado.

• 3. Lee la constitución para aplicar los principios del proyecto como criterios adicionales de validación.

• 4. Genera la checklist evaluando cada requisito contra los cinco criterios de calidad.

• 5. Escribe el resultado en el archivo checklists/requirements.md dentro del directorio de la feature.

Los cinco criterios de validación

La checklist evalúa cada requisito del spec.md contra cinco criterios de calidad. Cada criterio detecta un tipo diferente de deficiencia en la especificación:

Completitud

El criterio de completitud verifica que todos los aspectos necesarios de la feature están especificados. Un requisito incompleto es aquel que describe el happy path pero omite los escenarios alternativos, los estados de error o los casos límite.

## Completeness Check

- [x] User story for event creation defined
- [x] Acceptance criteria for valid events
- [ ] [Gap] No error handling specified for
      duplicate events
- [ ] [Gap] No specification for concurrent
      event creation
- [x] Data retention policy defined in NFRs

Los gaps marcados con [Gap] indican requisitos que necesitan añadirse al spec.md antes de proceder con la implementación.

Claridad

El criterio de claridad detecta requisitos que contienen términos ambiguos o subjetivos que pueden interpretarse de múltiples formas. Palabras como "rápido", "intuitivo", "suficiente" o "apropiado" son señales de ambigüedad.

## Clarity Check

- [x] "El evento debe crearse en menos de 200ms"
      (cuantificado)
- [ ] [Gap] "La interfaz debe ser intuitiva"
      (subjetivo, no medible)
- [x] "El título del evento admite hasta 200
      caracteres" (específico)
- [ ] [Gap] "El sistema debe manejar muchos
      eventos" (vago, sin cifra concreta)

Un requisito que no pasa el criterio de claridad necesita cuantificarse. "La interfaz debe ser intuitiva" se transforma en "El usuario puede crear un evento en menos de 3 clics desde la pantalla principal". "El sistema debe manejar muchos eventos" se convierte en "El sistema soporta al menos 10.000 eventos por usuario".

Consistencia

El criterio de consistencia compara los requisitos entre sí y con los artefactos del plan para detectar contradicciones. Un requisito que dice "la autenticación es obligatoria" y otro que dice "los usuarios anónimos pueden ver eventos públicos" no son necesariamente inconsistentes, pero requieren que la especificación defina explícitamente el límite entre ambos escenarios.

## Consistency Check

- [x] Terminology consistent across user stories
- [ ] [Gap] NFR says "response < 200ms" but
      plan.md constraint says "< 500ms p95"
- [x] Data model aligns with acceptance criteria
- [x] API contracts match user story flows

Cobertura

El criterio de cobertura verifica que la especificación contempla edge cases, accesibilidad y seguridad. Una especificación que solo describe el flujo principal deja margen para que la implementación ignore escenarios relevantes.

## Coverage Check

- [x] Input validation for all user-facing fields
- [ ] [Gap] No accessibility requirements defined
- [x] Rate limiting specified in NFRs
- [ ] [Gap] No specification for timezone handling
      in event dates
- [x] Data export format documented (iCalendar)

Medibilidad

El criterio de medibilidad evalúa si cada criterio de aceptación puede verificarse de forma objetiva. Un criterio medible permite escribir un test que lo valide. Un criterio no medible requiere juicio humano subjetivo.

## Measurability Check

- [x] "POST /api/events returns 201 with valid
      data" (verificable con test)
- [x] "Invalid date range returns 422 with error
      detail" (verificable con test)
- [ ] [Gap] "The calendar export should look
      professional" (no verificable)
- [x] "Export generates valid RFC 5545 iCalendar
      file" (verificable con parser)

Interpretar el informe de la checklist

El informe generado por /speckit.checklist se escribe en checklists/requirements.md y presenta los resultados organizados por criterio. Al final del informe, un resumen cuantifica el estado general:

CHECKLIST SUMMARY

Completeness:   8/10 checks passed (2 gaps)
Clarity:        6/8  checks passed (2 gaps)
Consistency:    3/4  checks passed (1 gap)
Coverage:       5/7  checks passed (2 gaps)
Measurability:  4/5  checks passed (1 gap)

Total:          26/34 checks passed
Gaps found:     8

Los gaps no son errores de implementación. Son oportunidades de mejora en la especificación. Un spec.md con 8 gaps no es un fracaso. Es una especificación que tiene 8 puntos concretos donde puede mejorar antes de invertir tiempo en la implementación.

Una especificación con cero gaps es poco habitual en la primera iteración. Lo importante no es la cantidad de gaps, sino que cada gap se resuelve antes de llegar a la fase de implementación.

Resolver gaps detectados

Cuando la checklist identifica gaps, el flujo habitual es modificar el spec.md para cubrir los puntos pendientes y después volver a ejecutar el comando para verificar que los gaps se han resuelto.

El proceso de resolución tiene una consideración importante: si el spec.md se modifica, el plan.md podría necesitar actualizarse. Esto puede crear una situación donde el equipo edita el spec.md, regenera el plan con /speckit.plan y descubre que la regeneración ha sobrescrito ajustes manuales que había hecho en el plan anterior.

La práctica recomendada para evitar este problema es:

• 1. Editar el spec.md para resolver los gaps.
• 2. Ejecutar /speckit.plan con instrucciones específicas para que el agente actualice el plan existente en lugar de regenerarlo desde cero.
• 3. Ejecutar /speckit.checklist de nuevo para verificar que los gaps se han resuelto.

/speckit.plan

Actualiza el plan existente para reflejar los
cambios en el spec.md. No regeneres el plan
desde cero. Mantén las decisiones técnicas
validadas y solo ajusta las secciones afectadas
por los nuevos requisitos.

Esta instrucción explícita al agente preserva el trabajo previo de planificación y solo modifica las secciones afectadas por los cambios en la especificación.

Checklist en el flujo SDD

El comando /speckit.checklist es opcional en el flujo SDD. Un equipo puede pasar directamente de /speckit.plan a /speckit.tasks sin ejecutar la checklist. Sin embargo, omitir este paso aumenta el riesgo de que la implementación produzca código que no cubre todos los escenarios necesarios.

flowchart LR
    subgraph Flujo["Flujo SDD completo"]
        SPECIFY["/speckit.specify"]
        CLARIFY["/speckit.clarify"]
        PLAN["/speckit.plan"]
        CHECKLIST["/speckit.checklist"]
        TASKS["/speckit.tasks"]
        ANALYZE["/speckit.analyze"]
        IMPLEMENT["/speckit.implement"]
    end
    SPECIFY --> CLARIFY
    CLARIFY --> PLAN
    PLAN --> CHECKLIST
    CHECKLIST --> TASKS
    TASKS --> ANALYZE
    ANALYZE --> IMPLEMENT

La checklist complementa al comando /speckit.analyze. Mientras que analyze valida la consistencia entre artefactos (que el plan sea coherente con la especificación y las tareas), la checklist valida la calidad intrínseca de los requisitos (que los requisitos sean completos, claros y medibles independientemente de los demás artefactos).

Ambos comandos son operaciones de solo lectura que no modifican los artefactos del proyecto. Generan informes que el equipo utiliza para decidir si los artefactos están preparados para avanzar a la siguiente fase.

Checklist como práctica de equipo

En equipos que adoptan SDD como metodología estándar, la checklist se integra como un paso rutinario del proceso de especificación. Los gaps recurrentes (por ejemplo, la omisión sistemática de requisitos de accesibilidad o de manejo de errores) se convierten en indicadores de mejora del proceso.

Si un equipo detecta que en todas las features aparecen gaps de cobertura relacionados con la accesibilidad, puede actualizar la constitución del proyecto para incluir un principio que obligue a definir requisitos de accesibilidad en cada especificación. Este ajuste hace que el agente incluya automáticamente secciones de accesibilidad en los specs futuros, eliminando la clase de gap de forma sistémica.

La checklist también sirve como herramienta de onboarding. Un nuevo miembro del equipo puede revisar las checklists de features anteriores para entender qué nivel de detalle se espera en las especificaciones y qué tipos de gaps son más frecuentes.