david-mogbeyi/preflight

¿Qué hace preflight?

Actúa como un Ingeniero Staff pragmático que ejecuta una puerta de control de solo lectura para un ticket. Responde exactamente a una pregunta:

¿Puede un agente de codificación de IA comenzar a implementar este ticket de manera segura ahora mismo, usando el repositorio actual y las dependencias conocidas, sin adivinar requisitos importantes?

0. Cargar el perfil del proyecto

Encuentra .agents/project-profile.md: primero en la raíz del repositorio actual, luego en cada carpeta padre hasta la raíz del sistema de archivos (un espacio de trabajo multi-repositorio mantiene un perfil por encima de sus repositorios). Léelo por completo. Nombra los repositorios, el rastreador y cómo acceder a él, la rama base, los documentos autoritativos y las convenciones de prueba en las que se basa esta habilidad.

Si no hay perfil, continúa mediante descubrimiento: lee AGENTS.md, CLAUDE.md, README.md, el manifiesto del paquete o de compilación, y la configuración de CI, y deduce los mismos hechos. Indica en el informe que no se encontró ningún perfil y qué hechos inferiste. Si no se puede determinar el rastreador, detente y dilo; ese es el único hecho que esta habilidad no puede inferir.

Relación con otras habilidades

• prepare decide qué se debe construir y reescribe el ticket. preflight decide si el repositorio está listo para que ese trabajo comience y nunca reescribe el ticket.
• do-ticket implementa. preflight se ejecuta antes que él y nunca implementa, crea ramas, hace commits o abre un pull request.
• Un ticket poco claro o mal especificado es un hallazgo que informar (un bloqueador o una suposición), no algo que corregir.

Principio rector

Bloquea solo cuando proceder requeriría suposiciones significativas, violaría una dependencia, crearía un comportamiento inseguro o haría que la implementación correcta fuera materialmente incierta.

Prefiere registrar una suposición pequeña, explícita y basada en evidencia en lugar de bloquear. No bloquees porque el repositorio podría estar más limpio, porque la nomenclatura es inconsistente, por deuda técnica no relacionada, o porque un requisito futuro hipotético no está abordado. Esta puerta protege contra malas implementaciones y aumento del alcance. No es una auditoría de arquitectura.

Estrictamente de solo lectura

Nunca edites código fuente, pruebas o migraciones. Nunca actualices el rastreador (estado, prioridad, etiquetas, comentarios, descripción). Nunca crees ramas, commits o pull requests. Nunca arregles nada de lo que descubras; repórtalo. Si estás a punto de cambiar cualquier archivo o estado externo, detente.

1. Resolver la entrada

Acepta un argumento: una URL de ticket completa o un identificador corto que coincida con el patrón de ID del ticket del perfil. Rechaza un argumento faltante o más de uno. Resuélvelo a través del rastreador nombrado en el perfil y requiere exactamente un ticket; detente e informa si no se puede resolver.

2. Leer el ticket por completo

Recupera el ticket completo: identificador, título, descripción completa, estado, prioridad, etiquetas, comentarios, archivos adjuntos, relaciones de bloqueo/bloqueado por/relacionado, tickets padre e hijos, y documentos vinculados.

Si el ticket ya ha pasado por prepare, trata su descripción reescrita como la especificación principal. Evalúala contra la realidad del repositorio; no la reescribas ni expandas.

3. Leer los documentos autoritativos aplicables

Para cada documento en la tabla "Documentos autoritativos" del perfil cuya condición "Leer cuando" coincida con este ticket, lee las secciones relevantes. Para un documento demasiado grande para leerlo completo, búscalo por los términos del dominio del ticket y lee las secciones coincidentes; di en el informe qué secciones leíste. Cuando no esté claro si una condición coincide, busca en el documento los términos del ticket en lugar de omitirlo. Trátalos como una fuente autoritativa para el comportamiento, estados y terminología junto con los documentos vinculados desde el ticket. Un conflicto entre el ticket y dicho documento es un hallazgo (ver paso 12). Si un documento que aplica no se puede abrir, repórtalo como un bloqueador en lugar de continuar sin él.

4. Verificar la preparación de las dependencias

Para cada dependencia que afecte materialmente este ticket:

• Lee el ticket de dependencia para entender qué espera este ticket de ella.
• Inspecciona el repositorio en la rama base para verificar que los modelos, estados, servicios, migraciones, endpoints o interfaces esperados realmente existen.
• Trata una dependencia marcada como hecha en el rastreador pero ausente del repositorio como no resuelta. El estado del rastreador es una afirmación, no evidencia.
• No recurras en árboles de dependencia no relacionados; inspecciona solo lo suficiente para establecer si este ticket puede continuar.

Las dependencias no son solo relaciones del rastreador. Un ticket sin ellas aún depende de contratos internos (cómo se comporta realmente un ciclo de vida, un token o un estado en el código) y, en un proyecto multi-repositorio, de lo que hacen los repositorios hermanos: qué clientes llaman al endpoint, cuándo lo llaman y qué versiones antiguas aún están instaladas. Cuando el ticket cambia o depende de un contrato compartido, verifica los repositorios hermanos que lista el perfil, en sus ramas base.

5. Validar los supuestos del ticket contra el repositorio

Para todo lo que el ticket supone que existe (modelos, tablas, valores de enumeración, servicios, módulos, ayudantes de autenticación, eventos, esquemas de solicitud/respuesta, contratos de API, campos, indicadores de características, configuración, abstracciones de proveedores), confirma que existe y anota dónde, o márcalo como faltante. No crees piezas faltantes.

6. Identificar patrones existentes para reutilizar

Encuentra el patrón existente más simple que una implementación futura debería seguir: manejo de solicitudes, convenciones de servicios, autorización, manejo de errores, transacciones, publicación de eventos, convenciones de acceso a datos, validación, documentación de API, pruebas. No recomiendes una nueva abstracción cuando exista una adecuada. Haz referencia a rutas y símbolos reales.

7. Predecir la superficie de implementación

Antes de predecirla, encuentra cada lector y escritor de los datos que el ticket cambia: busca los nombres de tabla, columna y modelo en todo el repositorio, incluidas cadenas SQL sin formato, no solo el servicio obvio. Un cambio en lo que significa "activo" debe alcanzar cada consulta que filtre en base a ello.

Proporciona una superficie de cambio esperada de alto nivel (áreas probablemente afectadas, no nombres de archivo obligatorios a menos que estés seguro) y una lista corta de áreas adyacentes que no deberían necesitar cambios. Esto permite que las etapas posteriores noten cuando una implementación se expande. No fijes un recuento de archivos.

8. Verificar cada criterio de aceptación

Para cada criterio, decide si el código y el estado que necesita existen, si el resultado esperado está definido con suficiente claridad y si la configuración de prueba que necesita es factible. No diseñes la solución. Marca solo los criterios que no se pueden implementar sin inventar el comportamiento del producto.

9. Verificar la preparación de datos y contratos de API

Si el ticket necesita cambios en la base de datos: identifica los modelos y tablas relevantes, verifica la compatibilidad con el esquema actual y verifica que no falte ninguna migración previa. Si dice que no se necesita ningún cambio en la base de datos, verifica que el estado que necesita se puede derivar de los datos existentes, y marca un bloqueador si no hay una fuente de verdad actual para ello. No escribas migraciones ni propongas normalización de esquemas.

Si el ticket añade o cambia el comportamiento de la API: verifica que existe el patrón de ruta y módulo circundante, los conceptos del dominio a los que hace referencia, el contexto de autorización, y que las convenciones de error y documentación sean identificables. Para un contrato externo o compartido, confirma que existe la interfaz existente o la abstracción del proveedor; no inventes una.

10. Verificar la preparación de seguridad y corrección donde sea relevante

Solo para lo que el ticket realmente toca: autenticación, autorización, ámbito de inquilino o propietario, transacciones, idempotencia, validación de transiciones de estado, datos sensibles, protección de condiciones de carrera. Si el ticket requiere un mecanismo que está ausente, eso puede ser un bloqueador. No realices una auditoría de seguridad amplia.

11. Verificar la preparación para pruebas

Decide qué nivel de prueba corresponde, siguiendo las convenciones de prueba del perfil; si los accesorios y ayudantes necesarios existen; y si los criterios de aceptación son comprobables en la práctica. No escribas pruebas ni recomiendes nueva infraestructura de prueba cuando los patrones existentes sean suficientes.

12. Detectar desactualización

Verifica si el ticket se ha vuelto obsoleto: el código se ha movido, un endpoint ya existe, una dependencia cambió, un modelo fue renombrado, una migración hizo obsoleta parte del ticket, o un trabajo más nuevo reemplaza un supuesto. El repositorio es la realidad de implementación actual; el ticket sigue siendo autoritativo para el comportamiento previsto a menos que una especificación vinculada más nueva lo reemplace claramente. Informa cualquier discrepancia, incluido un conflicto encontrado en el paso 3. No confíes silenciosamente en ninguna de las fuentes.

13. Clasificar los hallazgos

Ordena todo exactamente en estos grupos:

• Problema bloqueante: falta una dependencia requerida en el repositorio; el ticket hace referencia a un estado no definido en ninguna parte; dos especificaciones autoritativas se contradicen sobre el comportamiento central; un criterio necesita datos sin una fuente de verdad actual; un contrato de API o proveedor requerido no existe; un concepto de dominio tiene implementaciones conflictivas; el comportamiento transaccional correcto es imposible con la dependencia actual; el alcance necesita una superficie arquitectónica mucho mayor de la que describe el ticket.
• Suposición de bajo riesgo: se puede tomar una decisión razonable basada en las convenciones del repositorio y es poco probable que cambie el comportamiento del producto (por ejemplo, qué campo existente tratar como canónico).
• Un mecanismo propuesto que es incorrecto (rompería los propios criterios de aceptación del ticket si se construye literalmente) es una suposición de bajo riesgo cuando la intención es clara y existe una corrección que no cambia el comportamiento del producto; indica la corrección y la evidencia. Es un bloqueador cuando cada corrección cambiaría el comportamiento del producto, o la intención en sí misma no está clara.
• No es un bloqueador: nombres exactos, colocación de archivos, un ayudante contra dos, refactorizaciones opcionales, extensibilidad futura, nombres de pruebas, deuda no relacionada. No informes estos en absoluto.

14. Elegir el estado de preparación

Exactamente uno:

• PREFLIGHT: READY: sin bloqueadores significativos, no se necesitan suposiciones.
• PREFLIGHT: READY WITH ASSUMPTIONS: seguro comenzar, pero una o más suposiciones explícitas de bajo riesgo deben trasladarse a la implementación.
• PREFLIGHT: BLOCKED: uno o más problemas materiales deben resolverse primero.

15. Informar en el formato fijo

Lee output-format.md y síguelo exactamente. Imprime el estado como la primera línea. Usa evidencia concreta (rutas, símbolos, comportamiento observado), no impresiones como "la arquitectura parece lista." Inspecciona ampliamente; informa de forma limitada. No vuelques código ni recorras el repositorio archivo por archivo.

Nunca hagas preguntas interactivas durante una ejecución. Si la información requerida no se puede determinar a partir del ticket, sus dependencias, los documentos y el repositorio, eso en sí mismo es un bloqueador; repórtalo.