From f6d049127d0b2d0c8a1975f36a2fb43d02eb3c48 Mon Sep 17 00:00:00 2001 From: Enmanuel Date: Sun, 8 Mar 2026 13:57:29 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20a=C3=B1adir=20comando=20/create-issue?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nuevo comando slash que automatiza la creacion de issues en dev/issues/. Sigue estrictamente la regla create_issue.md, evalua el tamaño del issue para desglosar en sub-issues con feature flags si es necesario, y registra todo en el README automaticamente. Co-Authored-By: Claude Opus 4.6 --- .claude/commands/create-issue.md | 154 +++++++++++++++++++++++++++++++ 1 file changed, 154 insertions(+) create mode 100644 .claude/commands/create-issue.md diff --git a/.claude/commands/create-issue.md b/.claude/commands/create-issue.md new file mode 100644 index 0000000..5b390d5 --- /dev/null +++ b/.claude/commands/create-issue.md @@ -0,0 +1,154 @@ +# 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.). + +```bash +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/-.md` +- Seguir directo al paso 4 + +**Si es un issue grande** (necesita desglose): +- Crear el issue principal `dev/issues/-.md` con seccion `## Desglose multi-issue` +- Crear cada sub-issue como `dev/issues/-.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: + +```markdown +## Desglose multi-issue + +Este issue se implementa en sub-issues independientes, cada uno en su propia rama. + +| Sub-issue | Rama | Alcance | Estado | +|-----------|------|---------|--------| +| a- | issue/a- | | pendiente | +| b- | issue/b- | | pendiente | +| ... + +### Feature flag + +Nombre: `` +Se activa en el ultimo sub-issue cuando todo esta integrado. + +### Progreso por tarea + +- [ ] **1.1** — sub-issue a +- [ ] **1.2** — sub-issue a +- [ ] **2.1** — sub-issue 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`: + +```json +{ + "": { + "enabled": false, + "issue": "", + "description": "", + "added": "" + } +} +``` + +### 7. Actualizar el indice + +En `dev/issues/README.md`, agregar filas al final de la tabla. + +**Issue simple:** +```markdown +| | | [-.md](-.md) | pendiente | +``` + +**Issue multi-issue (agregar fila por cada sub-issue tambien):** +```markdown +| | | [-.md](-.md) | pendiente | +| a | (parte a) | [a-.md](a-.md) | pendiente | +| b | (parte b) | [b-.md](b-.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 ` (o `/fix-issue a`, `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