# Regla: Crear un nuevo issue

Guia para crear issues de features, mejoras o bugs en `dev/issues/`.

## Inputs — preguntar al usuario si no los da

| Input | Requerido | Ejemplo |
|-------|-----------|---------|
| Titulo | si | "Hot reload de configuracion" |
| Descripcion/objetivo | si | "Recargar config sin reiniciar el agente" |
| Dependencias | no | "Requiere issue 0010" |

## Pasos

### 1. Determinar el numero del issue

Buscar el numero mas alto en `dev/issues/` (incluyendo `completed/`) y usar el siguiente. Formato: 4 digitos con ceros a la izquierda (`0019`, `0020`, etc.).

### 2. Crear el archivo desde el template

Copiar `.claude/templates/issue.md` a `dev/issues/<NNNN>-<slug>.md`.

El slug debe ser:
- Lowercase
- Palabras separadas por guiones
- Conciso (2-4 palabras)
- Ejemplo: `0019-hot-reload.md`

### 3. Rellenar el template

Completar todas las secciones del template:

- **Objetivo**: 1-3 frases claras de que se quiere lograr
- **Contexto**: que existe, que falta, dependencias
- **Arquitectura**: archivos afectados, marcar `NEW` los nuevos. Incluir como se respeta pure core / impure shell
- **Tareas**: desglosar en fases con tareas numeradas (`1.1`, `1.2`, etc.). Cada tarea debe ser concreta y verificable. Incluir siempre una fase de tests y una de cleanup/docs
- **Ejemplo de uso**: flujo concreto mostrando la feature funcionando
- **Decisiones de diseno**: justificar las decisiones clave
- **Prerequisitos**: que debe estar implementado antes
- **Riesgos**: problemas potenciales y mitigacion

### 4. Actualizar el indice

Agregar una fila al final de la tabla en `dev/issues/README.md`:

```markdown
| <N> | <Titulo> | [<NNNN>-<slug>.md](<NNNN>-<slug>.md) | pendiente |
```

## Features multi-issue (feature flags)

Si la feature es demasiado grande para completarse en una sola rama corta (horas), **desglosar en sub-issues** que se implementan y mergean por separado. Cada sub-issue debe:

1. Ser autocontenido: compilar, pasar tests, no romper master
2. Proteger el codigo parcial con un **feature flag** en `dev/feature_flags.json` (desactivado hasta que todo este listo)
3. Usar numeracion con sufijo letra: `0015a`, `0015b`, etc.

**Ejemplo:**

```
0015a-telegram-types       → tipos puros en pkg/
0015b-telegram-client      → cliente en shell/
0015c-telegram-listener    → integracion en agents/
0015d-telegram-enable      → activar flag, cleanup
```

Indicar en el issue principal que es multi-issue y listar los sub-issues planificados.

**Feature flag ≠ WIP.** Un flag protege codigo terminado y testeado; un WIP es codigo a medias. Nunca commitear codigo incompleto a master.

## Reglas

- **Patron pure core / impure shell**: toda feature debe explicar que va en `pkg/` (puro) vs `shell/` (impuro).
- **Tareas atomicas**: cada tarea debe ser implementable de forma independiente.
- **Numeracion continua**: nunca reusar numeros de issues eliminados.
- **Estado**: los issues nuevos siempre empiezan como `pendiente`.
- **Completados**: cuando se termine un issue, moverlo a `dev/issues/completed/` y actualizar el README.
- **Issues grandes**: si no cabe en una rama corta, desglosar en sub-issues con feature flags.

## Verificacion

- [ ] Archivo creado en `dev/issues/<NNNN>-<slug>.md`
- [ ] Todas las secciones del template rellenadas
- [ ] Fila agregada en `dev/issues/README.md`
- [ ] Numero de issue es consecutivo (no hay saltos ni duplicados)
- [ ] Si es multi-issue: sub-issues planificados y feature flag definido