---
version: 1.0.0
updated: 2026-03-11
tags: [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

```bash
/issues:parallel [--dry-run]
```

### Ejemplos

**Ejemplo 1:**
```bash
/issues:parallel
```

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

**Ejemplo 2:**
```bash
/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/).

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

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

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

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

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