388 lines
9.5 KiB
Markdown
388 lines
9.5 KiB
Markdown
---
|
||
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
|