482 lines
13 KiB
Markdown
482 lines
13 KiB
Markdown
---
|
|
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
|