El comando /speckit.analyze

Por qué analizar antes de implementar

A lo largo del flujo SDD, se generan tres artefactos principales: la especificación (spec.md), el plan técnico (plan.md) y las tareas (tasks.md). Cada uno se genera en una fase distinta, a menudo con diferentes conversaciones o sesiones con el agente IA. Esta separación temporal introduce un riesgo: que los artefactos se desalineen entre sí.

Un requisito de la especificación puede quedar sin reflejo en el plan técnico. Una decisión del plan puede no traducirse en ninguna tarea. Una tarea puede referirse a un contrato que no existe en contracts/. Estas inconsistencias son difíciles de detectar con una revisión manual, especialmente en features complejas con múltiples user stories.

Los artefactos de SDD forman una cadena: spec genera plan, plan genera tasks. Si un eslabón se desvía, toda la cadena posterior arrastra la desviación.

El comando /speckit.analyze existe para detectar estas desalineaciones de forma sistemática y automatizada. Es el equivalente a un linter, pero en lugar de validar sintaxis de código, valida la coherencia semántica entre documentos de especificación.

Cómo funciona el comando

El comando se ejecuta en el chat del agente sin argumentos adicionales:

/speckit.analyze

A diferencia de otros comandos de Spec Kit, /speckit.analyze es una operación de solo lectura. No modifica ningún archivo del proyecto. Su única salida es un informe de análisis que describe los hallazgos.

El comando requiere que existan los tres artefactos principales de la feature: spec.md, plan.md y tasks.md. Si alguno de ellos falta, el comando se detiene con un error indicando qué archivo es necesario generar antes de poder ejecutar el análisis.

flowchart LR
    SPEC["spec.md"] --> ANALYZE["/speckit.analyze"]
    PLAN["plan.md"] --> ANALYZE
    TASKS["tasks.md"] --> ANALYZE
    CONST["constitution.md"] --> ANALYZE
    ANALYZE --> REPORT["Informe de análisis"]

Secuencia de análisis

Al recibir el comando, el agente ejecuta una secuencia de validaciones:

• 1. Verifica los prerequisitos: comprueba que existen los tres archivos (spec.md, plan.md, tasks.md) en el directorio de la feature activa.

• 2. Carga la constitución: lee .specify/memory/constitution.md para usar sus principios como referencia de validación.

• 3. Construye un modelo semántico: mapea los requisitos funcionales del spec.md a las decisiones del plan.md y a las tareas del tasks.md, creando una red de trazabilidad.

• 4. Ejecuta las validaciones: compara los artefactos entre sí buscando inconsistencias, duplicaciones, ambigüedades y elementos infraespecificados.

• 5. Valida contra la constitución: verifica que ningún artefacto contradice los principios constitucionales del proyecto.

• 6. Genera el informe: presenta los hallazgos organizados por categoría y severidad.

Qué detecta el análisis

El comando /speckit.analyze busca cinco categorías de problemas en los artefactos:

Inconsistencias

Una inconsistencia ocurre cuando dos artefactos contienen información contradictoria. Ejemplos:

• El spec.md define que "los usuarios pueden exportar eventos en formato iCalendar", pero el plan.md no menciona la librería de generación de archivos .ics ni contempla esta funcionalidad en la estructura del proyecto.
• El plan.md define PostgreSQL como sistema de almacenamiento, pero una tarea en tasks.md referencia operaciones de MongoDB.
• Un criterio de aceptación del spec.md dice "respuesta en menos de 200ms", pero las restricciones del plan.md establecen "< 500ms p95".

INCONSISTENCY [HIGH]: El criterio de aceptación AC-3
de US-2 ("respuesta < 200ms") contradice la
restricción del plan ("< 500ms p95"). Resolver
la discrepancia antes de implementar.

Duplicaciones

Una duplicación aparece cuando el mismo concepto se describe en múltiples lugares con variaciones que pueden generar confusión. Un endpoint que se documenta tanto en contracts/ como en el cuerpo del plan.md con formatos de respuesta ligeramente diferentes es una duplicación problemática.

Ambigüedades

Una ambigüedad se detecta cuando un artefacto contiene información que puede interpretarse de múltiples formas. Marcadores [NEEDS CLARIFICATION] que no se resolvieron en la fase de especificación pero que llegaron al plan son el caso más evidente.

Elementos infraespecificados

Un elemento infraespecificado es un requisito del spec.md que no tiene cobertura suficiente en el plan o en las tareas. Si una user story define cinco criterios de aceptación pero solo tres de ellos se reflejan en tareas, los dos restantes son elementos infraespecificados.

UNDERSPECIFIED [MEDIUM]: El criterio de aceptación
AC-4 de US-1 ("el formulario valida que start_time
sea anterior a end_time") no tiene una tarea
asociada en tasks.md.

Violaciones de constitución

Las violaciones de constitución se detectan cuando algún artefacto contradice un principio establecido en .specify/memory/constitution.md. Estas violaciones tienen la severidad más alta (CRITICAL) y el informe las marca de forma prominente.

CRITICAL [CONSTITUTION]: El plan propone un patrón
Repository con interfaz abstracta, pero la
constitución establece Anti-Abstraction y solo
existe una implementación (PostgresRepository).
Justificar en Complexity Tracking o eliminar
la abstracción.

Las violaciones de constitución se tratan como no negociables. El principio constitucional prevalece sobre la decisión del plan, a menos que se documente una excepción en la tabla de Complexity Tracking con justificación explícita.

Cómo interpretar el informe

El informe que genera /speckit.analyze se estructura en secciones organizadas por tipo de hallazgo y severidad. Cada hallazgo incluye tres elementos:

• Categoría y severidad: identifica el tipo de problema (inconsistency, duplication, ambiguity, underspecified, constitution violation) y su nivel de gravedad (CRITICAL, HIGH, MEDIUM, LOW).
• Descripción del hallazgo: explica qué se ha detectado, referenciando los artefactos y secciones concretas donde aparece el problema.
• Artefactos afectados: lista los archivos y secciones involucrados para facilitar la localización del problema.

Un informe típico tiene esta estructura:

=== SPEC-KIT ANALYSIS REPORT ===
Feature: 001-crear-eventos-calendario

CRITICAL findings: 0
HIGH findings: 1
MEDIUM findings: 2
LOW findings: 1

--- HIGH ---

[INCONSISTENCY] Requisito de rendimiento
  spec.md (NFR Performance): "< 200ms"
  plan.md (Constraints): "< 500ms p95"
  Acción: Alinear el umbral de rendimiento
  en ambos documentos.

--- MEDIUM ---

[UNDERSPECIFIED] Criterio sin tarea
  spec.md US-1 AC-4: "validar start < end"
  tasks.md: sin tarea asociada
  Acción: Añadir tarea de validación o
  documentar que se cubrirá en otra tarea.

[DUPLICATION] Contrato de endpoint duplicado
  contracts/api-spec.json: POST /api/events
  plan.md sección "API Design": POST /events
  Acción: Unificar la referencia al contrato.

--- LOW ---

[AMBIGUITY] Formato de fecha no especificado
  plan.md: "DateTime con timezone"
  Acción: Especificar formato ISO 8601 o
  Unix timestamp.

=== END REPORT ===

Plan de remediación opcional

Tras presentar los hallazgos, el agente puede ofrecer un plan de remediación: una propuesta de cambios concretos en los artefactos para resolver cada hallazgo. Este plan es una sugerencia que requiere la aprobación del usuario antes de aplicarse.

¿Deseas que genere un plan de remediación
para los hallazgos detectados? (si/no)

Si el usuario acepta, el agente propone modificaciones específicas para cada hallazgo. Si el usuario rechaza, el informe queda como referencia y el equipo puede resolver los hallazgos manualmente.

Es importante recordar que el propio comando /speckit.analyze nunca modifica archivos. Incluso cuando genera un plan de remediación, este se presenta como texto en la conversación para que el usuario decida si lo aplica o no.

Cuándo ejecutar analyze

El momento natural para ejecutar /speckit.analyze es después de generar las tareas con /speckit.tasks y antes de comenzar la implementación con /speckit.implement. En este punto, los tres artefactos principales ya existen y el análisis puede detectar inconsistencias entre todos ellos.

flowchart LR
    SPECIFY["/speckit.specify"] --> PLAN["/speckit.plan"]
    PLAN --> TASKS["/speckit.tasks"]
    TASKS --> ANALYZE["/speckit.analyze"]
    ANALYZE -->|Sin hallazgos críticos| IMPL["/speckit.implement"]
    ANALYZE -->|Hallazgos críticos| FIX["Corregir artefactos"]
    FIX --> ANALYZE

Sin embargo, el comando puede ejecutarse en cualquier momento posterior a la creación de los tres artefactos. Es especialmente útil en las siguientes situaciones:

Tras modificaciones manuales: si el equipo ha editado manualmente el spec.md, plan.md o tasks.md, ejecutar analyze verifica que las modificaciones no han introducido desalineaciones.

Tras iterar sobre la especificación: si se ha vuelto a ejecutar /speckit.specify o /speckit.clarify y se ha regenerado el plan, el analyze confirma que la nueva versión sigue siendo coherente con las tareas.

Antes de revisiones de equipo: ejecutar analyze antes de una revisión produce un informe que el equipo puede usar como punto de partida para la discusión, centrando la revisión en los hallazgos concretos del informe.

Analyze como red de seguridad

El comando /speckit.analyze funciona como una red de seguridad en el flujo SDD. No es un paso obligatorio para avanzar a la implementación, pero su uso reduce significativamente el riesgo de construir software que no cumple con lo especificado o que contradice la constitución del proyecto.

La validación cruzada que realiza es difícil de replicar manualmente. Un revisor humano que lee el spec.md, el plan.md y el tasks.md de forma secuencial puede detectar inconsistencias evidentes, pero es fácil pasar por alto desalineaciones sutiles: un criterio de aceptación que no tiene tarea asociada, un contrato cuyo formato de respuesta difiere del modelo de datos, o una restricción de rendimiento que aparece con valores diferentes en dos documentos.

El agente, al construir un modelo semántico que conecta los tres artefactos, puede detectar estas desalineaciones de forma exhaustiva. El resultado es un flujo de desarrollo donde la probabilidad de que un requisito se pierda en la traducción de especificación a código se reduce de forma medible.