---
version: 2.0.0
updated: 2026-03-11
tags: [issues, implementation, workflow, trunk-based]
---

# Command: fix-issue

Ejecuta de punta a punta el flujo de implementación/cierre de un issue siguiendo **estrictamente** la regla `fix_issue.md`.

## Para el usuario

### Cuándo usar este comando

Usar cuando quieras implementar un issue completo desde inicio hasta fin con confirmación antes de integrar. El comando maneja todo el ciclo: crear rama, implementar, testear, cerrar issue, pedir confirmación, e integrar a master.

### Sintaxis

```bash
/issues:fix-issue <NNNN>
/issues:fix-issue <NNNN>-<slug>
```

### Ejemplos

**Ejemplo 1: Por número**
```bash
/issues:fix-issue 0013
```

Busca `dev/issues/0013-*.md`, implementa todas las tareas, cierra el issue, pide confirmación, e integra.

**Ejemplo 2: Por slug completo**
```bash
/issues:fix-issue 0013-hot-reload
```

Usa exactamente `dev/issues/0013-hot-reload.md`.

## Para Claude

### Precondiciones

Verificar antes de ejecutar:

- [ ] Directorio `dev/issues/` existe
- [ ] Directorio `dev/issues/completed/` existe
- [ ] Archivo `dev/issues/README.md` existe
- [ ] Tests configurados (go test disponible)
- [ ] Working tree limpio

### Inputs

Se necesita el issue objetivo. Si no se proporciona, preguntar:

- `issue`: número o nombre (ej: `0010` o `0010-access-control`)

### Flujo obligatorio

#### 1. Resolver el issue objetivo

**Si viene solo número** (`0010`):
```bash
ls dev/issues/0010-*.md
```

**Si viene slug completo** (`0010-access-control`):
```bash
ls dev/issues/0010-access-control.md
```

**Validaciones:**
- Si no existe en `dev/issues/` → ✗ **STOP**: "Issue no encontrado"
- Si ya está en `dev/issues/completed/` → ✗ **STOP**: "Issue ya completado"

#### 2. Leer completo el issue y extraer información

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

Extraer:
- **Objetivo**: qué se quiere lograr
- **Tareas/fases**: lista completa de pasos
- **Arquitectura**: archivos a crear/modificar
- **Patrón pure/impure**: límites entre core/, shell/, app/
- **Tests requeridos**: criterios de aceptación

#### 3. Crear rama de trabajo (inline)

{{include: git-verify-clean}}

Verificar rama actual:

```bash
git branch --show-current
```

**Si ya estamos en `issue/<NNNN>-<slug>`** que coincide:
- ✓ Continuar directamente a paso 4

**Si estamos en master o cualquier otra rama:**

{{include: git-update-master}}

```bash
git checkout master
git pull --rebase
git checkout -b issue/<NNNN>-<slug>
```

**⚠️ IMPORTANTE:** Nunca trabajar directamente en `master`.

#### 4. Planificar con TodoWrite

Crear plan basado en las tareas del issue:

```markdown
- [ ] Fase 1: <descripción>
  - [ ] Tarea 1.1
  - [ ] Tarea 1.2
- [ ] Fase 2: <descripción>
  - [ ] Tarea 2.1
  - [ ] Tarea 2.2
- [ ] Fase N: Tests y validación
- [ ] Cerrar issue
```

**Principios:**
- Respetar el orden de fases del issue
- Incluir siempre fase de tests
- Marcar progreso al completar cada bloque

#### 5. Implementar el issue completo

**Ejecutar tareas en orden:**

Para cada tarea:
1. Implementar cambios requeridos
2. Seguir patrón **pure core / impure shell**:
   - `core/` → funciones puras, sin side effects
   - `shell/` → I/O, filesystem, network, APIs
   - `app/` → orquestación de core + shell
3. Compilar frecuentemente:
```bash
go build -tags goolm ./...
```
4. Marcar progreso en TodoWrite
5. Crear commits atómicos por bloque lógico (no al final, durante la implementación)

**Commits durante implementación:**
```bash
git add <archivos_del_bloque>
git commit -m "<tipo>: <resumen>" -m "<descripción larga en español>"
```

Tipos: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`, `chore:`

#### 6. Tests obligatorios

{{include: run-tests}}

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

**Casos:**
- Tests **pasan** → ✓ Continuar a paso 7
- Tests **fallan** → ✗ **STOP**: corregir antes de continuar
  ```bash
  go test -v -tags goolm ./...  # Ver detalles
  # Corregir errores
  # Crear commit con fix
  # Re-ejecutar tests
  ```
- No hay tests aplicables → ℹ Indicar al usuario, continuar

**⚠️ CRÍTICO:** No cerrar el issue sin tests pasando.

#### 7. Feature flags (si aplica)

Evaluar si es feature multi-issue o despliegue gradual:

**Si aplica feature flag:**
1. Actualizar `dev/feature_flags.json`:
```json
{
  "<nombre-del-flag>": {
    "enabled": false,  // o true si es el último sub-issue
    "issue": "<NNNN>",
    "description": "<descripción>",
    "updated": "2026-03-11"
  }
}
```

2. Incluir en commit correspondiente (no commit separado solo para flags)

**Si NO aplica:**
- Feature autocontenida que no necesita coordinación
- ✓ Saltar este paso

**⚠️ Recordatorio:** Feature flag ≠ WIP. Los flags protegen código terminado y testeado, no código a medias.

#### 8. Cerrar el issue

Mover issue a completed:

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

Actualizar índice en `dev/issues/README.md`:

Cambiar la línea del issue:
- Link: de `[<NNNN>-<slug>.md](<NNNN>-<slug>.md)` a `[completed/<NNNN>-<slug>.md](completed/<NNNN>-<slug>.md)`
- Estado: de `pendiente` o `en progreso` a `completado`

Crear commit:
```bash
git add dev/issues/completed/<NNNN>-<slug>.md dev/issues/README.md
git commit -m "docs: cerrar issue <NNNN>-<slug>" -m "Issue <NNNN> completado y movido a completed/

Todas las tareas implementadas y tests pasando.
Ready to merge to master."
```

#### 9. Mostrar resumen de cambios y confirmar

{{include: ask-user-confirm}}

**Mostrar al usuario un resumen completo:**

```bash
git status --short
git diff --stat master
git log --oneline master..HEAD
```

**Mostrar tareas completadas del TodoWrite.**

**Pausar y preguntar:**

```
✓ Issue <NNNN>-<slug> completado

Resumen de cambios:
- <N> archivos modificados/creados
- <N> commits realizados
- Tests: [pasando / no aplica]
- Issue movido a completed/

Commits:
- <commit 1>
- <commit 2>
- ...

¿Está todo bien para integrar a master?
- Si es correcto: se hará merge y push automáticamente
- Si necesitas ajustes: puedes hacer cambios adicionales antes
```

**Esperar respuesta del usuario:**
- Si responde **SI** / afirmativo → continuar a paso 10
- Si responde **NO** / necesita cambios → **STOP**: "Haz los ajustes necesarios y cuando estés listo ejecuta `/git:push`"

#### 10. Ejecutar /git:push automáticamente

Una vez confirmado por el usuario, ejecutar `/git:push` para:

1. Verificar que estamos en la rama correcta
2. Re-ejecutar tests (verificación final)
3. Checkout a master y actualizar
4. Merge --no-ff:
```bash
git merge --no-ff issue/<NNNN>-<slug> -m "merge: issue/<NNNN>-<slug> — <título del issue>"
```
5. Push a remoto
6. Limpiar rama local

El comando `/git:push` maneja todo el flujo de integración automáticamente.

### Verificación final

Informar al usuario:

```
✓ Issue <NNNN>-<slug> completado e integrado a master

Rama: issue/<NNNN>-<slug> (mergeada y limpiada)
Commits integrados: <N>
Tests: pasando
Issue: movido a dev/issues/completed/

Master actualizado y sincronizado con remoto.
```

## Convenciones

- **Issue completo**: implementar todas las tareas, no parcial
- **Commits atómicos**: durante implementación, no al final
- **Tests obligatorios**: no cerrar sin tests pasando
- **Pure core / impure shell**: respetar arquitectura estrictamente
- **Feature flags solo si aplica**: no usar para ocultar trabajo incompleto
- **Confirmación obligatoria**: siempre pedir antes de integrar

## Troubleshooting

### Error: "Issue not found"

**Causa:** El archivo del issue no existe en `dev/issues/`

**Solución:**
```bash
ls dev/issues/
# Verificar número o slug correcto
# O crear el issue primero con /issues:create-issue
```

### Error: "Issue already completed"

**Causa:** El issue ya está en `dev/issues/completed/`

**Solución:**
El issue ya fue implementado. Si necesitas modificarlo:
1. Crear nuevo issue que referencia el anterior
2. O mover de vuelta a `dev/issues/` si realmente no estaba completo

### Error: "Tests failing during implementation"

**Causa:** Los cambios rompieron tests existentes

**Solución:**
1. Ver detalles:
```bash
go test -v -tags goolm ./...
```

2. Identificar qué test falló y por qué
3. Corregir el código o actualizar el test si es legítimo
4. Crear commit con el fix
5. Continuar implementación

### Error: "Cannot create branch, working tree not clean"

**Causa:** Hay cambios sin commitear

**Solución:**
```bash
git status
# Opción 1: Commitear cambios primero
git add . && git commit -m "mensaje"
# Opción 2: Hacer stash
git stash
# Luego ejecutar /issues:fix-issue nuevamente
```

### Error: "go build failed"

**Causa:** Errores de compilación en el código

**Solución:**
1. Leer el error de compilación cuidadosamente
2. Corregir el error en el código
3. Intentar compilar de nuevo
4. No continuar hasta que compile correctamente

### Advertencia: "Feature flag needed but not found"

**Causa:** El issue es parte de feature multi-issue pero no tiene flag

**Solución:**
1. Revisar si realmente necesita feature flag
2. Si sí: agregar a `dev/feature_flags.json`
3. Si no: continuar sin flag

## Reglas críticas

- **Seguir fix_issue.md estrictamente**: no saltear pasos
- **NO saltear tareas del issue**: implementar todas
- **NO hacer commits WIP**: cada commit debe ser atómico y completo
- **SIEMPRE usar -tags goolm**: en build y test
- **SIEMPRE ejecutar tests**: antes de cerrar issue
- **Confirmación obligatoria**: esperar aprobación del usuario antes de integrar
- **Flujo automático post-confirmación**: ejecutar `/git:push` para integrar
- **Respetar arquitectura**: core/ puro, shell/ impuro, app/ orquestación
- **NO inventar soluciones**: seguir las tareas del issue al pie de la letra