Files

T

egutierrez 0ac8e72d14 docs: añadir regla de documentar desglose en fix_issue.md

Al desglosar un issue en sub-issues, ahora es obligatorio documentar
el desglose en el propio archivo del issue: tabla de sub-issues,
checklist de progreso por tarea, y actualizar con cada sub-issue
completada.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-03-07 19:19:52 +00:00

5.7 KiB

Raw Blame History

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:

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:

Añadir una seccion ## Desglose multi-issue en el documento del issue (antes de ## Ejemplo de uso o al final)
Incluir tabla con: sub-issue, rama, alcance, fases cubiertas, estado
Incluir checklist de progreso por tarea (marcar [x] las completadas, indicar en que sub-issue se hizo)
Actualizar el progreso cada vez que se completa una sub-issue

Si aplica, actualizar dev/feature_flags.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

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:

Commitear los cambios restantes (cierre de issue, README)
Hacer merge --no-ff de la rama a master
Push a remoto
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.

5.7 KiB Raw Blame History