fn_registry/docs/adr/0004-telemetry-driven-capability-growth.md

# ADR 0004 — Telemetria de ejecuciones de Claude como motor de crecimiento del registry

- **Fecha:** 2026-05-14
- **Estado:** accepted
- **Relacionados:** issue 0085 (telemetry + call_monitor), issue 0086 (delegation + capability groups), issue 0087 (capability discovery acceleration)

## Contexto

Hasta 0085, el registry crecia "manualmente": el humano (o Claude bajo supervision) detectaba patrones repetidos, redactaba proposals y un agente los implementaba. Costes observados en sesiones reales:

- Claude reinventaba inline logica que ya existia como funcion. Caso reciente (2026-05-13/14): `taskkill + cp Desktop + cmd /c start` ejecutado 5 veces seguidas pese a que `deploy_cpp_exe_to_windows_bash_infra` ya cubria el caso.
- Funciones recien creadas quedaban huerfanas (`calls_90d=0`) porque Claude no las encontraba via FTS5 con queries genericas.
- Tres pasos del bucle reactivo (`MEJORAR → APROBAR → CONSTRUIR`) requerian humano en el loop incluso para gaps obvios.

Sin medir lo que el agente realmente hace, las reglas (`registry_first.md`, `delegation.md`) son aspiracion no auditable. **No se puede mejorar lo que no se mide.**

## Decision

Tratar las **ejecuciones de Claude como senal de primera clase** del registry. Tres componentes encadenados:

1. **Capturar todo** (issue 0085) — Hook `PostToolUse` parsea cada Bash + cada `mcp__registry__*` y persiste en `projects/fn_monitoring/apps/call_monitor/operations.db`. Tablas: `calls`, `code_writes`, `test_runs`, `e2e_runs_fn`, `violations`, `patterns`, `sessions`. Vista `function_stats` agrega por `function_id`.

2. **Agrupar por capability** (issue 0086) — Tags planos (`notebook`, `metabase`, `deploy`, `cpp-windows`, ...) sobre funciones afines + pagina madre `docs/capabilities/<grupo>.md` con lista, ejemplo canonico y fronteras. Cargar un grupo cuesta **1 read**, no N busquedas FTS5.

3. **Acelerar descubrimiento** (issue 0087) — 5 capas escalonadas por coste de lookup:
   - Top-20 + fresh-7d en bloque autogenerado de CLAUDE.md (coste 0, contexto base).
   - Hook `UserPromptSubmit` injecta `FRESH:` / `TOP:` cada turno (coste 0).
   - Hook `PreToolUse` con `fn_match` fuzzy FTS5 sugiere `USE: ./fn run <id>` mid-flight (coste <50ms).
   - `docs/capabilities/<grupo>.md` cargado solo si tarea matchea dominio (coste 1 read).
   - `MEMORY.md` con insights cross-session (coste 0, persistente).

Las 3 metricas norte (en Monitor tab del `registry_dashboard`):

- `Reg %` — fraccion de calls con `function_id != ''`. Sube cuando Claude usa registry en vez de heredoc.
- `MCP ratio` — fraccion de `tool_used IN (mcp_*, fn_run)`. Mide adopcion canonica.
- `violations_24h` — antipatrones detectados. Baja con cada vuelta del bucle.

Cualquier decision tecnica que choque con estas metricas esta mal priorizada.

## Alternativas consideradas

- **Reglas mas estrictas sin telemetria.** Descartado: ya teniamos `registry_first.md` y se ignoraba sin que nada lo detectase. Reglas sin metricas son aspiracion.
- **Auto-merge de proposals desde el bucle reactivo.** Descartado: el agente decide *que* construir, pero el humano sigue revisando antes de escribir codigo permanente. Limite duro en `/fn_claude`: max 5 funciones por invocacion, no push automatico.
- **MCP-only sin hooks de telemetria.** Descartado: heredocs y `sqlite3` directo seguirian invisibles. El hook `PostToolUse` es la red de captura unica que cubre todos los canales (MCP, fn_run, heredoc, Edit, Write).
- **Indice estatico (lista plana de IDs) en lugar de capability groups.** Descartado: una lista de 800 funciones no cabe en contexto. Grupos con pagina madre densa (~80 lineas) cubren 80% del trabajo con coste de lectura asumible.

## Consecuencias

### Nuevo (visible en este repo)

- Carpeta `docs/capabilities/` con pagina madre por grupo. Indice en `docs/capabilities/INDEX.md`. Auditado por `fn doctor capabilities`.
- Hook `UserPromptSubmit` injecta cada turno: `REGISTRY-FIRST` + `CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z`.
- Hook `PostToolUse` (en `.claude/settings.local.json`) escribe a `call_monitor.operations.db`. Solo `args_hash`, NUNCA valores de argumentos (privacidad).
- Slash command `/fn_claude` — auto-auditoria: detecta gaps en la sesion, lanza `fn-constructor` en paralelo, valida que la proxima sesion usara la nueva funcion.
- Subagente `fn-constructor` mandatorio cuando se vaya a escribir >=5 lineas reutilizables inline.

### Reglas nuevas / endurecidas

- `.claude/rules/delegation.md` — STOP + spawn `fn-constructor` mismo turno, paralelo cuando >1 funcion independiente, tag de grupo obligatorio.
- `.claude/rules/capability_groups.md` — convencion de tag plano + pagina madre + auditoria via `fn doctor capabilities`.
- `.claude/rules/registry_calls.md` — 3 patrones canonicos (inspect / run / compose), antipatrones, excepciones para `sqlite3` directo.

### Boundary explicito

La telemetria cubre al **agente** y a **invocaciones canonicas**. Quedan fuera:

- Funcion Go/C++ llamada internamente por app ya compilada.
- Service de produccion recibiendo HTTP sin pasar por `fn run`.
- Sub-agente (`Agent` tool) sin telemetria heredada (mitigado por env var `FN_TELEMETRY=1` propagada).

Compensar runtime invisible con `e2e_checks` (issue 0068) y `fn doctor uses-functions` (audit estatico).

### Riesgos asumidos

- **Latencia de `fn_match` (capa 3).** Objetivo <50ms. Si supera 100ms, degradar a "solo en comandos largos" o "al final del turno".
- **Falsos positivos en propuestas automaticas.** Limite duro: max 5 por invocacion, evidencia obligatoria (snippet real), sin auto-merge.
- **Telemetria genera datos sensibles.** Mitigacion estructural: solo se guarda `args_hash`. Snippets de error redactados por allowlist.

## Aprendizaje

A 2026-05-14, primer grupo `cpp-windows` creado en respuesta directa al patron taskkill+cp+start repetido: `is_cpp_app_running_windows_bash_infra`, `launch_cpp_app_windows_bash_infra`, pipeline `redeploy_cpp_app_windows_bash_pipelines`, pagina madre `docs/capabilities/cpp-windows.md`. Validacion empirica del bucle: detectar -> construir -> agrupar -> documentar -> esperar reduccion de violations en proximas sesiones.

Pendiente: medir el delta de `Reg %` y `violations_24h` a 7d para confirmar que el coste de descubrimiento bajo de "FTS5 N veces" a "1 read de pagina madre".