repo_Claude/.claude/commands/issues/fix-issue.md

version, updated, tags

version	updated	tags
2.0.0	2026-03-11	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

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

Ejemplos

Ejemplo 1: Por número

/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

/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):

ls dev/issues/0010-*.md

Si viene slug completo (0010-access-control):

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

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:

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}}

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:

- [ ] 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:

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:

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}}

go test -tags goolm ./...

Casos:

• Tests pasan → ✓ Continuar a paso 7
• Tests fallan → ✗ STOP: corregir antes de continuar

  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:

{
  "<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:

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:

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:

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:

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:

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:

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:

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