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".
- 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. - Planificar: lee cada issue, construye un grafo de dependencias, elige los issues que pueden ejecutarse ahora sin colisionar.
- 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. - Revisar: un subagente revisor separado por issue — nunca el autor — lee el diff contra el issue y devuelve
approveochanges-requested. - Corregir: envía los hallazgos bloqueantes de vuelta al implementador original, luego re-revisa. Máximo dos rondas.
- Aterrizar: para cada issue aprobado,
bash <directorio-habilidad>/scripts/land.sh <issue> <rama> <archivo-comentario>— uno a la vez. - 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ómbraloreview-<id>. - Sin
isolation: "worktree"— la revisión es de solo lectura y funciona congit 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
.mdpara 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ódigo | Significado | Qué haces |
|---|---|---|
0 | Aterrizado, cerrado, limpiado | Continúa al siguiente issue |
2 | Condición previa fallida | Arregla y vuelve a ejecutar; no fuerces |
3 | Conflicto de rebase que un script no puede resolver | Resuelve manualmente en esa rama, sube, vuelve a ejecutar land.sh |
4 | CI falló o expiró | Lee la verificación fallida, arregla en la rama, sube, vuelve a ejecutar land.sh |
5 | Problema de fusión/cierre | Inspecciona 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 pusha BASE, y nunca uses--forcesalvo en la rama del propio agente (--force-with-lease, solo dentro del rebase deland.sh). - Nunca
git add -A/git add .— solo prepara rutas explícitas. - Nunca pongas
Closes #N/Fixes #Nen el cuerpo de un PR. Eso hace que GitHub cierre el issue silenciosamente al fusionar, sin ningún comentario sobre lo que se hizo. UsaRefs #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.