repo_Claude/.claude/commands/issues/parallel.md

version, updated, tags

version	updated	tags
1.0.0	2026-03-11	issues parallel development worktree

Command: parallel-issues

Analiza las issues pendientes en dev/issues/ y genera un plan de ejecución paralela (PARALLEL_EXECUTION_ORDER.md) agrupando issues independientes que no tienen conflictos entre sí.

Para el usuario

Cuándo usar este comando

• Cuando quieres identificar qué issues puedes desarrollar en paralelo sin conflictos
• Para acelerar el desarrollo trabajando en múltiples issues simultáneamente
• Antes de iniciar una sesión de desarrollo intensivo con múltiples desarrolladores
• Para planificar el uso de git worktrees con issues independientes

Sintaxis

/issues:parallel [--dry-run]

Ejemplos

Ejemplo 1:

/issues:parallel

Analiza todas las issues pendientes y genera el archivo PARALLEL_EXECUTION_ORDER.md con grupos de issues paralelizables.

Ejemplo 2:

/issues:parallel --dry-run

Muestra el análisis de paralelización en consola sin crear el archivo (útil para vista previa).

Para Claude

Precondiciones

Verificar antes de ejecutar:

• Existe el directorio dev/issues/
• Hay al menos una issue pendiente en formato NNNN-*.md
• El proyecto sigue la estructura funcional (core/shell/app)

Inputs

Se necesitan los siguientes datos. Si no se proporcionan, preguntar al usuario:

• --dry-run (opcional): Si está presente, solo muestra el análisis sin crear archivo

Flujo obligatorio

1. Detectar contexto del proyecto

Determinar si estamos en el proyecto padre (Dataforge) o en un proyecto hijo (workspaces/).

# Verificar si estamos en un proyecto hijo
if [[ "$PWD" == *"/workspaces/"* ]]; then
  PROJECT_TYPE="child"
  PROJECT_NAME=$(basename "$PWD")
else
  PROJECT_TYPE="parent"
  PROJECT_NAME="Dataforge"
fi

echo "Analizando issues en proyecto: $PROJECT_NAME ($PROJECT_TYPE)"

Verificar que existe dev/issues/:

if [ ! -d "dev/issues" ]; then
  echo "Error: No existe el directorio dev/issues/"
  exit 1
fi

2. Listar issues pendientes

Obtener todas las issues que no están marcadas como completadas:

# Listar archivos de issues
ls -1 dev/issues/*.md | grep -E '[0-9]{4}-.*\.md$' | sort

Para cada issue, extraer:

• Número de issue (NNNN)
• Título (del nombre del archivo)
• Estado (revisar si está en el índice como completada)
• Archivos mencionados (parsear el contenido del issue)
• Dependencias explícitas (buscar referencias a #NNNN)

Parseo de archivos mencionados:

Buscar patrones como:

• core/archivo.go
• shell/archivo.go
• app/archivo.go
• Cualquier path con extensión de código

Parseo de dependencias:

Buscar patrones como:

• "depende de #0001"
• "requiere #0002"
• "bloqueado por #0003"

3. Analizar conflictos y dependencias

Para cada par de issues (A, B), determinar si son paralelizables:

Criterios de conflicto (NO paralelizables):

1. Archivos compartidos: Si ambas issues modifican el mismo archivo
2. Dependencias explícitas: Si A menciona "#B" o viceversa
3. Dependencias transitivas: Si A depende de C y B depende de C

Criterios de paralelización (SÍ paralelizables):

1. Archivos disjuntos: Modifican archivos completamente diferentes
2. Capas diferentes: Una toca core/ y otra shell/ sin archivos comunes
3. Sin referencias cruzadas: Ninguna menciona a la otra

Estructura de datos sugerida:

Issue #0001:
  - Archivos: [core/types.go, core/workspace.go]
  - Depende de: []
  - Capa principal: core

Issue #0002:
  - Archivos: [shell/gitea.go, shell/http.go]
  - Depende de: [#0001]
  - Capa principal: shell

Conflictos detectados:
  - #0002 → #0001 (dependencia explícita)

4. Agrupar issues por independencia

Usar algoritmo de agrupación por grafos:

1. Construir grafo de dependencias:

   • Nodos = issues
   • Aristas = conflictos/dependencias

2. Detectar componentes independientes:

   • Issues sin aristas entre sí → mismo grupo paralelo
   • Issues con aristas → grupos secuenciales

3. Priorizar grupos:

   • Grupo 1: Issues sin dependencias (pueden ejecutarse YA)
   • Grupo 2: Issues que dependen solo de Grupo 1
   • Grupo N: Issues que dependen de grupos anteriores

Algoritmo simple:

Grupo_actual = 1
Issues_restantes = todas las issues pendientes
Issues_completadas = []

while Issues_restantes no está vacío:
  Grupo[Grupo_actual] = []

  for issue in Issues_restantes:
    tiene_conflictos = false

    # Verificar conflictos con issues ya en el grupo actual
    for otra in Grupo[Grupo_actual]:
      if conflicto(issue, otra):
        tiene_conflictos = true
        break

    # Verificar dependencias no resueltas
    for dep in issue.dependencias:
      if dep not in Issues_completadas:
        tiene_conflictos = true
        break

    if not tiene_conflictos:
      Grupo[Grupo_actual].append(issue)

  # Si no pudimos agregar ninguna issue al grupo, hay dependencias circulares
  if Grupo[Grupo_actual] está vacío:
    ERROR: "Dependencias circulares detectadas"
    break

  # Marcar issues del grupo como completadas para próxima iteración
  Issues_completadas += Grupo[Grupo_actual]
  Issues_restantes -= Grupo[Grupo_actual]
  Grupo_actual++

5. Estimar tiempos de desarrollo

Para cada issue, calcular complejidad basada en:

Factores:

1. Cantidad de archivos:

   • 1-2 archivos = Simple (1-2 horas)
   • 3-5 archivos = Moderada (2-4 horas)
   • 6+ archivos = Compleja (4-8 horas)

2. Capa afectada:

   • Solo core/ = Moderada (requiere tests extensivos)
   • Solo shell/ = Alta (I/O, manejo de errores)
   • app/ = Baja (orquestación)
   • Múltiples capas = Alta (integración compleja)

3. Palabras clave en descripción:

   • "refactor", "reestructurar" = +50% tiempo
   • "nuevo", "implementar" = tiempo base
   • "fix", "corregir" = -30% tiempo
   • "documentar" = tiempo muy bajo

Estimación por grupo:

• Tiempo de grupo = MAX(tiempos individuales) ← porque se ejecutan en paralelo
• Tiempo total = SUM(tiempos de grupos) ← porque los grupos son secuenciales

6. Generar archivo PARALLEL_EXECUTION_ORDER.md

Crear el archivo con la siguiente estructura:

# Plan de Ejecución Paralela

**Proyecto:** {{PROJECT_NAME}}
**Fecha de análisis:** {{FECHA}}
**Issues analizadas:** {{TOTAL_ISSUES}}
**Grupos paralelos:** {{TOTAL_GRUPOS}}

---

## Grupo 1: Issues Independientes (ejecutar en paralelo)

### Issue #0003 - Implementar shell/gitea.go
- **Archivos afectados:**
  - `shell/gitea.go`
  - `shell/gitea_test.go`
- **Capa:** shell
- **Complejidad:** Moderada
- **Tiempo estimado:** 3 horas
- **Dependencias:** Ninguna
- **Worktree sugerido:** `worktrees/issue-0003`
- **Branch sugerida:** `quick/issues:fix-issue-0003`

### Issue #0006 - Añadir logging estructurado
- **Archivos afectados:**
  - `shell/logger.go`
  - `app/main.go`
- **Capa:** shell, app
- **Complejidad:** Simple
- **Tiempo estimado:** 2 horas
- **Dependencias:** Ninguna
- **Worktree sugerido:** `worktrees/issue-0006`
- **Branch sugerida:** `quick/issues:fix-issue-0006`

### Issue #0008 - Documentación de módulos
- **Archivos afectados:**
  - `README.md`
  - `docs/architecture.md`
- **Capa:** docs
- **Complejidad:** Simple
- **Tiempo estimado:** 1.5 horas
- **Dependencias:** Ninguna
- **Worktree sugerido:** `worktrees/issue-0008`
- **Branch sugerida:** `quick/issues:fix-issue-0008`

**Tiempo estimado del grupo:** 3 horas (máximo en paralelo)

---

## Grupo 2: Issues Dependientes (ejecutar después de Grupo 1)

### Issue #0004 - Implementar app/orchestrator.go
- **Archivos afectados:**
  - `app/orchestrator.go`
  - `app/orchestrator_test.go`
- **Capa:** app
- **Complejidad:** Alta
- **Tiempo estimado:** 5 horas
- **Dependencias:**
  - `#0003` (requiere shell/gitea.go)
- **Worktree sugerido:** `worktrees/issue-0004`
- **Branch sugerida:** `quick/issues:fix-issue-0004`

**Tiempo estimado del grupo:** 5 horas

---

## Grupo 3: Issues Finales

### Issue #0005 - Integración completa
- **Archivos afectados:**
  - `app/main.go`
  - `cmd/dataforge/main.go`
- **Capa:** app
- **Complejidad:** Moderada
- **Tiempo estimado:** 3 horas
- **Dependencias:**
  - `#0004` (requiere orchestrator)
- **Worktree sugerido:** `worktrees/issue-0005`
- **Branch sugerida:** `quick/issues:fix-issue-0005`

**Tiempo estimado del grupo:** 3 horas

---

## Conflictos Detectados

### Conflictos por archivos compartidos:
- `#0002` y `#0003`: ambos modifican `core/types.go`
  - **Solución:** Ejecutar secuencialmente (están en grupos diferentes)

### Dependencias explícitas:
- `#0004` depende de `#0003`
- `#0005` depende de `#0004`

### Advertencias:
- Ninguna circular detectada ✓

---

## Resumen

| Métrica | Valor |
|---------|-------|
| Issues totales | 8 |
| Issues en Grupo 1 (paralelas) | 3 |
| Issues secuenciales | 5 |
| Grupos paralelos | 3 |
| Tiempo total secuencial | 28 horas |
| Tiempo total paralelo | 11 horas |
| **Ahorro de tiempo** | **61%** |

---

## Recomendaciones

1. **Ejecutar Grupo 1 en paralelo:** Usar git worktrees para trabajar en las 3 issues simultáneamente
2. **Esperar a Grupo 2:** No iniciar #0004 hasta que #0003 esté mergeada
3. **Validar integraciones:** Después de cada grupo, ejecutar tests completos
4. **Monitoring:** Si encuentras nuevas dependencias durante desarrollo, actualiza el plan

---

## Comandos para Setup de Worktrees

```bash
# Grupo 1 - Crear worktrees para issues paralelas
git worktree add worktrees/issue-0003 -b quick/issues:fix-issue-0003
git worktree add worktrees/issue-0006 -b quick/issues:fix-issue-0006
git worktree add worktrees/issue-0008 -b quick/issues:fix-issue-0008

# Ejecutar /issues:fix-issue en cada worktree (manual)
# cd worktrees/issue-0003 && /issues:fix-issue 0003
# cd worktrees/issue-0006 && /issues:fix-issue 0006
# cd worktrees/issue-0008 && /issues:fix-issue 0008

# Después de mergear Grupo 1, crear worktree para Grupo 2
git worktree add worktrees/issue-0004 -b quick/issues:fix-issue-0004

# Limpiar worktrees después de merge
git worktree remove worktrees/issue-0003
git worktree remove worktrees/issue-0006
git worktree remove worktrees/issue-0008

**Notas importantes:**

- Usar formato markdown claro y estructurado
- Incluir tabla de resumen con métricas
- Calcular ahorro de tiempo (tiempo secuencial vs paralelo)
- Sugerir comandos de worktree para facilitar setup
- Documentar advertencias y conflictos detectados

#### 7. Mostrar resultado

Si se ejecutó con `--dry-run`:
- Mostrar todo el contenido en consola
- NO crear archivo
- Terminar aquí

Si se ejecutó sin flags:
- Crear archivo `PARALLEL_EXECUTION_ORDER.md`
- Mostrar resumen en consola

```bash
cat PARALLEL_EXECUTION_ORDER.md

Verificación final

# Verificar que el archivo fue creado
ls -lh PARALLEL_EXECUTION_ORDER.md

# Contar grupos generados
grep -c "^## Grupo" PARALLEL_EXECUTION_ORDER.md

Informar al usuario:

✓ Plan de ejecución paralela generado

Archivo: PARALLEL_EXECUTION_ORDER.md

Resumen:
- Issues analizadas: {{N}}
- Grupos paralelos: {{M}}
- Ahorro estimado: {{X}}%

Próximos pasos:
1. Revisar el plan generado
2. Crear worktrees para Grupo 1
3. Ejecutar /issues:fix-issue en cada worktree
4. Mergear y continuar con siguientes grupos

Convenciones

• Nombres de grupo: "Grupo N" donde N empieza en 1
• Worktrees sugeridos: Siempre bajo worktrees/issue-NNNN
• Branches sugeridas: Formato quick/issues:fix-issue-NNNN
• Estimación de tiempo: En horas, redondeado a .5 (ej: 2.5h, 3h, 4.5h)
• Conflictos: Documentar TODOS los conflictos detectados aunque estén resueltos en el plan

Troubleshooting

Error: "No se encontraron issues pendientes"

Causa: No hay archivos .md en dev/issues/ o todos están marcados como completados

Solución:

# Verificar issues existentes
ls -1 dev/issues/*.md

# Verificar índice de issues completadas
cat dev/issues/README.md

Error: "Dependencias circulares detectadas"

Causa: Las issues tienen dependencias que forman un ciclo (A→B→C→A)

Solución:

1. Revisar manualmente las dependencias en los archivos de issues
2. Identificar el ciclo
3. Romper una de las dependencias refactorizando el alcance de una issue
4. Re-ejecutar el comando

Warning: "Múltiples issues modifican el mismo archivo"

Causa: Varias issues tocan el mismo archivo pero no tienen dependencias explícitas

Solución:

1. El algoritmo las colocará en grupos secuenciales automáticamente
2. Considerar refactorizar las issues para que sean más granulares
3. O agregar dependencias explícitas si hay un orden lógico

Reglas críticas

• NUNCA ejecutar issues en paralelo si comparten archivos - causará conflictos de merge
• SIEMPRE respetar dependencias explícitas - aunque no compartan archivos
• NUNCA asumir independencia sin analizar el contenido - leer cada issue completamente
• SIEMPRE calcular el tiempo del grupo como MAX(tiempos) - no como suma (son paralelas)
• NUNCA crear el archivo si hay errores en el análisis - informar al usuario y terminar
• SIEMPRE documentar conflictos detectados - transparencia total en el análisis