CommunityProgramación y desarrollogithub.com

resolvedor-paralelo-de-issues

Resuelve varios issues de GitHub en paralelo, cada uno en su propio worktree aislado de git, y luego aterriza cada uno mediante su propio pull request.

¿Qué es resolvedor-paralelo-de-issues?

Esta habilidad para Claude Code permite a los desarrolladores resolver múltiples issues de GitHub simultáneamente, respetando la integridad del código mediante worktrees aislados. Es extremadamente útil cuando un usuario tiene un lote de issues (como "resuelve #12 #15 #18") y desea procesarlos en paralelo en lugar de uno por uno. La habilidad planifica automáticamente un grafo de dependencias a partir de los números de issue, implementa cada issue desbloqueado de forma concurrente usando subagentes aislados, tiene un revisor independiente que verifica cada diff antes de fusionarlo, y abre un PR por issue. Finalmente, espera a que CI pase, realiza un squash-merge, y cierra cada issue con un comentario describiendo exactamente lo que se hizo. Funciona exclusivamente en Claude Code gracias a sus capacidades de subagentes con aislamiento de worktree y comunicación entre agentes, y requiere solo `git`, `gh` autenticado y `jq` en el sistema.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/dhiraj-verhelm/agent-skills/tree/HEAD/skills/parallel-issue-resolver

Installed? Explore more Programación y desarrollo skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Resolvedor Paralelo de Issues

Resuelve un lote de issues de GitHub concurrentemente, cada uno aislado en su propio worktree de git, y luego aterriza cada uno mediante su propio pull request. Cinco fases — Planificar → Implementar → Revisar → Corregir → Aterrizar.

La regla fundamental: un issue está cerrado si y solo si GitHub reporta su PR como MERGED. No en una fusión local, no en una ejecución de pruebas verde en un worktree, no por lo que diga un subagente. Cada cierre lleva un comentario que dice qué se implementó realmente.

El trabajo llega a main de la misma manera que lo haría el de un humano: rama → PR → CI → squash-merge. Nada aterriza que CI no haya visto.

Inicio rápido

El usuario dice: "Resuelve #12 #15 #18 en paralelo".

  1. Prevuelo: bash <directorio-habilidad>/scripts/preflight.sh — debe salir con código 0 antes de que generes algo. No hay un paso de configuración separado; configura el repositorio en la primera ejecución.
  2. Planificar: lee cada issue, construye un grafo de dependencias, elige los issues que pueden ejecutarse ahora sin colisionar.
  3. Implementar: un subagente por issue desbloqueado con isolation: "worktree", todos generados en un solo mensaje para que se ejecuten concurrentemente. Cada uno implementa, hace commit, sube, abre un PR y escribe un traspaso.
  4. Revisar: un subagente revisor separado por issue — nunca el autor — lee el diff contra el issue y devuelve approve o changes-requested.
  5. Corregir: envía los hallazgos bloqueantes de vuelta al implementador original, luego re-revisa. Máximo dos rondas.
  6. Aterrizar: para cada issue aprobado, bash <directorio-habilidad>/scripts/land.sh <issue> <rama> <archivo-comentario> — uno a la vez.
  7. Repetir si quedan issues recién desbloqueados.

Lee REFERENCE.md para conocer los mecanismos, la detección de comandos y los problemas antes de la primera ejecución.

Fase 0 — Prevuelo

Ejecuta esto antes de cada lote. Es el único comando de configuración en la habilidad:

bash <directorio-habilidad>/scripts/preflight.sh        # añade --fix para limpiar sobras seguras

Prepara todo lo que aún no esté configurado — .worktreeinclude para que los archivos .env/secretos ignorados por git se copien en cada worktree, reglas de ignorados, worktree.baseRef: "head" — luego verifica que la ejecución realmente tendrá éxito: herramientas requeridas presentes, árbol limpio, gh autenticado, base sincronizada con el origen, CI activado en pull_request, y sin ramas agent/issue-* sobrantes ni worktrees huérfanos que puedan colisionar.

La preparación es idempotente e imprime solo cuando cambia algo, así que desde la segunda ejecución en adelante es puramente una verificación. No escribe ningún archivo rastreado — las reglas de ignorados van en .git/info/exclude, por lo que la habilidad nunca deja un diff en el repositorio de nadie.

Si sale con código distinto de cero, detente y arregla — no generes agentes. Reporta al usuario lo que encontró.

Captura la rama base: git branch --show-current → BASE. Todos los PRs apuntan a BASE.

Fase 1 — Planificar (orquestador, en línea)

Para cada issue: gh issue view <id> --json number,title,body,labels,state,comments. Si un issue referencia un PRD/épica padre, léelo también.

Omite cualquier issue que ya esté CLOSED, o que ya tenga un PR abierto (gh pr list --search "<id> in:body") — dilo en lugar de duplicar trabajo.

Construye un grafo de dependencias. El issue B está bloqueado por A si se cumple alguna de estas condiciones:

  • B necesita código/infraestructura que A introduce.
  • B y A modifican archivos/módulos superpuestos → las ediciones concurrentes colisionarían.
  • B depende de una forma de API o decisión que A establece.

Un issue está desbloqueado si tiene cero dependencias bloqueantes sobre los otros issues en este lote. Solo los issues desbloqueados se ejecutan en esta ronda. Si cada issue está bloqueado, ejecuta solo el que tenga las dependencias más débiles para romper el ciclo.

Asigna a cada uno una rama determinista: agent/issue-<id>. Informa al usuario del plan del lote antes de generar — qué issues se ejecutan ahora, cuáles esperan y por qué.

Fase 2 — Implementar (subagentes paralelos)

Para cada issue desbloqueado, genera un subagente a través de la herramienta Agent con isolation: "worktree". Pon todas las generaciones en un solo mensaje para que se ejecuten concurrentemente.

  • Tipo de subagente: general-purpose (necesita editar + bash).
  • Nómbralo impl-<id> — necesitarás el nombre para enviarle los hallazgos de la revisión en la Fase 4 con su contexto intacto.
  • Prompt: el contenido de prompts/implement.md con {{ISSUE_ID}}, {{BRANCH}} (= agent/issue-<id>), {{BASE}} y {{STATE_DIR}} (ruta absoluta a <repo>/.claude/pir) completados.

Cada subagente implementa, ordena su propio diff, sube, abre un PR y escribe dos archivos de traspaso en {{STATE_DIR}}. Los archivos son el registro duradero — sobreviven a la compactación del contexto, la línea RESULT no. Ver REFERENCE.md.

Fase 3 — Revisión independiente (subagentes paralelos)

El agente implementador no revisa su propio trabajo. Para cada issue que haya vuelto como complete con un PR abierto, genera un revisor separado — nuevamente todos en un solo mensaje.

  • Tipo de subagente: general-purpose. Nómbralo review-<id>.
  • Sin isolation: "worktree" — la revisión es de solo lectura y funciona con git diff {{BASE}}...{{BRANCH}} desde el checkout base. Sin worktree que crear o limpiar.
  • Prompt: prompts/review.md con {{ISSUE_ID}}, {{BRANCH}}, {{BASE}}, {{PR}}, {{STATE_DIR}} completados.

El revisor escribe {{STATE_DIR}}/issue-<id>.review.json con un veredicto de approve o changes-requested más los hallazgos. Nunca edita, sube, fusiona ni comenta — reporta, tú decides.

Publica el veredicto en el PR para que el razonamiento quede registrado donde un humano lo buscaría:

gh pr comment <PR> --body "$(jq -r '\"**Revisión automatizada: \(.verdict)**\n\n\(.summary)\"' .claude/pir/issue-<id>.review.json)"

Fase 4 — Ronda de corrección (solo para changes-requested)

Envía los hallazgos bloqueantes de vuelta al implementador original, que aún tiene el código en contexto:

SendMessage → to: "impl-<id>"

La revisión independiente del PR # encontró problema(s) bloqueante(s). Corrige solo estos, vuelve a ejecutar las comprobaciones, sube a la misma rama y actualiza tu archivo de traspaso .md para que coincida con el estado final.

<el array blocking, textual>

Si crees que un hallazgo es incorrecto, di por qué en lugar de cambiar código que crees correcto.

Luego vuelve a ejecutar la Fase 3 para ese issue (un agente review-<id> nuevo — ronda 2).

Límite de dos rondas de revisión. Si un issue sigue en changes-requested después de la ronda 2, detente: deja el PR y el issue abiertos, e informa al usuario qué está sin resolver con los hallazgos del revisor. Tres rondas significan que el issue está mal especificado o el desacuerdo necesita a un humano, y más rondas queman tokens sin converger.

Si el implementador refuta un hallazgo en lugar de corregirlo, lee ambos argumentos y decide tú mismo. No te limites a reenviarlo — así es como se forman los bucles.

Fase 5 — Aterrizar (orquestador, desde el checkout BASE)

Aterriza los issues uno a la vez, en serie — nunca en paralelo. Cada fusión cambia BASE, lo que puede desactualizar el siguiente PR; land.sh rebasa cuando GitHub reporta un conflicto, y eso solo funciona contra una base ya actualizada.

Para cada issue cuyo traspaso diga status: "complete" y cuyo veredicto de revisión sea approve:

bash <directorio-habilidad>/scripts/land.sh <issue> agent/issue-<issue> .claude/pir/issue-<issue>.md

El script hace toda la parte final en el único orden correcto: verificar el veredicto de revisión → liberar el worktree → rebasar si hay conflictos → esperar a que CI se ponga verde → squash-merge → verificar que GitHub reporte MERGED → cerrar el issue con el comentario de traspaso → hacer fast-forward de BASE → eliminar la rama → podar worktrees.

Se niega a aterrizar cualquier cosa sin un veredicto approve en disco, por lo que la revisión es una compuerta, no un hábito. PIR_SKIP_REVIEW=1 lo anula — si lo usas, dilo en voz alta, porque elimina la única verificación que CI no puede realizar.

Rama según su código de salida:

CódigoSignificadoQué haces
0Aterrizado, cerrado, limpiadoContinúa al siguiente issue
2Condición previa fallidaArregla y vuelve a ejecutar; no fuerces
3Conflicto de rebase que un script no puede resolverResuelve manualmente en esa rama, sube, vuelve a ejecutar land.sh
4CI falló o expiróLee la verificación fallida, arregla en la rama, sube, vuelve a ejecutar land.sh
5Problema de fusión/cierreInspecciona el PR — puede estar fusionado con el issue aún abierto

Cualquier cosa que no sea 0 deja el PR y el issue abiertos, deliberadamente. Reporta esos al usuario con el enlace del PR; no reintentes a ciegas.

Luego vuelve a la Fase 1 si quedan issues bloqueados.

Fase 6 — Reportar

Informa al usuario, por issue: aterrizado (PR # + enlace), dejado abierto y por qué, o saltado y por qué. Para cualquier cosa dejada abierta después de dos rondas de revisión, incluye los hallazgos bloqueantes no resueltos del revisor. Nunca afirmes que un issue está terminado sin el número de PR fusionado.

Requisitos

Se ejecuta en Claude Code: depende de subagentes con isolation: "worktree", SendMessage y .worktreeinclude. Instálalo con npx skills add dhiraj-verhelm/agent-skills --skill parallel-issue-resolver, o copia este directorio en ~/.claude/skills/ o en .claude/skills/ de un repositorio. No hay configuración por repositorio, ningún archivo de configuración que editar y ninguna ruta que corregir.

Lo que necesita en la máquina: git, gh (autenticado) y jq. El prevuelo verifica los tres y nombra los que falten.

Lo que necesita del repositorio: un remoto de GitHub y CI que reporte verificaciones en los pull requests. El prevuelo advierte si no encuentra dicho CI. Aún puedes ejecutar con PIR_REQUIRE_CI=0, lo que aterriza PRs sin compuerta de CI. Dilo en voz alta si lo haces, porque elimina la principal propiedad de seguridad de la habilidad.

Lo que no hará en el repositorio: modificar ningún archivo rastreado. Las reglas de ignorados se escriben en .git/info/exclude, por lo que la preparación no deja ningún diff y nada puede filtrarse a un commit.

Los scripts se invocan como bash <ruta>, por lo que un bit ejecutable perdido durante la copia no rompe nada.

Seguridad y compuertas

  • Nunca git push a BASE, y nunca uses --force salvo en la rama del propio agente (--force-with-lease, solo dentro del rebase de land.sh).
  • Nunca git add -A / git add . — solo prepara rutas explícitas.
  • Nunca pongas Closes #N / Fixes #N en el cuerpo de un PR. Eso hace que GitHub cierre el issue silenciosamente al fusionar, sin ningún comentario sobre lo que se hizo. Usa Refs #N; el cierre es explícito, controlado por una fusión verificada, y siempre lleva el resumen.
  • Nunca fusiones con --admin, y nunca te saltes una verificación en rojo.
  • Un subagente por issue, trabajando solo en su issue.
  • Si el prevuelo falla, detente e informa al usuario. Si el árbol está sucio, detente — los worktrees se ramifican desde HEAD.

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

Skills relacionados