Implémenter la tâche

Que fait Implémenter la tâche ?

Livrer un ticket de 1 point sous forme de PR pour révision, contenant exactement ce que le ticket demande et rien de plus.

Entrée

$ARGUMENTS

• Ticket, obligatoire : une clé de tracker (par ex. ENG-123) ou un ID local (par ex. T-04). Si absent, lister les tickets prêts (statut open, dépendances fusionnées), d'abord ceux du chemin critique, et demander lequel prendre. En mode non supervisé, signaler blocked à la place.
• --tasks <fichier> : le fichier de tâches local. S'il n'est pas fourni, chercher le fichier *.tasks.md contenant le ticket dans le dossier RFC local, ignoré par git, du projet (par ex. .rfcs/), puis docs/rfcs/.
• --base <branche> : la branche de départ et cible de la PR. Par défaut, main. Une base autre que main signifie que la PR est empilée sur la PR non fusionnée d'un autre ticket.
• --branch <nom> : le nom de branche à utiliser. Sinon, suivre la règle de nommage de l'étape 1.
• --feedback <pr> : ne pas implémenter ; traiter les retours de révision sur une PR existante (voir la dernière section).
• --unattended : vous avez été démarré par un orchestrateur et personne ne peut répondre aux questions. Ne jamais demander ; lorsque vous auriez besoin de demander, arrêtez-vous et expliquez dans le rapport. Effectuez votre travail dans votre propre worktree.

Où se trouvent le ticket et les fichiers locaux

• Tracker en premier. Si le ticket a une clé de tracker (comme argument, ou dans le champ Tracker: du fichier de tâches), récupérez-le via l'outil de tracker connecté (Linear, Jira, GitHub Issues, …). Une fois publié, le tracker est la source de vérité pour le contenu du ticket ; s'il est annulé ou terminé là-bas, arrêtez-vous et signalez-le.
• Sinon fichier de tâches local, et pour les champs que le ticket tracker ne possède pas (fichiers, hors périmètre). Les RFC et fichiers de tâches sont des documents locaux et non suivis du développeur, ils n'existent donc que dans le dossier principal du projet, pas dans un worktree. Si vous êtes dans un worktree, trouvez le dossier principal avec git worktree list (la première entrée) et lisez les fichiers là-bas par chemin absolu. Traitez le dossier principal comme lecture seule : ne jamais éditer, checkout ou exécuter des commandes git dedans.
• Ne jamais commiter de RFC, notes ou fichiers de tâches. Stager les fichiers par chemin explicite, pas avec git add -A.

1. Choisir le ticket

• Lire le ticket (voir ci-dessus), y compris ses critères d'acceptation et dépendances. Si son type est spike, arrêtez-vous : les spikes produisent une décision, pas une PR ; dirigez vers /spike-task (non supervisé : signalez blocked).
• Une dépendance est satisfaite lorsque sa PR est fusionnée dans main (vérifier l'état de la PR avec gh, ou le statut de dépendance pr-merged/done), ou lorsque la branche de base est la propre branche de cette dépendance (empilement). Une dépendance de spike est satisfaite uniquement lorsqu'elle est done, ce qui signifie que sa décision a été approuvée et le backlog affiné. Si une dépendance n'est pas satisfaite, arrêtez-vous et dites laquelle.
• Assurez-vous que l'arbre de travail est propre, faites un fetch, et créez la branche à partir du dernier origin/<base>.
• Nom de branche (sauf si --branch a été fourni) : <nom_utilisateur>/<slug_projet>/<branche_tache>.
  • nom_utilisateur : le préfixe des branches existantes de l'utilisateur si elles suivent ce modèle, sinon son login GitHub (gh api user --jq .login).
  • slug_projet : depuis l'en-tête Project slug: du fichier de tâches, ou le nom de la RFC en kebab case.
  • branche_tache : la clé du tracker plus un court slug, par ex. eng-123-add-v2-flag (la clé permet aux intégrations du tracker de lier la PR), ou t-04-add-v2-flag si non publié.
• Si vous travaillez directement avec l'utilisateur (pas en mode non supervisé), mettez le statut du ticket à in progress dans le fichier de tâches, et dans le tracker si son intégration GitHub ne le fait pas.

2. Charger uniquement ce dont le ticket a besoin

Lisez le ticket, la section RFC sur laquelle il s'appuie, et les fichiers qu'il nomme. Puis tracez le flux réel : appelants, aides existants, et les tests à côté du code que vous allez modifier. Lisez assez pour comprendre le problème complètement, mais ne chargez pas toute la RFC ou l'historique de session ; le ticket a été écrit pour être autonome. Si ce n'est pas le cas, c'est un écart à signaler, pas à deviner.

3. Écrire les tests en premier

Convertissez chaque critère d'acceptation en un test, en utilisant le framework, le style et l'emplacement de test existants du dépôt. Exécutez-les et confirmez qu'ils échouent pour la bonne raison. Un test ciblé par critère suffit : pas de nouveaux utilitaires de test, fixtures ou aides à moins qu'un modèle existant ne les nécessite. Les tickets purement mécaniques (par ex. ajouter un flag) peuvent ne nécessiter aucun nouveau test si le critère est vérifié par des tests existants ou le type checker ; dites-le dans la PR.

4. Implémenter le plus petit changement complet

« Complet » signifie que chaque critère d'acceptation passe. « Le plus petit » signifie rien au-delà. Cela suit l'approche ponytail ; si un skill ponytail est installé, chargez-le maintenant à son niveau par défaut et laissez-le gouverner cette étape.

Sinon, prenez la première option qui fonctionne :

1. Le besoin est-il déjà satisfait ? Si le code existant remplit déjà les critères, arrêtez-vous et proposez de fermer le ticket.
2. Réutilisez ce que la base de code possède déjà : aides, types, modèles.
3. Utilisez la bibliothèque standard, puis les fonctionnalités natives de la plateforme (contraintes de base de données, entrées HTML intégrées, CSS avant JS), puis les dépendances déjà installées.
4. Ce n'est qu'ensuite, écrivez du nouveau code, aussi peu que nécessaire.

Pendant l'écriture :

• Pas de structure spéculative. Pas d'interfaces avec une seule implémentation, pas de fabriques pour un seul produit, pas de configuration pour des valeurs qui ne changent jamais, pas d'échafaudage « pour plus tard ». Préférez modifier un fichier existant plutôt que d'en créer un nouveau.
• Correspondre au code environnant : nommage, gestion des erreurs, structure. Le diff doit ressembler à ce que la base de code aurait écrit.
• Commentaires seulement là où le code ne peut pas parler. Ne racontez pas ce que le code fait, ne reformulez pas le ticket, ne laissez pas de code commenté ou de sortie de débogage. Le seul commentaire qui vaut la peine d'être ajouté est une simplification délibérée : nommez la limite et quand la mettre à jour, pour que personne ne la « corrige » par accident.
• Corrigez les bugs à la racine. Vérifiez chaque appelant avant de modifier une fonction partagée.
• Ne minimisez jamais la sécurité. Validation d'entrée aux frontières de confiance, gestion des erreurs empêchant la perte de données, bases de sécurité et d'accessibilité toujours correctement effectuées, même si le ticket ne les énonce pas.

5. Garder le périmètre

Si le ticket s'avère plus gros que 1 point (plus d'environ un jour, un second besoin apparaît, ou un critère ne peut être satisfait sans toucher à des zones non liées), arrêtez-vous. Ne commitez rien au-delà de ce qui est propre, expliquez ce que vous avez trouvé, et proposez une scission sous forme de nouveaux tickets pour approbation : écrivez-les dans le fichier de tâches lorsque vous travaillez avec l'utilisateur, ou dans le rapport en mode non supervisé. Les problèmes non liés que vous remarquez vont dans les notes de la PR, pas dans le diff. N'affaiblissez ni ne réinterprétez jamais un critère d'acceptation pour le faire passer.

6. Vérifier et ouvrir la PR

1. Exécutez les tests, le linter et le type checker de la manière dont le dépôt le fait. Si le changement a un comportement d'exécution et que vous pouvez exécuter /verify, faites-le ; sinon, exercez le comportement avec les propres commandes d'exécution ou de vérification du projet.
2. Relisez vous-même le diff complet : chaque ligne modifiée doit correspondre à un critère d'acceptation. Supprimez le formatage non lié, les renommages et les fichiers indésirables, et assurez-vous qu'aucun fichier RFC ou tâche local ne s'est glissé.
3. Commitez en suivant le style de commit du dépôt, poussez, et ouvrez la PR prête pour révision (pas en brouillon, afin que l'automatisation de révision s'exécute, sauf si l'utilisateur a demandé un brouillon) vers la branche de base, en utilisant templates/pr.md. Mettez la clé du tracker dans le titre et liez le ticket tracker dans la description. Si la base n'est pas main, dites sur quelle PR elle est empilée et que celle-ci fusionne en premier. Si vous ne pouvez pas ouvrir de PR depuis ici, poussez la branche et incluez le texte de la PR dans votre réponse.
4. Si vous travaillez directement avec l'utilisateur, mettez le statut du ticket à pr-open (ou pr-draft) et remplissez Branche / PR : dans le fichier de tâches, et déplacez le ticket tracker vers son état de révision si son intégration GitHub ne le fait pas. En mode non supervisé, laissez les statuts à l'orchestrateur.
5. Terminez par le rapport ci-dessous. En présence d'un utilisateur, une version de deux ou trois lignes suffit.

Traiter les retours de PR (--feedback)

Vous recevez une PR et une liste d'éléments de révision à traiter (liens vers les commentaires plus ce qu'il faut faire).

1. Récupérez et checkout la branche de la PR dans votre worktree. Lisez le ticket et les éléments ; lisez le diff actuel.
2. Traitez chaque élément avec le plus petit changement qui le résout, selon les mêmes règles qu'à l'étape 4. Restez dans le périmètre du ticket : si un élément demande quelque chose au-delà, ne le construisez pas ; signalez-le comme suivi.
3. Ajoutez de nouveaux commits plutôt que de modifier ou de forcer le push, afin que les réviseurs puissent voir ce qui a changé depuis leur révision. Exécutez les tests, puis poussez.
4. Répondez sur chaque fil de commentaire traité avec une ligne disant ce qui a changé et le court SHA du commit. Pour les éléments pour lesquels on vous a dit de répondre sans modifier le code, répondez avec le texte donné. Si vous concluez qu'un élément ne doit pas être modifié, ne discutez pas dans le fil ; laissez-le et expliquez dans votre rapport.
5. Terminez par le rapport, en utilisant done si chaque élément a été traité, blocked sinon.

Rapport

Terminez votre message final avec ce bloc exactement, afin qu'un orchestrateur puisse l'analyser :

RESULTAT : done | blocked | needs-split | already-met
TICKET : <ID local> / <clé du tracker ou "non publié">
PR : <url ou "aucune">
BRANCHE : <branche ou "aucune">
IGNORE : <limites délibérées ou éléments non traités, ou "aucun">
NOTES : <une ou deux lignes : pourquoi bloqué, quoi scinder, suivis, problèmes non liés trouvés>