agents_and_robots/.claude/rules/fix_issue.md

# Regla: Arreglar/implementar un issue existente

Guia para trabajar en un issue de `dev/issues/` y cerrarlo al terminar.
Usa trunk-based development: siempre trabajar en una rama, nunca en master.

## Inputs — preguntar al usuario si no los da

| Input | Requerido | Ejemplo |
|-------|-----------|---------|
| Numero o nombre del issue | si | `0010`, `0010-access-control` |

## Pasos

### 1. Leer el issue

Abrir `dev/issues/<NNNN>-<slug>.md` y entender:
- **Objetivo**: que se quiere lograr
- **Tareas**: lista de tareas a completar
- **Arquitectura**: archivos afectados, que es puro vs impuro

### 2. Crear rama de trabajo

Ejecutar `/git-branch` con el numero y slug del issue:

```
/git-branch
```

Esto crea la rama `issue/<NNNN>-<slug>` desde master actualizado.
**Nunca trabajar directamente en master.**

### 3. Planificar el trabajo

Crear un plan con `TodoWrite` basado en las tareas del issue. Respetar el orden de fases si el issue las define. **Incluir siempre una tarea de tests.**

### 4. Implementar

- Seguir las tareas del issue en orden
- Respetar **pure core / impure shell**: `pkg/` puro, `shell/` impuro
- Marcar cada tarea como completada en el TodoWrite conforme se avanza
- Compilar frecuentemente: `go build -tags goolm ./...`
- **Commits atómicos por bloque lógico** — no mezclar `feat:` + `test:` en un commit
- **No hacer commits WIP** — nada de "wip", "tmp", "fix fix". Si no hay un bloque lógico completo, no commitear todavía
- Cada commit lleva título corto con prefijo (`feat:`, `fix:`, `test:`, `docs:`, `refactor:`, `chore:`) y cuerpo largo en español explicando qué, por qué e impacto

### 5. Tests — OBLIGATORIO

Toda implementacion debe incluir tests. Antes de cerrar el issue:

- Escribir tests para el codigo nuevo o modificado
- Tests de `pkg/` (puro): tests unitarios directos, sin mocks de I/O
- Tests de `shell/` (impuro): pueden usar mocks/stubs para dependencias externas
- Tests de integracion si el issue lo requiere

Ejecutar:

```bash
go test -tags goolm ./...
```

**No cerrar el issue si los tests no pasan.**

### 6. Feature flags (solo si aplica)

En TBD no existen ramas largas. Para features que no caben en un solo issue/rama, se usan **feature flags**: código completo y testeado que se mergea a master pero desactivado.

**Feature flag ≠ WIP.** Un flag protege código terminado; un WIP es código a medias. Nunca commitear código incompleto.

**Cuándo usar feature flags:**
- Este issue es **parte de una feature multi-issue** (ej: issue 0015a, 0015b, 0015c)
- El cambio tiene **riesgo** y necesita poder desactivarse en producción
- Se quiere **despliegue gradual** (activar para un agente primero, después para todos)

**Cuándo NO usarlos:**
- Issue autocontenido que se completa en una rama → mergear directo, sin flag
- Bug fix, refactor, docs → no necesitan flag

**Al desglosar un issue en sub-issues**, documentar el desglose en el propio archivo del issue:
1. Añadir una seccion `## Desglose multi-issue` en el documento del issue (antes de `## Ejemplo de uso` o al final)
2. Incluir tabla con: sub-issue, rama, alcance, fases cubiertas, estado
3. Incluir checklist de progreso por tarea (marcar `[x]` las completadas, indicar en que sub-issue se hizo)
4. Actualizar el progreso cada vez que se completa una sub-issue

Si aplica, actualizar `dev/feature_flags.json`:

```json
{
  "flags": {
    "nombre-del-flag": {
      "enabled": false,
      "issue": "0020",
      "description": "Descripcion breve de la feature",
      "added": "2026-03-07"
    }
  }
}
```

Incluir el cambio en el commit correspondiente (no crear commit separado solo para flags).

**Flujo para features multi-issue:**

```
Feature grande (ej: 0015 Telegram)
  ├── issue/0015a-telegram-types     → pkg/ types, flag OFF  → merge
  ├── issue/0015b-telegram-client    → shell/ client, flag OFF → merge
  ├── issue/0015c-telegram-listener  → integration, flag OFF → merge
  └── issue/0015d-telegram-enable    → flag ON, cleanup → merge
```

Cada rama es corta, cada merge es seguro, master nunca se rompe.

### 7. Verificar

- [ ] `go build -tags goolm ./...` compila sin errores
- [ ] `go test -tags goolm ./...` pasa sin errores
- [ ] Todas las tareas del issue estan implementadas
- [ ] El codigo respeta pure core / impure shell
- [ ] Se escribieron tests para el codigo nuevo/modificado

### 8. Cerrar el issue — OBLIGATORIO al terminar

Al completar todas las tareas del issue, ejecutar estos pasos:

#### 8.1. Mover el archivo a completed

```bash
mv dev/issues/<NNNN>-<slug>.md dev/issues/completed/
```

#### 8.2. Actualizar el README

En `dev/issues/README.md`, cambiar la fila del issue:
- **Link**: de `[<NNNN>-<slug>.md](<NNNN>-<slug>.md)` a `[<NNNN>-<slug>.md](completed/<NNNN>-<slug>.md)`
- **Estado**: de `pendiente` a `completado`

### 9. Integrar y publicar

Ejecutar `/git-push` para:
1. Commitear los cambios restantes (cierre de issue, README)
2. Hacer merge --no-ff de la rama a master
3. Push a remoto
4. Eliminar la rama local

El commit de merge tendra formato: `merge: issue/<NNNN>-<slug> — <titulo>`

## Reglas

- **Leer antes de actuar**: siempre leer el issue completo antes de empezar a implementar.
- **Siempre en rama**: nunca trabajar en master. Usar `/git-branch` al inicio.
- **Siempre tests**: toda implementacion debe tener tests. No cerrar sin tests.
- **No saltear tareas**: implementar todas las tareas del issue, no solo las faciles.
- **Cerrar siempre**: nunca dejar un issue implementado sin moverlo a `completed/`.
- **Pure core / impure shell**: toda implementacion debe respetar el patron.
- **Compilar con goolm**: siempre usar `-tags goolm` en build y test.
- **Feature flags**: solo cuando el issue es parte de algo mayor. No es obligatorio en cada fix.