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

   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:

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

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

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

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:

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

• 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