--- version: 2.0.0 updated: 2026-03-11 tags: [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 ```bash /issues:create-issue ``` El comando preguntará interactivamente por los datos necesarios. ### Ejemplos **Ejemplo 1: Issue simple** ```bash /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** ```bash /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}} ```bash 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/-.md` - Continuar al paso 4 **Si es issue grande:** - NO crear archivo principal (no se necesita `dev/issues/-.md`) - Crear SOLO sub-issues `dev/issues/-.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:** ```markdown ## Coordinación multi-issue Este issue es parte de una implementación dividida en sub-issues: | Sub-issue | Alcance | Estado | |-----------|---------|--------| | a- (este) | | pendiente | | b- | | pendiente | | c- | | pendiente | ### Feature flag compartido Nombre: `` Se activa en el último sub-issue (d) cuando todo está integrado. ``` #### 6. Registrar feature flag (solo multi-issue) Actualizar `dev/feature_flags.json`: ```json { "": { "enabled": false, "issue": "", "description": "", "added": "" } } ``` #### 7. Actualizar el índice En `dev/issues/README.md`, agregar filas al final de la tabla. **Issue simple:** ```markdown | | | [-.md](-.md) | pendiente | ``` **Issue multi-issue (solo sub-issues, NO archivo principal):** ```markdown | a | (parte a) | [a-.md](a-.md) | pendiente | | b | (parte b) | [b-.md](b-.md) | pendiente | | c | (parte c) | [c-.md](c-.md) | pendiente | ``` ⚠️ **IMPORTANTE:** NO agregar fila para `-.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:** ```bash cat dev/issues/-.md ``` **Issue multi-issue:** Mostrar resumen de sub-issues creados y el contenido del primer sub-issue: ```bash echo "Sub-issues creados:" ls -1 dev/issues/*.md echo -e "\n=== Contenido del primer sub-issue (a) ===" cat dev/issues/a-.md ``` **Pausar y preguntar:** **Issue simple:** ``` Issue creado: - ¿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: a, b, 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-` automáticamente 2. Commitear archivos (`dev/issues/*.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 - creado e integrado a master Tipo: [issue simple / issue multi-issue con N sub-issues] Rama: quick/issues:create-issue- (mergeada y limpiada) Para implementar: /issues:fix-issue [si es simple] /issues:fix-issue 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