repo_Claude/.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** (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 stack y comandos build/test

Antes de lanzar los agentes, detectar el stack del proyecto y los comandos correspondientes. La skill es **agnostica del lenguaje**: soporta Go, C++, Rust, Node, Python o cualquier otro stack via override.

**Resolucion de comandos** (en orden de prioridad):

1. **Override explicito** del usuario (env vars `BUILD_CMD` y `TEST_CMD` o argumentos al invocar la skill).
2. **Manifest opcional** `.parallel-fix-issues.yml` en la raiz del repo:
   ```yaml
   build: "cmake -S cpp -B cpp/build && cmake --build cpp/build -j"
   test:  "ctest --test-dir cpp/build --output-on-failure"
   ```
3. **Auto-deteccion** segun ficheros raiz:
   - `go.mod`         → `go build [-tags X] ./...`        + `go test [-tags X] ./...` (X auto-detectado de `//go:build`)
   - `CMakeLists.txt` (raiz o `cpp/`) → `cmake -S <dir> -B <dir>/build -DCMAKE_BUILD_TYPE=Release && cmake --build <dir>/build -j` + `ctest --test-dir <dir>/build --output-on-failure || true`
   - `Cargo.toml`     → `cargo build`                     + `cargo test`
   - `package.json`   → `npm run build --if-present`      + `npm test --if-present`
   - `pyproject.toml` / `setup.py` → (sin build)          + `pytest`
4. Si nada se detecta, **preguntar al usuario** que comandos usar antes de continuar.

**Mostrar al usuario los comandos resueltos** y pedir confirmacion antes de seguir. Pasar tanto `BUILD_CMD` como `TEST_CMD` (ya resueltos) al prompt de cada agente.

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

## Comandos build/test del proyecto

BUILD_CMD=<COMANDO_RESUELTO>   # ej: "cmake -S cpp -B cpp/build && cmake --build cpp/build -j"
TEST_CMD=<COMANDO_RESUELTO>    # ej: "ctest --test-dir cpp/build --output-on-failure"

Estos comandos ya estan resueltos por el orquestador (auto-deteccion, override o manifest
.parallel-fix-issues.yml). Usalos tal cual desde la raiz del worktree:

  Bash({ command: "cd $W && eval \"$BUILD_CMD\"", dangerouslyDisableSandbox: true })
  Bash({ command: "cd $W && eval \"$TEST_CMD\"",  dangerouslyDisableSandbox: true })

Si el issue requiere comandos adicionales (ej. `./fn index` tras añadir funciones, `npm install`,
`uv sync`), ejecutalos antes/despues segun corresponda.

## 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 las convenciones del proyecto (pure core / impure shell si aplica)
   - Hacer commits atomicos por bloque logico
   - Prefijos: feat:, fix:, test:, docs:, refactor:, chore:
   - NO hacer commits WIP ni codigo a medias
   - Compilar frecuentemente:
     Bash({ command: "cd $W && eval \"$BUILD_CMD\"", dangerouslyDisableSandbox: true })

3. **Tests obligatorios** (en el lenguaje/framework apropiado del stack):
   - Escribir tests para todo codigo nuevo. Usar el framework convencional del lenguaje:
     Go → testing pkg, C++ → ctest/Catch2/gtest, Rust → cargo test, Python → pytest, etc.
   - Ejecutar:
     Bash({ command: "cd $W && eval \"$TEST_CMD\"", dangerouslyDisableSandbox: true })
   - NO continuar si los tests fallan
   - Si el issue requiere paso de indexacion u otros (ej. `./fn index`, `npm install`), ejecutarlo aqui

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:
- `$BUILD_CMD` — compila sin errores (auto-detectado o pasado por env/arg)
- `$TEST_CMD`  — tests pasan
- Issue movido a `dev/issues/completed/`
- Al menos 1 commit en la branch

Pasar `BUILD_CMD` y `TEST_CMD` como variables de entorno o argumentos posicionales:

```bash
BUILD_CMD="cmake --build cpp/build" TEST_CMD="ctest --test-dir cpp/build" \
  .claude/skills/parallel-fix-issues/scripts/verify-worktree.sh worktrees/<slug>
# o posicionales
.claude/skills/parallel-fix-issues/scripts/verify-worktree.sh worktrees/<slug> "go build ./..." "go test ./..."
```

Si no se pasan, el script auto-detecta el stack (go.mod, CMakeLists.txt, Cargo.toml, package.json, pyproject.toml).

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

**Despues de cada merge**, re-verificar que master compila usando los `BUILD_CMD`/`TEST_CMD` resueltos:

```bash
eval "$BUILD_CMD" && eval "$TEST_CMD"
```

`integrate-worktrees.sh` ya verifica el build post-merge si `BUILD_CMD` esta exportado.
Si falla despues de un merge, PARAR e informar — no continuar con mas 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

- **Stack agnostico**: la skill detecta el stack (Go, C++, Rust, Node, Python) en Fase 3. Si la auto-deteccion falla o el proyecto es exotico, el usuario puede pasar `BUILD_CMD`/`TEST_CMD` por env var o crear `.parallel-fix-issues.yml` en la raiz. Si el proyecto no tiene build/test, esos pasos se omiten con WARN
- **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
```