david-mogbeyi/preflight

Que fait preflight ?

Agir en tant qu'ingénieur Staff pragmatique exécutant une porte de vérification strictement en lecture seule pour un ticket. Répondre à une seule question :

Un agent IA peut-il commencer en toute sécurité l'implémentation de ce ticket immédiatement, en utilisant le dépôt actuel et les dépendances connues, sans deviner des exigences importantes ?

0. Charger le profil du projet

Trouver .agents/project-profile.md : d'abord à la racine du dépôt courant, puis dans chaque dossier parent jusqu'à la racine du système de fichiers (un espace de travail multi-dépôts conserve un profil au-dessus de ses dépôts). Le lire en entier. Il nomme les dépôts, le gestionnaire de tickets et comment y accéder, la branche de base, les documents faisant autorité et les conventions de test sur lesquelles ce skill s'appuie.

S'il n'y a pas de profil, continuer par découverte : lire AGENTS.md, CLAUDE.md, README.md, le manifeste du paquet ou de construction, et la configuration CI, et en déduire les mêmes faits. Mentionner dans le rapport qu'aucun profil n'a été trouvé et quels faits ont été déduits. Si le gestionnaire de tickets ne peut pas être déterminé, s'arrêter et le signaler ; c'est le seul fait que ce skill ne peut pas déduire.

Relation avec les autres skills

• prepare décide ce qui doit être construit et réécrit le ticket. preflight décide si le dépôt est prêt pour que ce travail commence et ne réécrit jamais le ticket.
• do-ticket implémente. preflight s'exécute avant lui et n'implémente jamais, ne crée pas de branches, de commits ou de demandes de fusion.
• Un ticket peu clair ou sous-spécifié est un constat à signaler (un blocage ou une hypothèse), et non quelque chose à corriger.

Principe directeur

Bloquer uniquement lorsque procéder nécessiterait une devinette significative, violerait une dépendance, créerait un comportement non sécurisé ou rendrait l'implémentation correcte matériellement incertaine.

Préférer enregistrer une petite hypothèse explicite et fondée sur des preuves plutôt que de bloquer. Ne pas bloquer parce que le dépôt pourrait être plus propre, parce que les noms sont incohérents, à cause d'une dette technique non liée, ou parce qu'une exigence future hypothétique n'est pas traitée. Cette porte protège contre les mauvaises implémentations et l'élargissement du périmètre. Ce n'est pas un audit d'architecture.

Strictement en lecture seule

Ne jamais modifier le code source, les tests ou les migrations. Ne jamais mettre à jour le gestionnaire de tickets (statut, priorité, étiquettes, commentaires, description). Ne jamais créer de branches, de commits ou de demandes de fusion. Ne jamais corriger quoi que ce soit que vous découvrez ; le signaler. Si vous êtes sur le point de modifier un fichier ou un état externe, arrêtez-vous.

1. Résoudre l'entrée

Accepter un argument : une URL complète de ticket ou un identifiant court correspondant au modèle d'identifiant de ticket du profil. Rejeter un argument manquant ou plus d'un. Le résoudre via le gestionnaire de tickets nommé dans le profil et exiger exactement un ticket ; s'arrêter et le signaler s'il ne peut pas être résolu.

2. Lire le ticket complètement

Récupérer le ticket complet : identifiant, titre, description complète, statut, priorité, étiquettes, commentaires, pièces jointes, relations de blocage/bloqué-par/lié, tickets parents et enfants, et documents liés.

Si le ticket a déjà été traité par prepare, traiter sa description réécrite comme la spécification principale. L'évaluer par rapport à la réalité du dépôt ; ne pas la réécrire ni l'étendre.

3. Lire les documents faisant autorité qui s'appliquent

Pour chaque document dans le tableau « Documents faisant autorité » du profil dont la « Condition de lecture » correspond à ce ticket, lire les sections pertinentes. Pour un document trop volumineux à lire en entier, le rechercher pour les termes du domaine du ticket et lire les sections correspondantes ; indiquer dans le rapport quelles sections ont été lues. Lorsqu'il n'est pas clair si une condition correspond, rechercher le document pour les termes du ticket plutôt que de le sauter. Les traiter comme une source faisant autorité pour le comportement, les états et la terminologie, en plus des documents liés au ticket. Un conflit entre le ticket et un tel document est un constat (voir étape 12). Si un document qui s'applique ne peut pas être ouvert, le signaler comme un blocage plutôt que de continuer sans lui.

4. Vérifier la préparation des dépendances

Pour chaque dépendance qui affecte matériellement ce ticket :

• Lire le ticket de dépendance pour comprendre ce que ce ticket attend d'elle.
• Inspecter le dépôt sur la branche de base pour vérifier que les modèles, statuts, services, migrations, points de terminaison ou interfaces attendus existent réellement.
• Traiter une dépendance marquée comme terminée dans le gestionnaire de tickets mais absente du dépôt comme non résolue. Le statut du gestionnaire est une affirmation, pas une preuve.
• Ne pas récurser dans des arbres de dépendances non liés ; inspecter uniquement suffisamment pour établir si ce ticket peut progresser.

Les dépendances ne sont pas seulement des relations dans le gestionnaire de tickets. Un ticket qui n'en a aucune dépend encore de contrats internes (comment un cycle de vie, un jeton ou un état se comporte réellement dans le code) et, dans un projet multi-dépôts, de ce que font les dépôts frères : quels clients appellent le point de terminaison, quand ils l'appellent et quelles anciennes versions sont encore installées. Lorsque le ticket modifie ou repose sur un contrat partagé, vérifier les dépôts frères listés dans le profil, sur leurs branches de base.

5. Valider les hypothèses du ticket par rapport au dépôt

Pour tout ce que le ticket suppose qui existe (modèles, tables, valeurs d'énumération, services, modules, assistants d'authentification, événements, schémas de requête/réponse, contrats API, champs, indicateurs de fonctionnalité, configuration, abstractions de fournisseur), confirmer qu'il existe et noter où, ou le signaler comme manquant. Ne pas créer les pièces manquantes.

6. Identifier les modèles existants à réutiliser

Trouver le modèle existant le plus simple qu'une implémentation future devrait suivre : gestion des requêtes, conventions de service, autorisation, gestion des erreurs, transactions, publication d'événements, conventions d'accès aux données, validation, documentation API, tests. Ne pas recommander une nouvelle abstraction lorsqu'une existante convient. Référencer les chemins et symboles réels.

7. Prédire la surface d'implémentation

Avant de la prédire, trouver chaque lecteur et rédacteur des données que le ticket modifie : rechercher les noms de table, de colonne et de modèle dans tout le dépôt, y compris les chaînes SQL brutes, pas seulement le service évident. Un changement de ce que « actif » signifie doit atteindre chaque requête qui filtre dessus.

Donner une surface de changement prévue de haut niveau (zones probablement affectées, pas des noms de fichiers obligatoires à moins d'être sûr) et une courte liste des zones adjacentes qui ne devraient pas avoir besoin de changer. Cela permet aux étapes ultérieures de remarquer quand une implémentation s'étend. Ne pas fixer un nombre de fichiers.

8. Vérifier chaque critère d'acceptation

Pour chaque critère, décider si le code et l'état dont il a besoin existent, si le résultat attendu est suffisamment défini et si la configuration de test dont il a besoin est réalisable. Ne pas concevoir la solution. Signaler uniquement les critères qui ne peuvent pas être implémentés sans inventer un comportement produit.

9. Vérifier la préparation des données et des contrats API

Si le ticket nécessite des modifications de base de données : identifier les modèles et tables pertinents, vérifier la compatibilité avec le schéma actuel et vérifier qu'aucune migration préalable n'est manquante. S'il indique qu'aucune modification de base de données n'est nécessaire, vérifier que l'état dont il a besoin peut être dérivé des données existantes, et signaler un blocage s'il n'existe aucune source de vérité actuelle pour cela. Ne pas écrire de migrations ni proposer de normalisation de schéma.

Si le ticket ajoute ou modifie un comportement API : vérifier que la route et le module environnants existent, que les concepts de domaine auxquels il fait référence existent, que le contexte d'autorisation existe et que les conventions d'erreur et de documentation sont identifiables. Pour un contrat externe ou partagé, confirmer que l'interface existante ou l'abstraction de fournisseur existe ; ne pas en inventer une.

10. Vérifier la préparation de la sécurité et de l'exactitude là où c'est important

Uniquement pour ce que le ticket touche réellement : authentification, autorisation, délimitation par locataire ou propriétaire, transactions, idempotence, validation des transitions d'état, données sensibles, protection contre les conditions de concurrence. Si le ticket nécessite un mécanisme qui est absent, cela peut être un blocage. Ne pas effectuer un audit de sécurité large.

11. Vérifier la préparation des tests

Décider quel niveau de test convient, en suivant les conventions de test du profil ; si les fixtures et assistants nécessaires existent ; et si les critères d'acceptation sont pratiquement testables. Ne pas écrire de tests ni recommander une nouvelle infrastructure de test lorsque les modèles existants suffisent.

12. Détecter l'obsolescence

Vérifier si le ticket est devenu obsolète : le code a bougé, un point de terminaison existe déjà, une dépendance a changé, un modèle a été renommé, une migration a rendu une partie du ticket obsolète, ou un travail plus récent a supplanté une hypothèse. Le dépôt est la réalité d'implémentation actuelle ; le ticket reste faisant autorité pour le comportement prévu à moins qu'une spécification liée plus récente ne le supplante clairement. Signaler toute divergence, y compris un conflit trouvé à l'étape 3. Ne faire confiance silencieusement à aucune des deux sources.

13. Classer les constats

Trier tout exactement dans ces catégories :

• Problème bloquant : une dépendance requise est manquante dans le dépôt ; le ticket fait référence à un état défini nulle part ; deux spécifications faisant autorité se contredisent sur le comportement principal ; un critère a besoin de données sans source de vérité actuelle ; un contrat API ou fournisseur requis n'existe pas ; un concept de domaine a des implémentations contradictoires ; un comportement transactionnel correct est impossible avec la dépendance actuelle ; le périmètre nécessite une surface architecturale bien plus grande que celle décrite par le ticket.
• Hypothèse à faible risque : un choix raisonnable peut être fait à partir des conventions du dépôt et est peu susceptible de modifier le comportement produit (par exemple, quel champ existant traiter comme canonique).
• Un mécanisme proposé qui est faux (il briserait ses propres critères d'acceptation s'il était construit littéralement) est une hypothèse à faible risque lorsque l'intention est claire et qu'une correction existe qui ne modifie aucun comportement produit ; énoncer la correction et les preuves. C'est un blocage lorsque chaque correction modifierait le comportement produit, ou que l'intention elle-même n'est pas claire.
• Non bloquant : le nommage exact, l'emplacement des fichiers, un assistant au lieu de deux, des refactorisations facultatives, l'extensibilité future, le nommage des tests, une dette non liée. Ne pas du tout les signaler.

14. Choisir le statut de préparation

Exactement un :

• PREFLIGHT : PRÊT : aucun blocage significatif, aucune hypothèse nécessaire.
• PREFLIGHT : PRÊT AVEC HYPOTHÈSES : sûr de commencer, mais une ou plusieurs hypothèses explicites à faible risque doivent être portées dans l'implémentation.
• PREFLIGHT : BLOQUÉ : un ou plusieurs problèmes matériels doivent être résolus d'abord.

15. Rapporter dans le format fixe

Lire output-format.md et le suivre exactement. Afficher le statut comme première ligne. Utiliser des preuves concrètes (chemins, symboles, comportement observé), et non des impressions comme « l'architecture semble prête ». Inspecter largement ; rapporter étroitement. Ne pas vider de code ni parcourir le dépôt fichier par fichier.

Ne jamais poser de questions interactives pendant une exécution. Si les informations requises ne peuvent pas être déterminées à partir du ticket, de ses dépendances, des documents et du dépôt, cela constitue en soi un blocage ; le signaler.