---
version: 1.0.0
updated: 2026-03-11
tags: [issues, planning, order]
---

# Command: sort-issues

Analiza las issues en `dev/issues/` y genera un archivo `dev/EXECUTION_ORDER.md` con el orden óptimo de ejecución basado en dependencias y relaciones entre issues.

## Para el usuario

### Cuándo usar este comando

- Cuando quieres planificar el orden de trabajo de las issues disponibles
- Después de crear nuevas issues y necesitas priorizar
- Antes de empezar una fase de desarrollo para entender el flujo crítico
- Cuando hay cambios en dependencias entre issues

### Sintaxis

```bash
/issues:sort
```

### Ejemplos

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

Analiza todas las issues en `dev/issues/` y crea `dev/EXECUTION_ORDER.md` con el orden recomendado.

**Ejemplo 2:**
```bash
/issues:sort
```

Actualiza el orden de ejecución después de completar algunas issues.

## Para Claude

### Precondiciones

Verificar antes de ejecutar:

- [ ] Directorio `dev/issues/` existe
- [ ] Hay archivos `.md` en `dev/issues/` (al menos uno)
- [ ] Tienes permisos de escritura en `dev/`

### Inputs

No requiere inputs del usuario. Analiza automáticamente todas las issues en `dev/issues/`.

### Flujo obligatorio

#### 1. Listar todas las issues disponibles

Obtener lista de todas las issues en `dev/issues/`:

```bash
ls -1 dev/issues/*.md | grep -E '[0-9]{4}-.*\.md$' | sort
```

Excluir `README.md` y otros archivos que no sean issues numeradas.

#### 2. Analizar cada issue para extraer dependencias

Para cada archivo de issue encontrado:

1. Leer el contenido completo del archivo
2. Buscar secciones que indiquen dependencias:
   - "Depends on", "Requires", "Prerequisites"
   - Referencias a otras issues (#NNNN)
   - Menciones en "Critical Path" o "Execution Order"
3. Identificar el tipo de issue (foundational, feature, infrastructure)
4. Analizar complejidad y alcance

**Patrones a buscar:**
- `#0001`, `issue #0001`, `0001-nombre`
- "must be completed before"
- "blocks", "required for"
- "depends on"

#### 3. Construir grafo de dependencias

Crear una representación mental del grafo:

- Nodos: cada issue
- Aristas: relaciones de dependencia (A → B significa "A debe completarse antes que B")
- Identificar:
  - Issues raíz (sin dependencias)
  - Issues bloqueadas (muchas dependencias)
  - Camino crítico
  - Issues paralelas (pueden ejecutarse simultáneamente)

#### 4. Calcular orden óptimo

Aplicar ordenamiento topológico considerando:

1. **Prioridad primaria:** Dependencias explícitas (hard dependencies)
2. **Prioridad secundaria:** Dependencias implícitas (una issue menciona conceptos de otra)
3. **Prioridad terciaria:** Orden lógico (fundamentos antes que features)
4. **Desempate:** Número de issue (menor primero)

Estrategia:
- Agrupar issues por "capas" (todas las de una capa pueden ejecutarse en paralelo)
- Identificar camino crítico explícitamente
- Sugerir paralelización cuando sea posible

#### 5. Generar archivo EXECUTION_ORDER.md

Crear archivo con formato muy sencillo:

```markdown
# Execution Order for Issues

Last updated: YYYY-MM-DD

## Recommended Order

1. #0001 - <nombre> — <razón breve>
2. #0002 - <nombre> — <razón breve>
3. #0003 - <nombre> — <razón breve>
...

## Critical Path

Issues que bloquean otras:
- #0001 → #0002, #0003
- #0005 → #0008

## Parallelizable Groups

### Group 1 (after #0001)
- #0002
- #0003

### Group 2 (after #0005)
- #0006
- #0007

## Notes

- <Nota importante sobre el orden>
- <Consideraciones especiales>
```

Escribir el archivo:

```bash
cat > dev/EXECUTION_ORDER.md << 'EOF'
<contenido-generado>
EOF
```

#### 6. Mostrar resumen al usuario

```
✓ Archivo dev/EXECUTION_ORDER.md creado

Issues analizadas: N
Camino crítico identificado: #XXXX → #YYYY → #ZZZZ
Grupos paralelizables: M

Próxima issue recomendada: #NNNN - <nombre>
```

### Verificación final

```bash
cat dev/EXECUTION_ORDER.md
```

Informar al usuario:

```
✓ Orden de ejecución de issues generado en dev/EXECUTION_ORDER.md

Próximos pasos:
  1. Revisar el orden propuesto
  2. Comenzar con la primera issue del orden
  3. Actualizar con /issues:sort cuando completes issues o agregues nuevas
```

## Convenciones

- **Formato simple**: Solo líneas numeradas con issues y razón breve
- **Razones concisas**: Máximo 1 línea explicando por qué ese orden
- **Actualización frecuente**: Re-ejecutar después de completar issues
- **Nombres consistentes**: Usar formato `#NNNN - nombre-descriptivo`

## Troubleshooting

### Error: "No issues found"

**Causa:** No hay archivos `.md` con formato de issue en `dev/issues/`

**Solución:**
```bash
ls -la dev/issues/
# Verificar que existan archivos NNNN-nombre.md
```

### Error: "Circular dependency detected"

**Causa:** Issue A depende de B, y B depende de A (ciclo)

**Solución:**
1. Revisar manualmente las issues involucradas
2. Romper la dependencia circular
3. Actualizar la documentación de al menos una issue
4. Re-ejecutar /issues:sort

### Error: "Permission denied writing to dev/"

**Causa:** No tienes permisos de escritura en el directorio `dev/`

**Solución:**
```bash
chmod u+w dev/
# O verificar permisos del directorio
ls -ld dev/
```

## Reglas críticas

- **No modificar issues**: Solo leer, nunca modificar los archivos de issues
- **Análisis exhaustivo**: Leer TODAS las issues antes de generar el orden
- **Formato consistente**: Mantener estructura simple y legible
- **Actualización atómica**: Sobrescribir el archivo completo, no editar parcialmente
- **Documentar razonamiento**: Cada issue en el orden debe tener su justificación breve