repo_Claude/.claude/skills/parallel-fix-issues/SKILL.md

name, description, allowed-tools, argument-hint

name	description	allowed-tools	argument-hint
parallel-fix-issues	Implementar múltiples issues en paralelo. Analiza dependencias entre issues pendientes, crea git worktrees aislados, lanza agentes concurrentes para cada issue, verifica resultados (build + tests) e integra todo a master en orden.	Bash Read Write Edit Grep Glob Agent	[issue-numbers... | all]

Parallel Fix Issues

Skill para implementar múltiples issues simultáneamente usando git worktrees y agentes paralelos.

Inputs

• $ARGUMENTS: lista de issue numbers (ej: 0026 0027 0031) o all para todos los pendientes.
• Si no hay argumentos, preguntar al usuario qué issues quiere procesar.

Proceso completo

Fase 1: Análisis de dependencias

Lanzar un Agent (subagent_type: Explore) para analizar los issues y producir un plan de ejecución.

El agente debe:

1. Leer dev/issues/README.md y filtrar los issues pendientes
2. Si $ARGUMENTS no es all, filtrar solo los issues solicitados
3. Para cada issue pendiente, leer el archivo completo y extraer:
   • Objetivo (resumen)
   • Prerequisitos y dependencias explícitas (ej: "requiere issue 0026")
   • Archivos afectados (para detectar conflictos potenciales entre issues)
4. Construir un grafo de dependencias y agrupar en waves (oleadas):
   • Wave 1: issues sin dependencias entre sí y sin dependencias pendientes
   • Wave 2: issues que dependen de wave 1
   • Wave N: etc.
5. Dentro de cada wave, identificar conflictos potenciales (dos issues que tocan los mismos archivos)
6. Devolver el resultado en este formato exacto:

WAVE 1 (paralelo):
- <NNNN>-<slug> — <objetivo resumido> — archivos: <lista>
- <NNNN>-<slug> — <objetivo resumido> — archivos: <lista>

WAVE 2 (paralelo, después de wave 1):
- <NNNN>-<slug> — <objetivo resumido> — depende de: <NNNN>

CONFLICTOS POTENCIALES:
- <NNNN> y <NNNN> tocan <archivo> — riesgo de merge conflict

ISSUES EXCLUIDOS:
- <NNNN>-<slug> — razón (dependencia externa no resuelta, etc.)

Mostrar el resultado al usuario y pedir confirmación antes de continuar. El usuario puede:

• Aprobar el plan tal cual
• Excluir issues específicos
• Reordenar waves

Fase 2: Setup de worktrees

Una vez aprobado el plan, crear los worktrees.

.claude/skills/parallel-fix-issues/scripts/setup-worktrees.sh <slug-1> <slug-2> ...

El script crea un worktree por issue en worktrees/<slug>/, cada uno en su propia branch issue/<slug>.

Verificar que todos los worktrees se crearon correctamente:

git worktree list

Fase 3: Ejecución paralela por waves

Para cada wave, lanzar Agents en paralelo (un Agent por issue, todos en el mismo mensaje para ejecución concurrente).

CRÍTICO: Lanzar todos los agentes de una wave en una sola respuesta con múltiples tool calls. NO lanzar de uno en uno.

PERMISOS: Todas las llamadas Bash de los agentes deben usar dangerouslyDisableSandbox: true para evitar prompts de permisos que bloqueen la ejecución paralela. Indicar esto explícitamente en el prompt de cada agente.

El prompt de cada agente debe incluir:

1. Ruta absoluta del worktree (calcular con $(git rev-parse --show-toplevel)/worktrees/<slug>, o pasar la ruta literal ya resuelta)
2. Build tag Go del proyecto (detectar — ver "Detección del build tag" más abajo)
3. Contenido completo del issue (copiar el markdown entero)
4. Instrucciones de ejecución (ver template abajo)

Detección del build tag

Antes de lanzar los agentes, detectar el build tag del proyecto para los comandos go build/go test:

# Heurísticas (en orden):
# 1. grep en go files por comentarios //go:build <tag>
# 2. Makefile con -tags <tag>
# 3. README con mención explícita
# Si no se encuentra ninguno, dejar la variable vacía (go build/test sin -tags)
BUILD_TAG=$(grep -rh "//go:build " --include="*.go" . 2>/dev/null | head -1 | sed -E 's|^.*//go:build ([^ ]+).*|\1|' || true)

Pasar BUILD_TAG al agente. Si está vacío, el agente usa go build ./... sin -tags.

Template de prompt para cada agente

Eres un agente de desarrollo implementando el issue <NNNN>-<slug>.

## Directorio de trabajo

Worktree: <RUTA_ABSOLUTA_DEL_WORKTREE>   # ej: /home/user/proyecto/worktrees/<slug>

Usa SIEMPRE esta ruta como prefijo en paths absolutos.
Variable de conveniencia para comandos:
  W=<RUTA_ABSOLUTA_DEL_WORKTREE>

## Build tag Go

BUILD_TAG=<VALOR_DETECTADO_O_VACIO>   # ej: fts5, goolm, o vacío

Úsalo solo si está definido:
  GO_BUILD="go build ${BUILD_TAG:+-tags $BUILD_TAG} ./..."
  GO_TEST="go test ${BUILD_TAG:+-tags $BUILD_TAG} ./..."

## Permisos

IMPORTANTE: En TODAS tus llamadas al tool Bash, usa el parámetro `dangerouslyDisableSandbox: true`.
Esto es necesario porque estás ejecutando en paralelo con otros agentes y no hay usuario interactivo
para aprobar permisos. Ejemplo:

  Bash({ command: "cd $W && $GO_BUILD", dangerouslyDisableSandbox: true })

## Issue a implementar

<PEGAR CONTENIDO COMPLETO DEL ISSUE AQUÍ>

## Instrucciones

Sigue este flujo estrictamente:

1. **Leer el issue** — ya lo tienes arriba, entiende objetivo, tareas y arquitectura.

2. **Implementar todas las tareas** en orden:
   - Respetar pure core / impure shell (pkg/ puro, shell/ impuro)
   - Hacer commits atómicos por bloque lógico
   - Prefijos: feat:, fix:, test:, docs:, refactor:, chore:
   - NO hacer commits WIP ni código a medias
   - Compilar frecuentemente:
     Bash({ command: "cd $W && $GO_BUILD", dangerouslyDisableSandbox: true })

3. **Tests obligatorios**:
   - Escribir tests para todo código nuevo
   - Ejecutar:
     Bash({ command: "cd $W && $GO_TEST", dangerouslyDisableSandbox: true })
   - NO continuar si los tests fallan

4. **Cerrar el issue** — solo mover el archivo, NO tocar README:
   - Bash({ command: "cd $W && git mv dev/issues/<NNNN>-<slug>.md dev/issues/completed/", dangerouslyDisableSandbox: true })
   - Commit: docs: cerrar issue <NNNN>
   IMPORTANTE: usar `git mv` (no `mv` + `git add`) para que git registre el movimiento.
   IMPORTANTE: NO modificar dev/issues/README.md — lo hace el orquestador después del merge
   para evitar conflictos entre agentes paralelos.

5. **NO hacer merge a master, NO hacer push.** La integración la maneja el orquestador.

6. **Reportar resultado** al final:
   - ÉXITO: qué se implementó, cuántos commits, tests pasando
   - FALLO: qué falló, en qué paso, qué queda pendiente

Esperar a que todos los agentes de la wave terminen antes de pasar a la siguiente wave.

Fase 4: Verificación

Después de cada wave, verificar TODOS los worktrees completados:

.claude/skills/parallel-fix-issues/scripts/verify-worktree.sh worktrees/<slug>

El script verifica:

• go build ${BUILD_TAG:+-tags $BUILD_TAG} ./... — compila sin errores
• go test ${BUILD_TAG:+-tags $BUILD_TAG} ./... — tests pasan
• Issue movido a dev/issues/completed/
• Al menos 1 commit en la branch

El script acepta BUILD_TAG como variable de entorno (detectada en Fase 3) o como segundo argumento:

BUILD_TAG=fts5 .claude/skills/parallel-fix-issues/scripts/verify-worktree.sh worktrees/<slug>
# o
.claude/skills/parallel-fix-issues/scripts/verify-worktree.sh worktrees/<slug> fts5

Si un worktree falla verificación:

1. Reportar al usuario qué falló
2. Preguntar si quiere: (a) intentar arreglar, (b) excluir ese issue, (c) abortar todo
3. Si se excluye, marcar para no integrar

Fase 5: Integración a master

Una vez todas las waves verificadas, integrar a master en orden de waves (wave 1 primero, luego wave 2, etc.).

.claude/skills/parallel-fix-issues/scripts/integrate-worktrees.sh <slug-1> <slug-2> ...

El script hace para cada branch:

1. git checkout master
2. git merge --no-ff issue/<slug> con mensaje descriptivo
3. Si hay merge conflict: PARAR e informar al usuario

Después de cada merge, re-verificar que master compila:

go build ${BUILD_TAG:+-tags $BUILD_TAG} ./... && go test ${BUILD_TAG:+-tags $BUILD_TAG} ./...

Si falla después de un merge, PARAR e informar — no continuar con más merges.

Fase 6: Actualizar README de issues

Después de integrar TODOS los issues exitosos, actualizar dev/issues/README.md una sola vez desde master. Esto evita conflictos: los agentes paralelos solo mueven archivos, el orquestador actualiza el índice.

Para cada issue integrado:

1. Cambiar el link de [<NNNN>-<slug>.md](<NNNN>-<slug>.md) a [<NNNN>-<slug>.md](completed/<NNNN>-<slug>.md)
2. Cambiar el estado de pendiente a completado

Hacer un solo commit:

git add dev/issues/README.md
git commit -m "docs: actualizar README de issues — marcar <N> issues como completados"

Fase 7: Limpieza

Si todo fue exitoso:

# Eliminar worktrees y branches
for slug in <slugs...>; do
  git worktree remove "worktrees/${slug}" 2>/dev/null
  git branch -d "issue/${slug}" 2>/dev/null
done

Fase 8: Reporte final

Mostrar al usuario un resumen:

## Resultado de parallel-fix-issues

### Issues completados
- ✓ 0026-split-runtime — 5 commits
- ✓ 0027-prune-config-schema — 3 commits
- ✓ 0031-expand-file-tools — 7 commits

### Issues fallidos
- ✗ 0029-core-tests — falló en fase de tests (excluido)

### Estado de master
- Build: OK
- Tests: OK (142 passed)
- Commits nuevos: 18

### Siguiente paso
Ejecutar: git push

Notas importantes

• Build tag Go: detectar del proyecto en Fase 3 (ver "Detección del build tag"). Si el proyecto no usa build tags, omitir -tags en todos los comandos
• Siempre usar dangerouslyDisableSandbox: true en todas las llamadas Bash de los agentes paralelos
• Nunca hacer push automáticamente — el usuario decide cuándo pushear
• Si hay merge conflicts, parar y pedir intervención manual
• Un worktree = un issue = una branch — nunca mezclar
• Los worktrees se crean desde master actualizado
• La carpeta worktrees/ está en .gitignore
• Issues con dependencias externas no resueltas se excluyen automáticamente
• README centralizado: los agentes NO tocan dev/issues/README.md — solo el orquestador lo actualiza después del merge, en un solo commit. Esto evita merge conflicts entre agentes paralelos
• git mv para cerrar issues: usar git mv (no mv + git add) para mover issues a completed/

Casos de uso

# Implementar todos los issues pendientes
/parallel-fix-issues all

# Implementar issues específicos
/parallel-fix-issues 0026 0027 0031

# Solo los issues de refactor
/parallel-fix-issues 0026 0027 0028