Añadidos arhcivos basicos de repos
This commit is contained in:
@@ -0,0 +1,387 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user