Que fait Résolveur parallèle d'issues ?
Résoudre un lot d'issues GitHub simultanément, chacune isolée dans sa propre arborescence de travail git, puis les intégrer via leur propre pull request. Cinq phases — Planifier → Implémenter → Réviser → Corriger → Intégrer.
La règle fondamentale : une issue n'est fermée que si et seulement si GitHub signale sa PR comme MERGED. Pas lors d'une fusion locale, pas après un test vert dans une worktree, pas sur la parole d'un sous-agent. Chaque fermeture porte un commentaire décrivant ce qui a été réellement implémenté.
Le travail arrive sur main de la même manière qu'un humain le ferait : branche → PR → CI → squash-merge. Rien n'atterrit sans que la CI ne l'ait vu.
Démarrage rapide
L'utilisateur dit : "Résoudre #12 #15 #18 en parallèle".
- Pré-vérification :
bash <skill-dir>/scripts/preflight.sh— doit se terminer avec 0 avant de lancer quoi que ce soit. Il n'y a pas d'étape de configuration séparée ; il configure le dépôt lui-même au premier lancement. - Planifier : lire chaque issue, construire un graphe de dépendances, choisir les issues qui peuvent s'exécuter maintenant sans collision.
- Implémenter : un sous-agent par issue non bloquée avec
isolation: "worktree", tous lancés dans un seul message pour qu'ils s'exécutent simultanément. Chacun implémente, valide, pousse, ouvre une PR et écrit un fichier de transmission. - Réviser : un sous-agent distinct pour chaque issue — jamais l'auteur — lit le diff par rapport à l'issue et retourne
approveouchanges-requested. - Corriger : renvoyer les constatations bloquantes à l'implémenteur d'origine, puis réexaminer. Deux cycles maximum.
- Intégrer : pour chaque issue approuvée,
bash <skill-dir>/scripts/land.sh <issue> <branche> <fichier-commentaire>— une par une. - Boucler si des issues débloquées restent.
Lisez REFERENCE.md pour les mécanismes, la détection des commandes et les pièges avant le premier lancement.
Phase 0 — Pré-vérification
Exécutez ceci avant chaque lot. C'est la seule commande de configuration du skill :
bash <skill-dir>/scripts/preflight.sh # ajoutez --fix pour nettoyer les résidus sans risque
Il amorce tout ce qui n'est pas encore configuré — .worktreeinclude pour que les fichiers .env/secrets ignorés par git soient copiés dans chaque worktree, les règles d'ignorance, worktree.baseRef: "head" — puis vérifie que l'exécution réussira : outils requis présents, arbre propre, gh authentifié, base synchronisée avec l'origine, CI déclenchant sur pull_request, et aucun résidu de branches agent/issue-* ou worktrees orphelins qui pourraient entrer en collision.
L'amorçage est idempotent et n'affiche un message que lorsqu'il modifie quelque chose, donc à partir du deuxième lancement, c'est purement une vérification. Il n'écrit aucun fichier suivi — les règles d'ignorance vont dans .git/info/exclude, donc le skill ne laisse jamais de diff dans le dépôt de quiconque.
S'il se termine avec un code non nul, arrêtez-vous et corrigez — ne lancez pas d'agents. Signalez ce qu'il a trouvé à l'utilisateur.
Capturez la branche de base : git branch --show-current → BASE. Toutes les PR ciblent BASE.
Phase 1 — Planifier (orchestrateur, en ligne)
Pour chaque issue : gh issue view <id> --json number,title,body,labels,state,comments. Si une issue fait référence à un document PRD/épic parent, lisez-le aussi.
Ignorez toute issue qui est déjà CLOSED, ou qui a déjà une PR ouverte (gh pr list --search "<id> in:body") — dites-le plutôt que de dupliquer le travail.
Construisez un graphe de dépendances. L'issue B est bloquée par A si l'un des cas suivants s'applique :
- B a besoin du code/de l'infrastructure que A introduit.
- B et A modifient des fichiers/modules qui se chevauchent → des modifications simultanées entreraient en collision.
- B dépend d'une forme d'API ou d'une décision que A établit.
Une issue est débloquée si elle n'a zéro dépendance bloquante sur les autres issues de ce lot. Seules les issues débloquées s'exécutent lors de ce tour. Si chaque issue est bloquée, exécutez uniquement celle avec les dépendances les plus faibles pour briser le cycle.
Attribuez à chacune une branche déterministe : agent/issue-<id>. Dites à l'utilisateur le plan du lot avant de lancer — quelles issues s'exécutent maintenant, lesquelles attendent, et pourquoi.
Phase 2 — Implémenter (sous-agents parallèles)
Pour chaque issue débloquée, lancez un sous-agent via l'outil Agent avec isolation: "worktree". Mettez tous les lancements dans un seul message pour qu'ils s'exécutent simultanément.
- Type de sous-agent :
general-purpose(a besoin d'édition + bash). - Nommez-le
impl-<id>— vous aurez besoin du nom pour renvoyer les constatations de révision dans la Phase 4 avec son contexte intact. - Invite : le contenu de prompts/implement.md avec
{{ISSUE_ID}},{{BRANCH}}(=agent/issue-<id>),{{BASE}}, et{{STATE_DIR}}(chemin absolu vers<depot>/.claude/pir) renseignés.
Chaque sous-agent implémente, nettoie son propre diff, pousse, ouvre une PR et écrit deux fichiers de transmission dans {{STATE_DIR}}. Les fichiers sont l'enregistrement durable — ils survivent à la compaction du contexte, la ligne RESULT non. Voir REFERENCE.md.
Phase 3 — Révision indépendante (sous-agents parallèles)
L'agent qui implémente ne révise pas son propre travail. Pour chaque issue revenue complete avec une PR ouverte, lancez un réviseur séparé — à nouveau tous dans un seul message.
- Type de sous-agent :
general-purpose. Nommez-lereview-<id>. - Pas de
isolation: "worktree"— la révision est en lecture seule et travaille à partir degit diff {{BASE}}...{{BRANCH}}depuis l'extraction de base. Pas de worktree à créer ou à nettoyer. - Invite : prompts/review.md avec
{{ISSUE_ID}},{{BRANCH}},{{BASE}},{{PR}},{{STATE_DIR}}renseignés.
Le réviseur écrit {{STATE_DIR}}/issue-<id>.review.json avec un verdict de approve ou changes-requested plus des constatations. Il ne modifie jamais, ne pousse jamais, ne fusionne jamais et ne commente jamais — il rapporte, vous décidez.
Publiez le verdict sur la PR pour que le raisonnement soit enregistré là où un humain le chercherait :
gh pr comment <PR> --body "$(jq -r '"**Révision automatisée : \(.verdict)**\n\n\(.summary)"' .claude/pir/issue-<id>.review.json)"
Phase 4 — Tour de correction (uniquement pour changes-requested)
Envoyez les constatations bloquantes à l'implémenteur d'origine, qui a toujours le code en contexte :
SendMessage → to: "impl-<id>"
La révision indépendante de la PR # a trouvé problème(s) bloquant(s). Corrigez uniquement ceux-ci, relancez les vérifications, poussez sur la même branche et mettez à jour votre fichier de transmission
.mdpour correspondre à l'état final.<le tableau
blocking, textuellement>Si vous pensez qu'une constatation est erronée, dites pourquoi au lieu de modifier un code que vous estimez correct.
Relancez ensuite la Phase 3 pour cette issue (un nouvel agent review-<id> — tour 2).
Limitez à deux tours de révision. Si une issue est toujours changes-requested après le tour 2, arrêtez-vous : laissez la PR et l'issue ouvertes, et dites à l'utilisateur ce qui n'est pas résolu avec les constatations du réviseur. Trois tours signifient que l'issue est sous-spécifiée ou que le désaccord nécessite un humain, et les tours supplémentaires brûlent des tokens sans converger.
Si l'implémenteur conteste une constatation plutôt que de la corriger, lisez les deux arguments et tranchez vous-même. Ne vous contentez pas de le relayer — c'est ainsi que se forment les boucles.
Phase 5 — Intégrer (orchestrateur, depuis l'extraction BASE)
Intégrez les issues une par une, en série — jamais en parallèle. Chaque fusion modifie BASE, ce qui peut rendre obsolète la PR suivante ; land.sh rebasifie lorsque GitHub signale un conflit, et cela ne fonctionne que contre une base déjà mise à jour.
Pour chaque issue dont la transmission indique status: "complete" et dont le verdict de révision est approve :
bash <skill-dir>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md
Le script effectue toute la partie finale dans le seul ordre correct : vérifier le verdict de révision → libérer la worktree → rebasifier en cas de conflit → attendre que la CI devienne verte → squash-merger → vérifier que GitHub signale MERGED → fermer l'issue avec le commentaire de transmission → avancer rapidement BASE → supprimer la branche → nettoyer les worktrees.
Il refuse d'intégrer quoi que ce soit sans un verdict approve sur le disque, donc la révision est une barrière plutôt qu'une habitude. PIR_SKIP_REVIEW=1 le remplace — si vous l'utilisez, dites-le à voix haute, car cela supprime la seule vérification que la CI ne peut pas effectuer.
Branchez-vous sur son code de sortie :
| Code | Signification | Ce que vous faites |
|---|---|---|
0 | Intégré, fermé, nettoyé | Passez à l'issue suivante |
2 | Condition préalable échouée | Corrigez et relancez ; ne forcez pas |
3 | Conflit de rebasification qu'un script ne peut pas résoudre | Résolvez manuellement sur cette branche, poussez, relancez land.sh |
4 | CI échouée ou expirée | Lisez la vérification qui a échoué, corrigez sur la branche, poussez, relancez land.sh |
5 | Problème de fusion/fermeture | Inspectez la PR — elle peut être fusionnée avec l'issue toujours ouverte |
Tout ce qui n'est pas 0 laisse la PR et l'issue ouvertes, délibérément. Signalez ces cas à l'utilisateur avec le lien de la PR ; ne réessayez pas aveuglément.
Revenez ensuite à la Phase 1 si des issues bloquées restent.
Phase 6 — Rapporter
Dites à l'utilisateur, par issue : intégrée (PR # + lien), laissée ouverte et pourquoi, ou ignorée et pourquoi. Pour tout ce qui est laissé ouvert après deux tours de révision, incluez les constatations bloquantes non résolues du réviseur. Ne prétendez jamais qu'une issue est terminée sans le numéro de PR fusionnée.
Prérequis
S'exécute dans Claude Code : il repose sur les sous-agents avec isolation: "worktree", SendMessage et .worktreeinclude. Installez avec npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver, ou copiez ce dossier dans ~/.claude/skills/ ou .claude/skills/ d'un dépôt. Il n'y a pas de configuration par dépôt, pas de fichier de configuration à éditer et pas de chemins à corriger.
Ce dont il a besoin sur la machine : git, gh (authentifié) et jq. La pré-vérification vérifie les trois et nomme ceux qui manquent.
Ce dont il a besoin du dépôt : une remote GitHub, et une CI qui signale les vérifications sur les pull requests. La pré-vérification avertit si elle ne trouve pas de telle CI. Vous pouvez toujours exécuter avec PIR_REQUIRE_CI=0, qui intègre les PR sans barrière CI. Dites-le à voix haute si vous le faites, car cela supprime la principale propriété de sécurité du skill.
Ce qu'il ne fera pas au dépôt : modifier un fichier suivi. Les règles d'ignorance sont écrites dans .git/info/exclude, donc l'amorçage ne laisse aucun diff et rien ne peut fuiter dans un commit.
Les scripts sont invoqués comme bash <chemin>, donc un bit exécutable perdu pendant la copie ne casse rien.
Sécurité et barrières
- Ne jamais
git pushsur BASE, et ne jamais--forceautre chose que la branche de l'agent (--force-with-lease, uniquement à l'intérieur du rebasification deland.sh). - Ne jamais
git add -A/git add .— ne mettez en scène que des chemins explicites. - Ne jamais mettre
Closes #N/Fixes #Ndans le corps d'une PR. Cela fait fermer l'issue silencieusement par GitHub lors de la fusion, sans commentaire sur ce qui a été fait. UtilisezRefs #N; la fermeture est explicite, barrée par la fusion vérifiée, et porte toujours le résumé. - Ne jamais fusionner avec
--admin, et ne jamais ignorer une vérification rouge. - Un sous-agent par issue, travaillant uniquement sur son issue.
- Si la pré-vérification échoue, arrêtez-vous et dites-le à l'utilisateur. Si l'arbre est sale, arrêtez-vous — les worktrees partent de HEAD.