asanabrial/issue-flow

Issue Flow — Analyste / Développeur sur un tracker d'issues partagé

Contrat d'activation

Utiliser pour issue-flow analyst [conditions], issue-flow dev [règles-métier] [numéro-issue], travail d'analyste ou de développeur, réclamations et transitions d'état du workflow. Conditions d'analyste et domaines de développement sont facultatifs : une cible bornée est le périmètre ; sinon l'analyste audite le dépôt et le développeur implémente l'issue sélectionnée. Lire d'abord les instructions du dépôt et charger uniquement la liaison de tracker sélectionnée par la configuration de l'opérateur avant le travail sur le tracker. Charger la composition de domaine pour les règles de transfert, priorité ou routage ; les notes d'exécution pour l'invocation, la délégation ou les mécanismes d'équipe ; et les incidents de sécurité pour la justification des conflits, réclamations, transferts ou échecs.

Règles strictes

• Issue Flow possède les rôles, états, réclamations et transitions ; les domaines routés possèdent la valeur, la priorité, les preuves et les critères de complétion. Aucun côté n'invente la politique de l'autre.
• Un analyste, y compris un réviseur adverse, est en lecture seule pour le dépôt et tous les systèmes externes sauf les opérations de tracker configurées requises ci-dessous : il ne crée aucune branche/worktree/commit/PR et n'exécute aucune migration, synchronisation, écriture en base de données ou action de livraison. Il dépose au maximum une issue étayée. La révision DOIT utiliser un contexte qui n'a pas écrit la modification.
• Générer un identifiant de run <runtime>-<préfixe-session> unique et le réutiliser pour chaque écriture. Conserver l'attribution d'exécution bornée dans les étiquettes analyst:<runtime>/dev:<runtime> et l'attribution non bornée dans le texte ; les étiquettes de l'analyste persistent, tandis que celles du développeur sont supprimées lors de la publication mais conservées lors de la livraison.
• Reprendre l'issue détenue de cette exécution avant de consulter les files d'attente. Utiliser la réclamation arbitrée par timeline de la liaison sélectionnée ; la réclamation active la plus ancienne gagne. Exécuter verify_claim avant la première écriture dans le dépôt, à chaque battement de cœur, et à chaque frontière coûteuse ou irréversible ; une surface de contrôle illisible n'autorise aucune écriture.
• Conserver exactement un des états analysis, ready, in-progress, review, blocked ou done. L'état du workflow de la liaison est faisant autorité ; chaque projection configurée est mise à jour et relue, et done est explicite avant la fermeture du tracker.
• La liaison sélectionnée DOIT mapper ensure_states, create, list_state, claim, reclaim, verify_claim, heartbeat, transition, comment, last_activity, label, unassign, publish_version et close. Exécuter des opérations réversibles plutôt que de les reconstruire ; les liaisons DOIVENT déclarer les capacités non supportées et échouer en mode fermé.
• Les critères d'acceptation de l'issue, les règles du domaine routé et les règles du dépôt définissent ce qui est fait. Ne jamais inventer de portes manquantes ni réinterpréter l'issue en silence.

Portes de décision

Situation	Action
L'analyste a des conditions ou un diff/PR/issue borné	Analyser uniquement ce périmètre sous les règles applicables du dépôt et du domaine.
L'analyste n'a ni conditions ni domaine	Utiliser le contrat general autonome dans la composition de domaine ; déposer uniquement le résultat dédupliqué le plus fort ou rien.
Une route de domaine est enregistrée	L'analyste charge le livre de règles gauche ; le développeur charge le droit. Indiquer explicitement quand le routage d'implémentation est absent.
Les mécanismes d'exécution ou l'acquisition de contexte indépendant varient	Suivre les notes d'exécution ; les limites d'exécution changent le mécanisme, jamais l'invariant.
La sécurité des réclamations, re-réclamations ou transferts nécessite une justification	Suivre la liaison active et les incidents de sécurité, sans copier le récit d'incident ici.
L'état doit être choisi	Spécification invalide -> analysis ; implémentable et non assigné -> ready ; construction réclamée -> in-progress ; construit/publié -> review ; attente externe non construite -> blocked avec condition et libérateur ; fusionné et vérifié -> done.

Étapes d'exécution

Avant la première écriture sur le tracker par l'un ou l'autre rôle dans un projet inconnu, exécuter ensure_states de la liaison sélectionnée ; puis utiliser les opérations exécutables et les relectures de cette liaison plutôt que de les reconstruire. Charger la composition de domaine pour le routage, la validation d'échelle, le partitionnement des files d'attente ou le repli autonome ; les notes d'exécution pour l'invocation, l'application de la lecture seule, l'acquisition de contexte indépendant ou les limites d'exécution ; les incidents de sécurité uniquement lorsque la justification des réclamations, re-réclamations, transferts ou échecs est nécessaire ; et la livraison de dépôt uniquement lorsque les règles du dépôt ne définissent pas entièrement l'isolation ou l'intégration.

Analyste

1. Maintenir le dépôt et les systèmes externes non-tracker en lecture seule. Vider analysis du plus ancien au plus récent, puis inspecter blocked : déplacer les conditions remplies vers ready avec preuves, dater les conditions qui tiennent toujours, et nommer depuis combien de temps une personne doit une décision en attente.
2. Analyser uniquement le périmètre borné sous le livre de règles de domaine gauche. Sans conditions ni domaine, utiliser le contrat general autonome ; vérifier les preuves et les doublons, puis ne conserver au plus que le constat le plus défendable ou signaler qu'aucun n'a survécu.
3. Valider les champs, la route, l'échelle et le contrat de corps pour les constats en file d'attente et nouveaux. Pour un travail en file d'attente, ajouter le matériel de transfert manquant avec comment et ne transitionner que ce même élément complet ; ne jamais créer de remplacement. Pour un nouveau constat, remplir le modèle d'issue analyste et create avec chaque marqueur plus analyst:<runtime> et l'attribution du run-id. Utiliser ready, ou blocked avec la condition manquante exacte et le libérateur ; puis STOP sans implémenter ni assigner.

Ce que produit l'analyste

Une issue qu'un développeur peut prendre sans refaire l'analyse. Si le développeur doit redériver votre raisonnement, l'analyse n'a rien apporté.

## Description pour les humains

> [!NOTE]
> Une ou deux phrases, langage simple, pas de jargon, pas de chemins de fichiers, pas de métriques — de quoi parle cette issue, pour quelqu'un qui ne lira jamais après cette ligne. Écrit dans la langue que la configuration de l'opérateur nomme pour cette installation (voir le tableau à la fin de ce fichier). Le titre lui-même est le titre littéral fixe ci-dessus — toujours en anglais, toujours cette phrase exacte, jamais reformulé par issue. `> [!NOTE]` est la syntaxe d'alerte native de GitHub — elle s'affiche comme un encadré coloré avec bordure, ce qui est le but : cela doit être visuellement impossible à manquer sur une issue par ailleurs pleine de prose technique.

C'est la première chose sur l'issue, avant `## Problem`.

## Problem
Qu'est-ce qui est incorrect ou manque, et comment vous le savez. Preuve, pas d'affirmation : références fichier:ligne, nombres mesurés, logs, étapes de reproduction.

## Why it matters
Impact si laissé tel quel. Si vous ne pouvez pas en énoncer un, dites-le clairement — un « impact faible, déposé pour complétude » documenté est honnête et permet au développeur de déprioriser.

## Proposed approach
La conception. Les alternatives que vous avez envisagées et pourquoi vous les avez rejetées. Si vous n'êtes PAS sûr, dites quelle partie est incertaine et ce qui la résoudrait.

## Acceptance criteria
Énoncés vérifiables. « Plus rapide » n'est pas un critère ; « p95 sous 200 ms mesuré par X » en est un. Inclure ce qui ne doit PAS changer (invariants, sorties identiques octet par octet).

## Out of scope
Ce qu'un développeur ne doit explicitement pas faire ici. Cela empêche la dérive du périmètre plus fiablement que n'importe quelle quantité de prose dans les sections ci-dessus.

## Evidence
Commandes exécutées, fichiers lus, nombres mesurés. Assez pour qu'un réviseur puisse revérifier l'analyse sans la répéter.

Développeur

1. Reprendre l'issue détenue de cette exécution à son état enregistré avant de consulter les files d'attente. Sinon, vider review non assignée avant ready, en revérifiant le blocage de livraison avant de réclamer un travail publié.
2. Pour ready, partitionner les candidats valides par domaine stable et échelle déclarée, classer uniquement au sein de chaque partition, et choisir le plus ancien en-tête de partition ; un domaine sélectionné limite la sélection à son élément le plus ancien le mieux classé. Utiliser le plus ancien d'abord uniquement lorsqu'aucun candidat n'a de contrat d'échelle valide.
3. claim avec le run-id et l'horizon, puis arbitrer la timeline horodatée par le serveur ; la réclamation active la plus ancienne gagne, et un perdant commente, libère et sélectionne à nouveau. Conserver le travail de révision réclamé dans review sauf si un changement de code nécessite in-progress et un nouveau cycle de publication/révision/CI ; pour un travail prêt, transitionner une fois vers in-progress avec dev:<runtime> et sans second événement de réclamation.
4. Charger le livre de règles d'implémentation droit de la route avant de planifier ; s'il est absent, indiquer qu'aucun ne s'applique et construire selon les critères d'acceptation écrits. Suivre les règles du dépôt, utiliser le repli de livraison de dépôt pour une politique d'isolation/intégration manquante, vérifier la réclamation immédiatement avant la première écriture de branche/worktree/fichier, et implémenter dans le checkout isolé.
5. Renouveler avant de publier, publier ou réutiliser la cible de révision partagée, puis transitionner vers review. Acquérir un contexte indépendant uniquement lorsque Délégation de révision autorise cette exécution ; sinon demander une révision démarrée séparément. Exiger son verdict et une CI verte sur la même tête/base exacte ; chaque poussée invalide les deux. Laisser la livraison bloquée dans review, restaurer l'état local modifié par la tentative échouée, enregistrer le bloqueur précis, et désassigner plutôt que de le contourner ; les règles de dépôt contradictoires obtiennent une issue séparée.
6. Renouveler à chaque frontière irréversible ; fusionner uniquement après révision, CI verte, et correspondance des identités de tête/base actuelles. Pour une route de commit de fusion, exiger que les parents exacts du SHA livré soient la base et la tête révisées ; les autres stratégies configurées exigent leur topologie équivalente déclarée par la liaison et toute porte de SHA livré. Pour chaque version modifiée, publier et vérifier à distance son tag annoté immuable et la Release requise ; renouveler à nouveau, transitionner vers done, enregistrer la révision/CI/tests/mesures/PR/SHA de livraison/publications avec le run-id, et fermer. En cas de transfert, préserver toutes les preuves : une spécification erronée va vers analysis, une attente externe non construite vers blocked, un travail construit mais non livrable vers review, et un diagnostic partiel utile vers ready.

Porte de révision détaillée conservée jusqu'à la dernière tranche de retrait

6. Faire réviser la modification publiée par un contexte qui ne l'a pas écrite, puis exiger une CI verte sur la dernière tête de PR. Capturer les SHA de tête et de base avant la révision et exiger que l'artefact de verdict nomme explicitement les deux ; un « approuvé » flottant n'est pas une preuve pour une révision ou un diff particulier. Lorsque la configuration l'autorise, obtenir ce contexte vous-même — un sous-agent ou un coéquipier ; lorsqu'elle ne l'autorise pas, remettre la PR à une exécution d'analyste démarrée séparément et dire sur l'issue que vous l'attendez. Ce que la configuration décide est qui démarre la révision, jamais si elle s'exécute. Chaque poussée invalide le verdict précédent et le résultat de CI : réviser la surface modifiée et attendre à nouveau les vérifications requises.

   Si la révision, la CI ou la livraison est bloquée, STOPPER LÀ et laisser dans review. Un travail construit et publié mais qui ne peut pas être livré — un réviseur demande des modifications, une vérification échoue, une approbation native requise ne peut pas être fournie par une identité distincte, une permission manque, deux règles de projet se contredisent — est un travail terminé en attente de livraison, ce qui est exactement ce que signifie review. Ne pas le déplacer vers done : cet état signifie livré. Ne pas contourner le bloqueur non plus ; une règle que vous contournez pour livrer est une règle qui cesse de signifier quoi que ce soit.

   Commenter le bloqueur précisément — ce qui l'a refusé, ce que cette chose attend, ce que le projet exige à la place — puis désassigner pour qu'un autre acteur puisse terminer la livraison. Restaurer tout état local que vous avez modifié en essayant.

   Un bloqueur qui provient de deux règles de projet contradictoires mérite sa propre issue. Il frappera la tâche suivante, et la suivante, et chaque exécution le rediagnostiquera à partir de zéro. Un constat déposé transforme une taxe récurrente en une décision que quelqu'un peut prendre une fois.

7. Fusionner uniquement la tête PR révisée après que sa CI requise est verte, publier les tags de version, puis close. Renouveler la réclamation immédiatement avant de fusionner, exiger tête/base révisée == tête/base CI == tête/base actuelle, lier la fusion au SHA de tête révisé, et refuser si l'un ou l'autre côté a bougé. Utiliser la stratégie de fusion configurée ; un merge commit préserve la limite de branche et l'ascendance PR, tandis que squash et rebase jettent délibérément ces informations. Récupérer le SHA livré après fusion et vérifier qu'il a exactement la base révisée et la tête révisée comme parents ; ne pas prétendre à une préservation de topologie à partir d'un seul indicateur de commande. Une file d'attente de fusion est éligible uniquement lorsque sa méthode configurée garantit cette même topologie. Si le projet exige une CI sur le SHA livré exact, attendre cette porte post-fusion.

Travailler dans un dépôt — le flux par défaut

Les règles du dépôt gagnent, toujours. Lire ses instructions d'agent (AGENTS.md, CLAUDE.md ou équivalent) avant toute autre chose et les suivre. Ce qui suit est le repli pour un dépôt qui ne prescrit rien, et un plancher pour un dépôt qui n'en prescrit qu'une partie — jamais une norme concurrente.

Le repli plus ancien — utiliser l'historique des commits comme convention — ne va pas aussi loin, et il vaut la peine de dire pourquoi. Un journal git vous dit comment les messages de commit sont écrits. Il ne peut pas vous dire si deux agents peuvent partager un checkout, ou si une branche vérifiée il y a une heure est toujours valide après que quelqu'un d'autre a fusionné. Ces réponses décident si le travail parallèle se corrompt lui-même, donc ce skill les fournit plutôt que de les laisser à un domaine qui n'a aucune raison de les connaître.

1. Ne jamais travailler dans l'arbre de base. Pour un développeur, la branche par défaut est en lecture seule : pas de modifications, pas de commits. Vérifier avant le premier changement au lieu de supposer :

git branch --show-current   # main / master -> stop, branchez d'abord

Si vous constatez que vous avez déjà commité sur la branche de base et n'avez PAS poussé, déplacer les commits vers une branche et réinitialiser. Si vous avez déjà poussé, ne pas forcer la poussée — annuler et refaire correctement.

Pour

…

[tronqué pour la traduction]