agents_and_robots/.claude/commands/create-issue.md

Command: create issue

Crea un issue nuevo en dev/issues/ siguiendo estrictamente la regla create_issue.md. Si el issue es grande, lo desglosa automaticamente en sub-issues con feature flags.

Inputs

Se necesitan los datos del issue. Si no se proporcionan, preguntar.

• titulo: titulo corto y descriptivo (ej: "Hot reload de configuracion")
• descripcion: objetivo/descripcion de lo que se quiere lograr
• dependencias (opcional): issues de los que depende (ej: "Requiere issue 0010")

Flujo obligatorio

1. Determinar el numero del issue

Buscar el numero mas alto en dev/issues/ y dev/issues/completed/ y usar el siguiente. Formato: 4 digitos con ceros a la izquierda (0023, 0024, etc.).

ls dev/issues/ dev/issues/completed/ | grep -oP '^\d{4}' | sort -rn | head -1

2. Generar slug

A partir del titulo:

• Lowercase
• Palabras separadas por guiones
• Conciso (2-4 palabras)
• Ejemplo: "Hot reload de configuracion" → hot-reload

3. Evaluar tamano del issue

Antes de escribir el issue, analizar el alcance y determinar si cabe en una sola rama corta (horas).

Criterios para desglosar en sub-issues:

• Toca mas de 2 capas del patron (pkg/ + shell/ + agents/ + tools/)
• Requiere mas de ~3 fases de implementacion
• El usuario lo indica explicitamente
• La descripcion implica multiples componentes independientes

Si es un issue simple (cabe en una rama):

• Crear un solo archivo dev/issues/<NNNN>-<slug>.md
• Seguir directo al paso 4

Si es un issue grande (necesita desglose):

• Crear el issue principal dev/issues/<NNNN>-<slug>.md con seccion ## Desglose multi-issue
• Crear cada sub-issue como dev/issues/<NNNN><letra>-<sub-slug>.md (ej: 0023a-types, 0023b-client)
• Cada sub-issue es autocontenido: debe compilar, pasar tests, no romper master
• Agregar feature flag en la descripcion del issue principal
• Registrar todos los sub-issues en dev/issues/README.md

4. Crear el issue desde el template

Copiar .claude/templates/issue.md y rellenar todas las secciones:

• Objetivo: 1-3 frases claras
• Contexto: que existe, que falta, dependencias
• Arquitectura: archivos afectados (marcar NEW los nuevos). Explicar que va en pkg/ (puro) vs shell/ (impuro)
• Tareas: fases con tareas numeradas (1.1, 1.2, etc.). Cada tarea concreta y verificable. Siempre incluir fase de tests y fase de cleanup/docs
• Ejemplo de uso: flujo concreto
• Decisiones de diseno: justificaciones clave
• Prerequisitos: que debe existir antes
• Riesgos: problemas potenciales y mitigacion

5. Para issues multi-issue — contenido adicional

En el issue principal, agregar despues de las tareas:

## Desglose multi-issue

Este issue se implementa en sub-issues independientes, cada uno en su propia rama.

| Sub-issue | Rama | Alcance | Estado |
|-----------|------|---------|--------|
| <NNNN>a-<slug> | issue/<NNNN>a-<slug> | <que cubre> | pendiente |
| <NNNN>b-<slug> | issue/<NNNN>b-<slug> | <que cubre> | pendiente |
| ...

### Feature flag

Nombre: `<nombre-del-flag>`
Se activa en el ultimo sub-issue cuando todo esta integrado.

### Progreso por tarea

- [ ] **1.1** <tarea> — sub-issue <NNNN>a
- [ ] **1.2** <tarea> — sub-issue <NNNN>a
- [ ] **2.1** <tarea> — sub-issue <NNNN>b
...

Cada sub-issue individual debe tener su propio archivo con:

• Objetivo especifico del sub-issue
• Tareas que le corresponden del issue principal
• Nota de que es parte de un issue mayor

6. Registrar feature flag (solo multi-issue)

Actualizar dev/feature_flags.json:

{
  "<nombre-del-flag>": {
    "enabled": false,
    "issue": "<NNNN>",
    "description": "<descripcion breve>",
    "added": "<YYYY-MM-DD>"
  }
}

7. Actualizar el indice

En dev/issues/README.md, agregar filas al final de la tabla.

Issue simple:

| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |

Issue multi-issue (agregar fila por cada sub-issue tambien):

| <N>  | <Titulo>           | [<NNNN>-<slug>.md](<NNNN>-<slug>.md)   | pendiente |
| <N>a | <Titulo> (parte a) | [<NNNN>a-<slug>.md](<NNNN>a-<slug>.md) | pendiente |
| <N>b | <Titulo> (parte b) | [<NNNN>b-<slug>.md](<NNNN>b-<slug>.md) | pendiente |

8. Verificar

• Archivo(s) creado(s) en dev/issues/
• Todas las secciones del template rellenadas
• Fila(s) agregada(s) en dev/issues/README.md
• Numero de issue es consecutivo (sin saltos ni duplicados)
• Si es multi-issue: sub-issues creados, feature flag en dev/feature_flags.json, seccion de desglose en issue principal

9. Reportar al usuario

Mostrar resumen:

• Numero y titulo del issue
• Si fue desglosado: listar sub-issues con su alcance
• Recordar: usar /fix-issue <NNNN> (o /fix-issue <NNNN>a, <NNNN>b, etc.) para implementar

Reglas criticas

• Seguir create_issue.md de forma estricta
• Patron pure core / impure shell: toda feature debe explicar que va en pkg/ vs shell/
• Tareas atomicas: cada tarea debe ser implementable de forma independiente
• Numeracion continua: nunca reusar numeros
• Estado: issues nuevos siempre pendiente
• Issues grandes: desglosar en sub-issues con feature flags, nunca dejar una rama abierta por dias
• Feature flag != WIP: un flag protege codigo terminado y testeado, no codigo a medias
• No commitear: este comando solo crea archivos en dev/issues/. No hace commits ni crea ramas