290 lines
8.4 KiB
Markdown
290 lines
8.4 KiB
Markdown
---
|
|
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/<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:**
|
|
|
|
```markdown
|
|
## 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`:
|
|
|
|
```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:**
|
|
```markdown
|
|
| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |
|
|
```
|
|
|
|
**Issue multi-issue (solo sub-issues, NO archivo principal):**
|
|
```markdown
|
|
| <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:**
|
|
```bash
|
|
cat dev/issues/<NNNN>-<slug>.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/<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
|