fn_registry/.claude/rules/function_growth_and_self_docs.md

Function growth + self-documenting capability

Dos doctrinas hermanas. Una define como deben ser las funciones (auto-descubribles y lanzables sin segunda lectura). La otra define como crece el registry (no inflando funciones — promoviendo composiciones a pipelines).

Issue 0087.

---

Parte A — .md autosuficiente (contrato OBLIGATORIO)

Cuando Claude (o un humano) encuentra una funcion via FTS / fuzzy match / capability page / TOP block, el .md debe bastar para lanzarla sin abrir el codigo. Esto es lo que hace que descubrir = lanzar y elimina el coste del second lookup.

Secciones obligatorias en cada .md del registry (functions + pipelines + types con uso practico):

Seccion	Contenido	Tamaño
Frontmatter	name, signature, params (con desc por param), output, tags, uses_functions, etc. Lo de hoy.	—
## Ejemplo	Bloque de codigo lanzable con args concretos. Copiar+pegar produce ejecucion real. NO placeholders abstractos.	3-10 lineas
## Cuando usarla	1-2 frases con triggers: "cuando hagas X / antes de Y / si necesitas Z". Verbos imperativos. Ayuda al fuzzy match y a Claude a saber sin leer el codigo.	1-3 lineas
## Gotchas	Problemas conocidos / no-go cases. Obligatoria para funciones impuras o con efectos (Windows-side, red, FS write, GPU). Omisible para funciones puras triviales.	0-5 puntos
## Capability growth log	Solo SI la funcion ha crecido. Una linea por version: v1.1.0 (YYYY-MM-DD) — anade --build flag para skip build. No se rellena en v1.0.0.	crece con el tiempo

Anti-patrones del .md:

• Ejemplo con <arg1>, <arg2> placeholders abstractos — NO. Ejemplos con valores reales (registry_dashboard, /home/lucas/...).
• "Cuando usarla" vacio o "ver descripcion arriba" — NO. Frase nueva con trigger explicito.
• notes lleno + ## Gotchas vacio cuando la funcion tiene efectos — mover de notes a ## Gotchas.
• Capability growth log inventado (sin que la funcion haya cambiado) — NO. Solo se rellena cuando hay version bump real.

Verificacion (TBD: convertir a check de fn doctor): cada .md de functions//pipelines/ debe tener ## Ejemplo y ## Cuando usarla. ## Gotchas obligatoria solo si purity: impure. ## Capability growth log libre.

---

Parte B — Crecimiento por composicion (no por inflado)

Principio: una funcion que hace bien UNA cosa NO necesita crecer. Anadir params "por si acaso" la hace peor (Inner Platform Effect). Lo que crece es el registry: pipelines nuevos que componen funciones existentes.

Ejemplo del principio

• Hoy: Claude para hacer una transferencia bancaria llama bank_login -> bank_list_accounts -> bank_make_transfer. 3 calls, 3 decisiones, 3 puntos de fallo.
• Manana: pipeline bank_transfer_oneshot(account, amount, target) que compone las 3 internamente. 1 call, 1 decision.

Misma capacidad, 3x menos pasos. Esto es lo que multiplica la velocidad de Claude, no anadir flags a bank_login.

Como se promueve una composicion

Senal detectable en call_monitor.operations.db: secuencia A→B(→C) con

• Mismo session_id.
• Intervalo entre calls < N segundos (default 30s).
• Occurrences > K (default 5) en ventana de D dias (default 30).
• Success rate > S (default 0.9 — falla < 10%).
• No existe ya un pipeline que la cubra (validar con FTS sobre uses_functions).

Cuando se cumple → proposal new_pipeline con evidencia (sequence_ids, session_ids, occurrence count). Humano (o fn-orquestador autonomo) decide promover.

Implementacion (issue 0087 tanda A)

• call_monitor sequences --detect subcomando: escanea calls table, agrupa por session+window, computa secuencias, upserta en tabla function_sequences.
• Cron diario que ejecuta el detector + genera proposals automaticas.
• Visible en Monitor tab del registry_dashboard: sub-tab "Promotion candidates".

Cuando SI inflar una funcion

Casos legitimos para anadir feature a una funcion existente:

1. Generalizar firma sin romper consumidores (anadir param opcional con default sensato).
2. Mejor manejo de error (mensajes mas claros, retry sensible).
3. Default mas inteligente (autodetectar lo que antes era arg obligatorio).
4. Eliminar gotcha conocido (fix de bug que estaba en ## Gotchas).

NO infles para casos hipoteticos. NO anadas params "por flexibilidad". Si dudas, separa la responsabilidad en una funcion nueva o un pipeline.

Capability growth log — cuando se rellena

• Se rellena solo cuando la funcion crece (alguno de los 4 casos arriba).
• Cada bump de version -> 1 linea en ## Capability growth log con fecha y resumen 1-frase.
• Una funcion estable de hace 6 meses puede seguir en v1.0.0 sin log: indica madurez, no abandono.
• Telemetria (call_monitor) decide si una funcion estable es huerfana (calls_90d=0) o usada-y-buena (calls_30d>10, error_rate<0.05). Las primeras se deprecan; las segundas se respetan.

---

Parte C — Output de discovery

Cuando un mecanismo de discovery (fuzzy match / FRESH hook / TOP block / capability page) surfacea una funcion, el payload minimo es:

<id>  →  <signature>  →  <ejemplo de 1 linea>

Ejemplo concreto:

redeploy_cpp_app_windows_bash_pipelines
  ./fn run redeploy_cpp_app_windows registry_dashboard /path/to/app [--build]
  use: tras compilar cpp/build/windows, antes de smoke test manual

Si Claude necesita mas (gotchas, params completos, codigo), un mcp__registry__fn_show <id> adicional. Pero el primer hit ya basta para el 80% de casos.

---

Parte D — Relacion con otras reglas

• registry_first dice CUANDO buscar/usar/delegar. Esta regla dice COMO debe ser la funcion para que esa busqueda valga.
• ids_naming hace ID predictible. Esta regla hace metadata predictible.
• delegation dice cuando spawnar fn-constructor. Esta regla es lo que fn-constructor debe producir.
• capability_groups agrupa funciones afines. Las paginas madre de cada grupo deben respetar el mismo contrato self-doc (mejor con su propio ejemplo end-to-end por grupo).

Resumen TL;DR

1. Cada .md autosuficiente: Ejemplo + Cuando usarla + Gotchas (si impura) + Growth log (si crecio).
2. Las funciones que hacen bien una cosa NO necesitan crecer.
3. El registry crece promoviendo composiciones repetidas a pipelines, no inflando funciones.
4. Telemetria de call_monitor detecta secuencias candidatas y abre proposals automaticas.
5. Discovery devuelve siempre: id + signature + 1-line example. Resto on-demand.