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

---
name: parallel-fix-issues
description: >
  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.
allowed-tools: Bash Read Write Edit Grep Glob Agent
argument-hint: "[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.

```bash
.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:

```bash
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**: `/home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug>`
2. **Contenido completo del issue** (copiar el markdown entero)
3. **Instrucciones de ejecución** (ver template abajo)

#### Template de prompt para cada agente

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

## Directorio de trabajo

Worktree: /home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug>

Usa SIEMPRE esta ruta como prefijo en paths absolutos.
Variable de conveniencia para comandos:
  W=/home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug>

## 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 -tags goolm ./...", 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 -tags goolm ./...", dangerouslyDisableSandbox: true })

3. **Tests obligatorios**:
   - Escribir tests para todo código nuevo
   - Ejecutar:
     Bash({ command: "cd $W && go test -tags goolm ./...", 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:

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

El script verifica:
- `go build -tags goolm ./...` — compila sin errores
- `go test -tags goolm ./...` — tests pasan
- Issue movido a `dev/issues/completed/`
- Al menos 1 commit en la branch

**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.).

```bash
.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:

```bash
go build -tags goolm ./... && go test -tags goolm ./...
```

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:

```bash
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:

```bash
# 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

- **Siempre compilar con `-tags goolm`**
- **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
```