fn_registry/.claude/commands/fix-issue.md

name, description

name	description
fix-issue	Implementar un issue de dev/issues/ end-to-end. Crea rama, ejecuta tareas, bumpa version si toca modulos/framework/apps (via /version), tests, cierra issue, integra a master.

/fix-issue

Ejecuta el flujo completo de implementacion/cierre de un issue de dev/issues/. Adaptado al stack del registry: Go (-tags fts5 CGO_ENABLED=1), Python (python/.venv/bin/python3), Bash, TypeScript (pnpm), C++ (cmake+mingw-w64 toolchain).

Inputs

/fix-issue <NNNN[a|b|c...]>

• NNNN: numero del issue (ej. 0107).
• Si es sub-issue, sufijo letra: 0107a, 0107b, ...

Si no se proporciona, preguntar.

Flujo obligatorio

1. Resolver el issue

• dev/issues/<NNNN>-*.md → si no existe, STOP.
• Si ya en dev/issues/completed/, STOP.
• Si es sub-issue, leer tambien el principal para contexto.

2. Leer y extraer

• Objetivo, tareas, arquitectura, prerequisitos, riesgos.
• Identificar archivos afectados — anotar si toca:
  • modules/<X>/ o cpp/framework/ → bumpa version (paso 8).
  • functions/, python/functions/, bash/functions/, frontend/functions/ → indexer + fn index al cerrar.
  • Apps en apps/<X>/ o projects/*/apps/<X>/ → requiere rama TBD (regla apps_tbd.md) + bumpa version per-app (paso 8). Si el issue toca multiples apps, una llamada /version por app.
  • Registry meta (CLAUDE.md, rules, templates) → push directo a master OK.

3. Estrategia de rama

Registry-only changes (functions/types/docs/rules):

• Push directo a master OK. NO crear rama.

Apps changes (apps/, projects/*/apps/):

• Crear rama TBD:

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

  La rama es del registry. Si la app es sub-repo, ademas crear rama dentro del sub-repo.

Modules/framework changes (modules/, cpp/framework/):

• Rama TBD obligatoria (afecta a todas las apps que linkean).

4. Plan con TaskCreate

• Crear tarea por bloque logico del issue.
• Incluir SIEMPRE:
  • Tarea de tests (unit + smoke).
  • Tarea de fn index si toco metadata.
  • Tarea de /version si toco modules/, cpp/framework/, apps/<X>/ o projects/*/apps/<X>/ (una llamada por target).
  • Tarea de cleanup/docs.

5. Implementar

Reglas registry-first (CLAUDE.md):

• ANTES de escribir codigo reutilizable → mcp__registry__fn_search para encontrar lo que existe.
• Si falta funcion reutilizable → spawn fn-constructor (no escribir inline).
• Si patron se repite >2x → propose nueva funcion.
• NUNCA sqlite3 registry.db "SELECT ..." plano — usar MCP.

Convenciones del stack:

Stack	Build/test
Go	CGO_ENABLED=1 go build -tags fts5 -o fn ./cmd/fn/ y CGO_ENABLED=1 go test -tags fts5 ./...
Python	python/.venv/bin/python3 -m pytest <path>
Bash	bash -n <script>.sh + tests inline
TypeScript	cd frontend && pnpm build && pnpm test
C++ (Linux)	cmake --build build --target <app>
C++ (Windows MinGW)	cmake -B build/windows -DCMAKE_TOOLCHAIN_FILE=cpp/toolchains/mingw-w64.cmake && cmake --build build/windows --target <app>

Commits atomicos por bloque logico con prefijos: feat:, fix:, test:, docs:, refactor:, chore:. Mensajes en espanol. NO WIP.

6. Tests

Stack-dependent (ver arriba). Si tests pasan parcialmente con failures pre-existentes no causadas por la rama, documentar en cuerpo del commit/PR.

7. Feature flags (si aplica)

Si el issue forma parte de un feature multi-issue:

• Editar dev/feature_flags.json con el flag (desactivado).
• Activar el flag en el ultimo sub-issue del set.

Flag != WIP. Codigo detras de flag debe compilar + testear.

8. Version bump (si toco modulos/framework/apps)

OBLIGATORIO si el issue toco alguno de:

• modules/<X>/ → bumpa modules/<X>/module.md::version.
• cpp/framework/ → bumpa modules/framework/module.md::version.
• apps/<X>/ → bumpa apps/<X>/app.md::version.
• projects/<P>/apps/<X>/ → bumpa projects/<P>/apps/<X>/app.md::version.

/version <path> <major|minor|patch> "<reason>"

Reglas (modulos/framework):

• Major: breaking ABI/API publica.
• Minor: additive (nuevo helper, refactor interno sin cambio de API, nuevo miembro).
• Patch: bugfix puro.

Reglas (apps):

• Major: breaking observable (CLI args, schema BBDD propia, formato wire).
• Minor: feature aditiva visible (nuevo panel, endpoint, opcion).
• Patch: bugfix sin cambio observable, refactor interno, mejora perf.

Una llamada /version por target afectado. Si el issue toca 1 modulo + 2 apps -> 3 llamadas a /version (cada una con su reason y bump-type apropiado; pueden diferir).

Diff guard: cambios que solo tocan el app.md (correccion typo descripcion, anadir tag) NO requieren bump — son metadata, no comportamiento. Detectar con git diff --name-only | grep -v '\.md$' para decidir si hay cambio de codigo real.

/version solo edita + stage. NO commit. El bump va junto con el codigo correspondiente en el mismo commit (feat: o fix: o refactor:).

Si NO toco modulos/framework/apps, saltar este paso.

9. Cerrar el issue

Mover archivo:

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

Actualizar dev/issues/README.md:

• Link → completed/<NNNN>-<slug>.md
• Estado → completado

Si es feature multi-issue y este es el ultimo sub-issue:

• Flip flag en dev/feature_flags.json a enabled: true con enabled_at: <YYYY-MM-DD>.
• Verificar que todos los sub-issues estan en completed/.

10. Integrar

Registry-only changes: push directo a master.

Apps/modules/framework changes: /full-git-push o /git-push (merge --no-ff de la rama a master, push, delete rama).

11. Verificar post-cierre

• fn index — registry.db al dia.
• fn doctor (subcomandos relevantes: artefacts, services, cpp-apps, uses-functions).
• Si toco modulos: fn doctor modules (post 0107a) — 0 drift.

Reglas criticas

• Registry-first: SIEMPRE buscar antes de escribir; delegar a fn-constructor antes que inline.
• TBD para apps: NUNCA push directo a master en apps. Rama corta, merge --no-ff.
• TBD NO para registry: push directo OK para functions/types/docs/rules.
• /version obligatorio si tocas modulos, framework o apps (con cambio de codigo real, no solo metadata). Si no, drift entre version: y ## Capability growth log y se pierde trazabilidad.
• Tests siempre: no cerrar issue sin tests pasando (salvo failures pre-existentes documentados).
• Commits atomicos: 1 commit = 1 bloque logico. No mezclar feat: + test: en mismo commit.
• Cerrar siempre: nunca dejar issue implementado sin mover a completed/ + actualizar README.

Referenciado desde

• .claude/commands/version.md — bump semver de modulos.
• .claude/commands/full-git-push.md — push del registry + sub-repos.
• .claude/rules/apps_tbd.md — politica de TBD por tipo de cambio.

Ejemplo: implementar 0107c (refactor data_table)

/fix-issue 0107c

1. Resolver: dev/issues/0107c-split-data-table.md ✓
2. Extraer: refactor 4777 LOC → 6 sub-funciones. Toca modules/ → /version obligatorio.
3. Rama: issue/0107c-split-data-table desde master.
4. Plan: 8 tareas (lectura + 6 sub-funciones + entrypoint thin + version bump).
5. Implementar: spawn fn-constructor en paralelo si hay >1 sub-funcion independiente.
6. Tests: build + smoke + primitives_gallery --capture diff.
7. Flag: parte de modules-v2, NO activar todavia (espera 0107a-f cerrar).
8. /version modules/data_table major "split data_table.cpp into 6 sub-functions"
9. Cerrar: mv → completed/ + README.
10. /git-push.
11. fn index + fn doctor modules → 0 drift en consumidores limpiados.