eai-org/agent-toolkit

Passation

Finalisez un changement terminé pour que ses relecteurs n'aient jamais à reconstruire l'intention à partir du diff. Écrivez pour un relecteur qui ne dispose que du diff — pas de document de planification, pas de session, pas de connaissance que l'un ou l'autre existe.

Résoudre la tâche

L'entrée est une référence partielle quelconque — identifiant de ticket, slug, chemin d'un artefact de planification — ou rien, ce qui signifie la tâche de la session ; dans une session fraîche, déduisez-la du nom de branche et des commits récents. Résolvez-la vers le répertoire de planification de la tâche : son dossier <id>-<slug>/ dans le répertoire de planification du projet, ou ses fichiers plats <id>-<slug>.* dans un répertoire familial partagé. Une correspondance claire → procédez, en indiquant le répertoire et les artefacts trouvés. Inférée, ou plusieurs candidats (-vN, …) → confirmez d'abord. Une référence explicite ne correspondant à rien en local → arrêtez-vous et demandez ; ne devinez jamais.

Rassembler

Lisez ce qui suit, en ignorant ce qui n'existe pas :

1. Artefacts de la tâche — chaque <id>-<slug>*.md dans le répertoire de planification : ticket, exigences, plan, journal des décisions, tours de relecture et de passation antérieurs, et tout autre élément correspondant.
2. Tickets liés — un seul saut : parent (en remontant uniquement au-delà des conteneurs minces), prédécesseurs/successeurs directs, relations explicites, frères du répertoire familial ; n'étendez jamais leurs propres relations. D'abord les .TICKET.md locaux ; ne récupérez du tracker que lorsqu'une relation n'a pas de fichier local et semble importante pour un pourquoi — en cas de doute sur la nécessité de récupérer, demandez.
3. La session, lorsqu'elle a produit le changement : décisions, pivots, contraintes.
4. Le diff par rapport à la cible, plus les sujets des commits.

Chaque source une fois, pas plus profondément que l'artefact ne le nécessite : parcourez l'ensemble du diff, lisez en profondeur uniquement les fichiers que vous nommerez dans le Guide de relecture, et ne reconstruisez jamais l'historique commit par commit — quel commit a changé quoi est le travail du diff, pas le vôtre.

Ensuite, faites correspondre les étapes du plan et les critères d'acceptation avec le diff dans les deux sens — prévu mais absent, présent mais non planifié. Terminé lorsque chaque source est lue ou confirmée absente et que chaque élément planifié est mis en correspondance.

N'inventez jamais de justification

N'indiquez un « pourquoi » que si une source le fournit. Un écart que rien n'explique est demandé à l'auteur une fois ; sans réponse ou impossible à demander, il est livré signalé en mots clairs (« rien n'enregistre pourquoi — à confirmer »), car il peut s'agir d'un écart involontaire plutôt que d'une décision. Le sourçage est votre porte, pas la lecture du relecteur : il décide ce que vous pouvez écrire, et n'apparaît jamais dans le texte. Lorsque vous n'êtes pas sûr, demandez toujours. Ne devinez jamais.

L'artefact

<slug>.HANDOVER.md dans le répertoire de planification ; déjà pris → <slug>.HANDOVER-2.md, -3, … — n'écrasez jamais. Pas de répertoire de planification → présentez le contenu et demandez où l'enregistrer. Son corps est prêt à être collé comme description de PR, et se suffit à lui-même :

• Ne mentionnez que ce que le relecteur peut ouvrir — une URL de tracker, ou un fichier dont vous avez vérifié qu'il est commité sur la branche. Tout le reste — documents de planification, journal des décisions, session, hachages de commit — n'est ni lié ni nommé : écrivez ce qu'il dit (« cela était censé … »), jamais où il le dit.
• Les tickets liés ne sont pas mentionnés sauf si un pourquoi dépend de l'un d'eux (« construit ainsi pour préparer ») — citez alors son URL de tracker.
• Sous un écran, ~400 mots ; les limites ci-dessous sont des plafonds, pas des objectifs.
• Formulation simple, orientée relecteur, jamais le vocabulaire de cette compétence. Avant de rédiger, invoquez réellement use-conversational-language — réciter ses règles de mémoire ne compte pas.

Sections, ignorées uniquement si vraiment vides :

1. Quoi et pourquoi — 2 à 3 lignes.
2. Décisions importantes — au maximum 5 lignes, chacune : ce qui a été choisi ou ce qui s'écarte du plan, son pourquoi ou le drapeau de pourquoi manquant, et où dans le code le voir.
3. Guide de relecture — les quelques fichiers où le jugement compte et pourquoi ; le reste nommé comme mécanique.
4. Lacunes connues — au maximum 3 : insuffisances, hypothèses, questions ouvertes.

Terminé lorsque chaque section est remplie ou délibérément ignorée, rien n'est lu comme vérifié qui ne l'était pas, et rien dans le texte ne pointe vers quelque chose que le relecteur ne peut pas ouvrir.

Limites

• Ne modifiez aucun fichier source ; le document de passation est le seul fichier écrit.
• Ne poussez jamais, n'ouvrez ni ne commentez une PR — la publication est un appel explicite de l'utilisateur.