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".