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.

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

TODOS tus comandos bash deben ejecutarse en:
  /home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug>

Usa SIEMPRE paths absolutos con ese prefijo. NO uses cd al inicio — usa paths absolutos en cada comando.

## 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: cd /home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug> && go build -tags goolm ./...

3. **Tests obligatorios**:
   - Escribir tests para todo código nuevo
   - Ejecutar: cd /home/ubuntu/CodeProyects/agents_and_robots/worktrees/<slug> && go test -tags goolm ./...
   - NO continuar si los tests fallan

4. **Cerrar el issue**:
   - mv dev/issues/<NNNN>-<slug>.md dev/issues/completed/
   - Actualizar dev/issues/README.md: link a completed/, estado a "completado"
   - Commit: docs: cerrar issue <NNNN>

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: 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 7: 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`**
- **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 (ej: depende de issue completado que no está en la lista) se excluyen automáticamente

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