Pre-Implementation Gates

Qué son los Pre-Implementation Gates

Los Pre-Implementation Gates son puntos de validación obligatorios que se aplican durante la fase de planificación. Su propósito es verificar que el plan técnico generado por /speckit.plan cumple con los principios establecidos en la constitución del proyecto antes de que el equipo avance a la fase de tareas e implementación.

Sin estos checkpoints, el plan podría contener decisiones que contradicen los principios del proyecto. Un equipo que ha establecido el principio de Simplicity en su constitución podría recibir un plan que propone una arquitectura de microservicios para una funcionalidad que se resuelve con un monolito. Los gates detectan esta desalineación y la hacen visible.

Los Pre-Implementation Gates actúan como un filtro de calidad entre el plan técnico y la implementación. Su objetivo no es bloquear el avance, sino garantizar que las decisiones técnicas están alineadas con la filosofía del proyecto.

El concepto se inspira en los quality gates de la ingeniería de software tradicional, pero adaptado al contexto de SDD. En lugar de revisiones manuales por un comité, los gates son validaciones que el agente IA ejecuta automáticamente al generar el plan.

Constitution Check: el gate principal

El gate más importante del proceso de planificación es el Constitution Check. Este checkpoint verifica que las decisiones técnicas del plan respetan cada uno de los principios definidos en la constitución del proyecto.

El Constitution Check se ejecuta en dos momentos durante la generación del plan:

• Antes de Phase 0 (investigación): se valida que la dirección técnica prevista no contradice ningún principio constitucional. Si se detecta una violación, el agente se detiene y solicita orientación antes de invertir tiempo en investigación.

• Después de Phase 1 (diseño): se revisa el plan completo, incluyendo el modelo de datos, los contratos y la estructura del proyecto, para confirmar que las decisiones tomadas durante el diseño siguen cumpliendo la constitución.

flowchart LR
    CONST["Constitution"] --> CHECK1["Constitution Check<br>Pre-Phase 0"]
    CHECK1 -->|Pasa| PH0["Phase 0<br>Investigación"]
    PH0 --> PH1["Phase 1<br>Diseño"]
    PH1 --> CHECK2["Constitution Check<br>Post-Phase 1"]
    CHECK2 -->|Pasa| OK["Plan aprobado"]
    CHECK1 -->|Falla| FIX1["Ajustar dirección"]
    CHECK2 -->|Falla| FIX2["Justificar o corregir"]

El agente extrae las reglas de validación directamente de la constitución. Los principios que contienen palabras clave como MUST, MUST NOT, REQUIRED o NON-NEGOTIABLE se tratan como restricciones duras que no pueden violarse sin justificación explícita.

Checkpoint de Simplicity

El principio de Simplicity establece que el código generado debe resolver los requisitos actuales sin anticipar necesidades futuras. Este principio se traduce en un checkpoint que analiza el plan buscando señales de sobreingeniería.

El agente verifica aspectos concretos del plan:

Número de componentes: si el plan propone más módulos, servicios o capas de los estrictamente necesarios para cumplir los requisitos de la especificación, el checkpoint lo señala. Una feature con tres user stories no debería producir un plan con diez servicios separados.

Patrones de diseño innecesarios: el checkpoint detecta cuando el plan propone patrones arquitectónicos que no están justificados por los requisitos. Un patrón Observer para un sistema con un único tipo de evento, o un patrón Strategy para una lógica que solo tiene una variante, son señales de complejidad innecesaria.

Dependencias excesivas: si el plan introduce múltiples dependencias externas para resolver algo que podría implementarse con las herramientas que ya tiene el proyecto, el checkpoint lo cuestiona.

Un plan que pasa el checkpoint de Simplicity no es necesariamente simple. Es un plan donde cada decisión de complejidad está justificada por un requisito concreto de la especificación.

Cuando el checkpoint detecta una posible violación del principio de Simplicity, no bloquea automáticamente el plan. En su lugar, registra la violación en la tabla de Complexity Tracking y solicita una justificación.

Checkpoint de Anti-Abstraction

El principio de Anti-Abstraction impide la creación de abstracciones prematuras. En el contexto del plan técnico, este checkpoint busca interfaces, clases abstractas o capas de indirección que solo tienen una implementación concreta.

Situaciones que el checkpoint de Anti-Abstraction señala:

Interfaces con implementación única: si el plan define un EventRepository como interfaz abstracta pero solo existe un PostgresEventRepository, la abstracción no aporta valor. El checkpoint sugiere usar directamente la implementación concreta hasta que exista una segunda variante que justifique la abstracción.

Capas de servicio innecesarias: un EventService que simplemente delega todas las llamadas a un repositorio sin añadir lógica de negocio es una capa de indirección sin valor. El checkpoint identifica esta situación cuando los métodos del servicio son pass-through directos.

Factorías para un solo tipo: un EventFactory que solo crea instancias de CalendarEvent no justifica su existencia. La creación directa del objeto es más simple y más clara.

## Complexity Tracking

| Violación              | Por qué es necesaria          | Alternativa rechazada          |
|------------------------|-------------------------------|--------------------------------|
| EventRepository        | Se planean 3 backends         | Acceso directo a PostgreSQL    |
| (interfaz)             | de storage en la hoja         | no permite migrar a SQLite     |
|                        | de ruta del producto          | para testing local             |

La tabla de Complexity Tracking es el mecanismo que permite documentar excepciones conscientes al principio de Anti-Abstraction. No todas las abstracciones son malas, pero cada una debe tener una razón explícita que vaya más allá de "por si acaso" o "por buenas prácticas".

Checkpoint de Integration-First

El principio de Integration-First establece que las conexiones a sistemas externos (bases de datos, APIs de terceros, servicios de autenticación, colas de mensajes) deben configurarse y verificarse antes de construir la lógica de negocio.

Este checkpoint valida que el plan incluya:

Verificación temprana de integraciones: si la feature depende de una API externa (por ejemplo, un servicio de email para enviar invitaciones), el plan debe contemplar la validación de esa conexión como uno de los primeros pasos de la implementación, no como el último.

Contratos de integración definidos: para cada sistema externo con el que la feature interactúa, debe existir un contrato (en contracts/) que documente el formato de los datos intercambiados, los endpoints utilizados y el comportamiento esperado en caso de error.

Estrategia de fallback documentada: si una integración externa no está disponible (el servicio de email cae, la API de terceros tiene latencia alta), el plan debe documentar cómo se comporta el sistema. Esta información se deriva de los edge cases del spec.md.

flowchart TB
    subgraph Orden["Orden de implementación"]
        INT["1. Configurar integraciones<br>DB, APIs externas, auth"]
        VERIFY["2. Verificar conexiones<br>Health checks, contracts"]
        LOGIC["3. Lógica de negocio<br>Sobre integraciones verificadas"]
        UI["4. Interfaz de usuario<br>Sobre lógica funcional"]
    end
    INT --> VERIFY --> LOGIC --> UI

El checkpoint de Integration-First previene un error frecuente en proyectos con agentes IA: construir toda la lógica de negocio sobre stubs y descubrir al final que la integración real funciona de forma diferente a lo esperado.

Complexity Tracking en la práctica

La tabla de Complexity Tracking es la sección del plan.md donde se documentan todas las violaciones de los checkpoints constitucionales que el equipo ha decidido aceptar. Esta tabla tiene tres columnas:

• Violación: qué principio constitucional se está violando y en qué parte del plan.
• Por qué es necesaria: la justificación técnica o de negocio que respalda la decisión.
• Alternativa rechazada: qué solución más simple se consideró y por qué no es suficiente.

| Violación                        | Por qué es necesaria             | Alternativa rechazada                 |
|----------------------------------|----------------------------------|---------------------------------------|
| 4 modulos en lugar de 3          | Auth requiere modulo dedicado    | Incluir auth en el modulo API hace    |
|                                  | por requisitos de seguridad      | el modulo demasiado grande            |
| Repository pattern               | Necesitamos SQLite en tests      | Mocks directos no cubren queries      |
|                                  | y PostgreSQL en produccion       | complejas con joins                   |

La tabla comienza vacía en la mayoría de los planes. Solo se rellena cuando el Constitution Check detecta una violación que el equipo considera justificada. Un plan con una tabla de Complexity Tracking vacía indica que todas las decisiones técnicas se alinean con la constitución sin excepciones.

Un plan con múltiples entradas en la tabla de Complexity Tracking no es necesariamente malo. Lo que importa es que cada violación tiene una justificación documentada y que se ha descartado explícitamente una alternativa más simple. Este registro de decisiones facilita las revisiones futuras y evita que se repitan debates sobre decisiones que ya se tomaron.

Gates como herramienta de equipo

Más allá de su función técnica, los Pre-Implementation Gates sirven como herramienta de comunicación en equipos de desarrollo. Cuando un plan pasa todos los checkpoints sin violaciones, el equipo tiene la confianza de que las decisiones técnicas son coherentes con los principios del proyecto.

Cuando un plan tiene violaciones documentadas en el Complexity Tracking, estas se convierten en puntos de discusión para la revisión del plan. En lugar de debatir sobre opiniones subjetivas ("creo que esto es demasiado complejo"), la conversación se centra en las justificaciones documentadas ("el plan viola Anti-Abstraction porque necesitamos dos backends de storage, y aquí está la justificación").

Los gates también proporcionan métricas de evolución del proyecto. Si con el tiempo la tabla de Complexity Tracking crece en cada plan, puede indicar que la constitución necesita una enmienda para reflejar la realidad del proyecto. Si la tabla se mantiene vacía de forma consistente, indica que la constitución y las decisiones técnicas están bien alineadas.

Este feedback bidireccional entre los gates y la constitución es un ejemplo del principio de refinamiento continuo que fundamenta la metodología SDD. Los artefactos no son estáticos: se adaptan y evolucionan con el proyecto.