Añadidos arhcivos basicos de repos
This commit is contained in:
@@ -0,0 +1,289 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user