repo_Claude/.claude/commands/issues/create-issue.md

version, updated, tags

version	updated	tags
2.0.0	2026-03-11	issues documentation workflow

Command: create-issue

Crea un issue nuevo en dev/issues/ con confirmación del usuario. Si el issue es grande, lo desglosa automáticamente en sub-issues con feature flags.

Para el usuario

Cuándo usar este comando

Usar cuando necesites documentar una nueva tarea, feature o fix antes de implementarlo. El comando crea la estructura completa del issue y pide confirmación antes de integrarlo.

Sintaxis

/issues:create-issue

El comando preguntará interactivamente por los datos necesarios.

Ejemplos

Ejemplo 1: Issue simple

/issues:create-issue
# Título: Hot reload de configuración
# Descripción: Permitir recargar config sin reiniciar

Crea dev/issues/NNNN-hot-reload.md y pide confirmación.

Ejemplo 2: Issue multi-parte

/issues:create-issue
# Título: Integración completa con Telegram
# Descripción: Cliente, listener, y handlers para Telegram

Detecta que es grande y crea sub-issues (NNNN a, b, c...) con feature flag.

Para Claude

Precondiciones

Verificar antes de ejecutar:

• Directorio dev/issues/ existe
• Archivo dev/issues/README.md existe
• Template .claude/templates/issue.md existe

Inputs

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

• titulo: título corto y descriptivo (ej: "Hot reload de configuración")
• descripcion: objetivo/descripción de lo que se quiere lograr
• dependencias (opcional): issues de los que depende (ej: "Requiere issue 0010")

Flujo obligatorio

1. Determinar el número del issue

{{include: issue-numbering}}

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

El próximo issue será: número_más_alto + 1 (formato 4 dígitos)

2. Generar slug

A partir del título:

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

3. Evaluar tamaño del issue

Analizar el alcance y determinar si cabe en una sola rama corta (horas).

Criterios para desglosar en sub-issues:

• Toca más de 2 capas del patrón (core/ + shell/ + app/)
• Requiere más de ~3 fases de implementación
• El usuario lo indica explícitamente
• La descripción implica múltiples componentes independientes

Si es issue simple:

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

Si es issue grande:

• NO crear archivo principal (no se necesita dev/issues/<NNNN>-<slug>.md)
• Crear SOLO sub-issues dev/issues/<NNNN><letra>-<sub-slug>.md
• Cada sub-issue debe ser autocontenido con toda la información necesaria
• Agregar feature flag para coordinar sub-issues
• Continuar al paso 4

4. Crear el issue desde el template

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

• Metadata: ID, estado (pendiente), prioridad, tipo
• Objetivo: 1-3 frases claras
• Contexto: qué existe, qué falta, dependencias
• Arquitectura: archivos afectados (marcar NEW los nuevos)
• Patrón pure/impure: qué va en core/ vs shell/ vs app/
• Tareas: fases con tareas numeradas (1.1, 1.2, etc.)
• Ejemplo de uso: flujo concreto con código
• Decisiones de diseño: justificaciones clave
• Prerequisitos: qué debe existir antes
• Riesgos: problemas potenciales y mitigación
• Criterios de aceptación: checklist de completitud

5. Para issues multi-issue — contenido en sub-issues

Ya que NO se crea archivo principal, cada sub-issue debe ser autocontenido:

En cada sub-issue incluir:

• Objetivo específico del sub-issue
• Contexto: parte de qué feature mayor (ej: "Parte 1 de 4 del sistema de distribución .claude")
• Relación con otros sub-issues (dependencias, orden sugerido)
• Tareas específicas de este sub-issue
• Referencia al feature flag compartido

En el PRIMER sub-issue (NNNNa) agregar tabla de coordinación:

## Coordinación multi-issue

Este issue es parte de una implementación dividida en sub-issues:

| Sub-issue | Alcance | Estado |
|-----------|---------|--------|
| <NNNN>a-<slug> (este) | <qué cubre> | pendiente |
| <NNNN>b-<slug> | <qué cubre> | pendiente |
| <NNNN>c-<slug> | <qué cubre> | pendiente |

### Feature flag compartido

Nombre: `<nombre-del-flag>`
Se activa en el último sub-issue (<NNNN>d) cuando todo está integrado.

6. Registrar feature flag (solo multi-issue)

Actualizar dev/feature_flags.json:

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

7. Actualizar el índice

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 (solo sub-issues, NO archivo principal):

| <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 |
| <N>c | <Titulo> (parte c) | [<NNNN>c-<slug>.md](<NNNN>c-<slug>.md) | pendiente |

⚠️ IMPORTANTE: NO agregar fila para <NNNN>-<slug>.md ya que este archivo no se crea.

8. Mostrar el issue creado y confirmar

{{include: ask-user-confirm}}

Mostrar al usuario el contenido completo:

Issue simple:

cat dev/issues/<NNNN>-<slug>.md

Issue multi-issue: Mostrar resumen de sub-issues creados y el contenido del primer sub-issue:

echo "Sub-issues creados:"
ls -1 dev/issues/<NNNN>*.md
echo -e "\n=== Contenido del primer sub-issue (<NNNN>a) ==="
cat dev/issues/<NNNN>a-<slug>.md

Pausar y preguntar:

Issue simple:

Issue creado: <NNNN>-<slug>

¿Te parece bien el issue?
- Si es correcto: se hará commit y push automáticamente
- Si necesitas ajustes: puedes editarlo manualmente antes

Issue multi-issue:

Issues creados: <NNNN>a, <NNNN>b, <NNNN>c (sin archivo principal)

¿Te parecen bien los sub-issues?
- Si es correcto: se hará commit y push automáticamente
- Si necesitas ajustes: puedes editarlos manualmente antes

Esperar respuesta del usuario:

• Si responde afirmativo → continuar al paso 9
• Si responde negativo → STOP: "Edita los archivos y ejecuta /git:push cuando estés listo"

9. Ejecutar /git:push automáticamente

Una vez confirmado, ejecutar /git:push para:

1. Crear rama quick/issues:create-issue-<NNNN> automáticamente
2. Commitear archivos (dev/issues/<NNNN>*.md, dev/issues/README.md, dev/feature_flags.json si aplica)
3. Mergear a master con --no-ff
4. Push a remoto
5. Limpiar rama local

Verificación final

Informar al usuario:

✓ Issue <NNNN>-<slug> creado e integrado a master

Tipo: [issue simple / issue multi-issue con N sub-issues]
Rama: quick/issues:create-issue-<NNNN> (mergeada y limpiada)

Para implementar:
  /issues:fix-issue <NNNN>        [si es simple]
  /issues:fix-issue <NNNN>a       [si es multi-issue, implementar sub-issues en orden]

Convenciones

• Numeración continua: nunca saltar números ni reusar
• Estado inicial: siempre pendiente
• Issues cortos: máximo horas de implementación por rama
• Sub-issues autocontenidos: cada uno debe compilar y pasar tests independientemente
• Feature flags != WIP: protegen código terminado, no código a medias

Troubleshooting

Error: "Template file not found"

Causa: No existe .claude/templates/issue.md

Solución: Crear el template desde el proyecto base o consultar documentación.

Error: "Cannot determine next issue number"

Causa: No hay issues previos en dev/issues/ o dev/issues/completed/

Solución: Comenzar con 0001 como primer issue.

Advertencia: "Issue número ya existe"

Causa: Ya existe un archivo con ese número.

Solución: Verificar manualmente y usar el siguiente número disponible.

Reglas críticas

• Seguir template estrictamente: no omitir secciones
• Patrón pure core / impure shell: toda feature debe explicar qué va en core/ vs shell/
• Tareas atómicas: cada tarea debe ser implementable independientemente
• Numeración sin gaps: siempre consecutiva
• Confirmación obligatoria: siempre esperar aprobación del usuario antes de integrar
• Issues grandes: desglosar en sub-issues con feature flags, nunca ramas de larga duración