fn_registry/dev/issues/0086-claude-md-delegation-and-capability-groups.md

id, title, status, closed, priority, created, related

id	title	status	closed	priority	created	related
0086	Refactor incremental de CLAUDE.md — delegacion agresiva a fn-constructor + capability groups por tags	done	2026-05-14	high	2026-05-13	0069 0085

Cierre 2026-05-14

15 capability groups en docs/capabilities/INDEX.md con descripcion + ejemplo canonico + fronteras: metabase, mantine, deploy, ssh, systemd, registry, bigquery, nlp, docker, android, doctor, notebook, cpp-windows, git. Hook gate post-creacion (hook_capability_tag_gate.sh) + vista session_capability_growth (migration 005) + linea CAPABILITY-GROWTH en UserPromptSubmit ya operativos. Reglas delegation.md + capability_groups.md presentes en .claude/rules/INDEX.md. CLAUDE.md tiene bloque "Delegacion + Capability Groups (REGLA DURA)" al principio.

Contexto

.claude/CLAUDE.md (proyecto) cubre bien el "que" (BDs, sync, MCP-first, antipatrones) pero NO documenta el bucle que multiplica capacidades de Claude:

detectar gap -> spawn fn-constructor -> indexar -> importar -> invocar (mismo turno)

Hoy Claude:

• Detecta logica reutilizable y la escribe inline en el artefacto (o heredoc). No delega.
• Cuando si delega, suele hacerlo secuencial aunque las funciones sean independientes.
• Tras crear funciones nuevas, no las invoca en el mismo turno — quedan recien indexadas sin primer uso.
• No marca con tags de grupo las nuevas funciones, asi que el siguiente turno (o siguiente sesion) no encuentra el cluster facilmente. Resultado: re-descubrimiento via FTS5 cada vez.
• No hay documentacion de capability groups (ej. "metabase", "android-emu", "deploy", "notebook") — los tags existen sueltos pero sin pagina madre que liste el grupo, su API y ejemplos.

Issue 0085 ya da la base de telemetria (call_monitor + writes). Falta:

1. Doctrina en CLAUDE.md que obligue al ciclo crear-usar-tagear-documentar en el mismo turno.
2. Capability groups: tags canonicos + docs/capabilities/<group>.md autogenerable que liste funciones, firmas, ejemplos.
3. Loop closure: paralelizar fn-constructor, auto-verificar con fn doctor, usar las nuevas funciones antes de cerrar turno.

Objetivo

Que Claude, en cada turno, multiplique su capacidad util registrando funciones nuevas y reusandolas inmediatamente — no acumular funciones huerfanas ni reescribir logica inline.

Tres entregables:

1. Refactor incremental de .claude/CLAUDE.md (no reescritura completa): mantener estructura actual, comprimir secciones referenciales hacia docs/, anadir bloque nuevo "Delegacion + Capability Groups" al principio.
2. Sistema de capability groups basado en tags + docs/capabilities/<group>.md generado por fn doctor capabilities (nuevo subcomando) o pipeline dedicado.
3. Reglas duras nuevas en .claude/rules/ que el hook PreToolUse/UserPromptSubmit pueda verificar.

Diseno

Fase 1 — Bloque nuevo en CLAUDE.md (top del archivo)

Despues del parrafo "fn-registry" y antes de "Dos bases de datos SQLite", insertar bloque dedicado:

## Delegacion + Capability Groups (REGLA DURA)

Claude **multiplica capacidades** delegando creacion de funciones a `fn-constructor`
y reusandolas inmediatamente. NO escribir logica reutilizable inline.

### Cuando un patron es candidato a funcion

- Aparece >=2 veces en la sesion actual o en heredocs recientes.
- Firma es generica (no depende de tipos internos del artefacto).
- Tiene 1 responsabilidad clara (CRUD, parse, transform, http call, etc.).

### Flujo obligatorio (mismo turno)

1. **Detectar gap**. Si vas a escribir 5+ lineas de logica reutilizable inline -> STOP.
2. **Spawn `fn-constructor` inmediato** via `Agent(subagent_type="fn-constructor", ...)`.
   - Sin preguntar al usuario.
   - Si hay >1 funcion independiente -> **una sola llamada al Agent tool con N tool_use blocks paralelos**.
3. **Tagear con grupo de capacidad**. Cada funcion nueva lleva al menos UN tag de grupo
   (ej. `metabase`, `android-emu`, `notebook`, `deploy`, `osint`). Ver `docs/capabilities/`.
4. **`fn index`** para registrar.
5. **Importar y USAR en el mismo turno** — no dejar funcion huerfana recien creada.
6. **Auto-verificar**: `fn doctor uses-functions` y `fn doctor unused` para detectar drift.

### Anti-patrones (auditables)

| Anti-patron | Consecuencia | Sustituir por |
|---|---|---|
| Escribir helper inline en artefacto en vez de delegar | Re-invento por sesion | Spawn fn-constructor |
| Crear N funciones serialmente cuando son independientes | Latencia x N | Multiples Agent() en mismo mensaje |
| Crear funcion y no usarla en el turno | Funcion huerfana, calls_90d=0 desde dia 1 | Importar + invocar antes de cerrar turno |
| Crear funcion sin tag de grupo | Imposible descubrir en bloque la siguiente sesion | Anadir tag de capability group |
| Reescribir logica inline en heredoc que ya existe como funcion | Capitalizacion perdida | `mcp__registry__fn_search` antes de escribir |

### Capability groups

Cada grupo tiene una pagina madre en `docs/capabilities/<group>.md` con:
- Lista de funciones (ID + firma corta).
- 1-2 ejemplos canonicos de uso.
- Que NO hace el grupo (fronteras).

Generada/actualizada por `fn doctor capabilities --update`. Grupos vigentes:
ver `docs/capabilities/INDEX.md`.

Cuando Claude entra en una tarea de un dominio conocido, lee `docs/capabilities/<grupo>.md`
ANTES de buscar funciones sueltas. Eso desbloquea el grupo entero (no funcion a funcion).

Fase 2 — Comprimir secciones referenciales

Mover de CLAUDE.md a docs/:

Seccion actual	Destino
Schema rapido (functions/types/unit_tests/pc_locations + FTS5)	docs/schema.md
CLI completa (fn index, fn ops *, fn doctor, fn run, fn sync, fn proposal)	docs/cli.md
Anadir funciones / Anadir tipos (paso a paso)	docs/contributing.md
Analysis (estructura + crear + usar + helpers)	docs/analysis.md
Bucle reactivo 5 fases (detalle ExecuteAndReact)	docs/reactive_loop.md

CLAUDE.md queda como mapa (~150-180 lineas): identidad del repo + top reglas + tres patrones canonicos + punteros al INDEX de rules y a docs/.

Fase 3 — Capability groups (tags + docs autogeneradas)

3.1 Tags canonicos de grupo

Reservar un namespace de tags para "capability groups". Convencion: tag plano (sin prefijo) coincide con el slug del grupo:

Grupo	Tag	Cubre
metabase	metabase	Cliente HTTP, refresh metadata, dashboards, cards
android-emu	android-emu	adb, emulator, input events, screenshots
deploy	deploy	rsync, systemd, gitea webhook, vps setup
notebook	notebook	jupyter discover/read/exec/write/kernel
osint	osint	gliner/glirel, graph_explorer ingestion
frontend-ui	frontend-ui	@fn_library wrappers Mantine
sqlite-helpers	sqlite-helpers	open/migrate/wal/fts5
http-server	http-server	router, json response, middleware
...	...	...

fn doctor capabilities (nuevo subcomando) audita tags vs grupos declarados en docs/capabilities/INDEX.md.

3.2 Pagina madre por grupo

docs/capabilities/<grupo>.md autogenerable. Ejemplo docs/capabilities/notebook.md:

# Capability: notebook

Operar Jupyter Lab colaborativo desde cualquier sesion de Claude.

## Funciones

| ID | Firma | Que hace |
|---|---|---|
| jupyter_discover_py_notebook | `discover(host, port) -> JupyterInfo` | Lista instancias + kernels + sesiones |
| jupyter_read_py_notebook | `read(path, cell?) -> list[Cell]` | Lee celdas / metadata |
| jupyter_exec_py_notebook | `exec(mode, path, code, cell?)` | append/cell/kernel exec |
| jupyter_write_py_notebook | `write(action, path, content, cell?)` | append/insert/edit/delete |
| jupyter_kernel_py_notebook | `kernel(action, kernel_id?)` | list/start/restart/shutdown |

## Ejemplo canonico

\`\`\`bash
PY="python/.venv/bin/python3"
$PY python/functions/notebook/jupyter_discover.py --json
$PY python/functions/notebook/jupyter_exec.py append notebooks/01.ipynb "df.describe()"
\`\`\`

## Fronteras

NO incluye: ejecutar notebooks via papermill, scheduling, conversion a HTML.
Para eso ver `docs/capabilities/scheduling.md` o crear funcion nueva.

3.3 Autogeneracion

Nuevo pipeline generate_capability_doc_bash_pipelines <grupo>:

• Query a registry.db: SELECT id, signature, description FROM functions WHERE tags LIKE '%"<grupo>"%'
• Render template Markdown.
• Escribir a docs/capabilities/<grupo>.md (preservando seccion "Ejemplo canonico" y "Fronteras" si existen — son curated, no autogenerables).

fn doctor capabilities:

• Lista grupos en docs/capabilities/INDEX.md.
• Para cada grupo, cuenta funciones taggeadas vs documentadas.
• Avisa de drift: tag sin pagina, pagina sin funciones, funcion sin grupo.

Fase 4 — Reglas duras nuevas en .claude/rules/

Crear .claude/rules/delegation.md:

• "Si vas a escribir >=5 lineas de logica reutilizable inline -> STOP -> spawn fn-constructor"
• "Funciones independientes -> Agent paralelo en mismo mensaje"
• "Funcion creada -> tag de grupo obligatorio -> usar en el mismo turno -> fn doctor uses-functions"

Crear .claude/rules/capability_groups.md:

• Lista de grupos canonicos.
• Como crear grupo nuevo (cuando hay >=3 funciones que comparten dominio + no encajan en grupo existente).
• Como leer docs/capabilities/<grupo>.md antes de buscar funciones sueltas.

Actualizar .claude/rules/INDEX.md con las dos nuevas filas.

Fase 5 — Telemetria (reutiliza issue 0085, NO tabla nueva)

Anadir vista a call_monitor:

-- Funciones creadas + usadas en la misma sesion (multiplicador real)
CREATE VIEW IF NOT EXISTS session_capability_growth AS
SELECT
    w.session_id,
    w.function_id,
    w.created_at as first_write,
    MIN(c.ts) as first_call,
    COUNT(c.id) as calls_in_session
FROM code_writes w
LEFT JOIN calls c
    ON c.function_id = w.function_id
    AND c.session_id = w.session_id
    AND c.ts >= w.created_at
WHERE w.is_creation = 1
GROUP BY w.session_id, w.function_id;

Dashboard tab "Capability growth": cuantas funciones creo Claude por sesion, cuantas uso, cuantas quedaron huerfanas.

Hook UserPromptSubmit extiende su contexto con:

CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z. Si orphan>0 -> usa esas funciones o documenta por que no.

Decisiones tomadas (2026-05-14)

• Minimo por grupo: 3-4 funciones para crear pagina madre. Tags con <3 funciones se mantienen sueltos.
• Ubicacion docs: docs/capabilities/ (no .claude/capabilities/). Asi documentar, init y resto de agentes los leen igual que el resto de docs/.
• Auto-tagging masivo: SI. Pasada inicial sobre todas las funciones existentes (clustering por dominio + signature similarity + co-ocurrencia en uses_functions). Las nuevas a partir de hoy llevan tag obligatorio.
• Hook CAPABILITY-GROWTH: siempre on. Cada UserPromptSubmit inyecta linea CAPABILITY-GROWTH: created_this_session=X used=Y orphan=Z, incluso con valores 0/0/0. Razon: presencia constante crea disciplina, el banner muerto (0/0/0) es por si solo signal — recuerda que el bucle existe.

Pasos

1. Inventario actual de tags en registry.db (SELECT tag, COUNT(*) FROM functions_tags GROUP BY tag) — identificar candidatos a grupo (tags con >=3 funciones).
2. Auto-tagging masivo retroactivo: pipeline auto_tag_capabilities_bash_pipelines que:
   • Clusteriza funciones por domain + signature embedding + co-ocurrencia en uses_functions.
   • Propone tag de grupo para cada cluster con >=3 funciones.
   • Aplica via fn proposal add --kind add_tag (revision humana en bloque) o directo con --apply si confianza >0.9.
   • Idempotente: re-correr no duplica tags.
3. Crear docs/capabilities/INDEX.md + 1 pagina piloto (ej. notebook.md) a mano para fijar formato.
4. Implementar generate_capability_doc_bash_pipelines + fn doctor capabilities (audita drift tag<->doc).
5. Refactor incremental de .claude/CLAUDE.md (insertar bloque + comprimir + mover a docs/).
6. Crear .claude/rules/delegation.md + capability_groups.md + actualizar INDEX.
7. Anadir vista session_capability_growth a call_monitor.
8. Extender hook UserPromptSubmit con linea CAPABILITY-GROWTH (modo a definir).
9. Gate post-creacion: hook PostToolUse sobre Agent(subagent_type=fn-constructor) que verifica que la funcion creada lleva al menos un tag de grupo antes de cerrar turno.
10. Pilotar 3 grupos: notebook, metabase, deploy. Verificar que Claude (siguiente sesion) entra a docs/capabilities/metabase.md antes de buscar metabase_* sueltas.

Criterio de exito

• CLAUDE.md baja a <=200 lineas, sin perder informacion (movida a docs/).
• 5+ capability groups documentados con pagina madre.
• En una sesion piloto, Claude crea >=2 funciones nuevas y las invoca en el mismo turno (vista session_capability_growth lo confirma).
• fn doctor capabilities corre sin warnings tras la migracion inicial.
• Reduccion medible de patrones inline repetidos (vista patterns del call_monitor) tras 1 semana.

Riesgos

• Sobre-fragmentar en grupos pequenos: cada grupo con 2 funciones genera ruido. Minimo 3-4 funciones por grupo para crear pagina madre.
• Tags duplicados / drift: metabase vs mb vs metabase-client. fn doctor capabilities debe avisar y proponer normalizacion.
• Funciones nuevas huerfanas pese a la regla: si el "usar en mismo turno" es solo aspiracional, la regla muere. La vista de telemetria + hook de UserPromptSubmit son el gate real.
• Refactor de CLAUDE.md rompe punteros existentes: revisar que .claude/commands/, subagentes.md, etc. no referencien secciones movidas. Dejar redirects breves.

Notas

• Issue 0085 ya provee call_monitor + tablas calls, code_writes, patterns, violations. Esta issue NO crea tablas nuevas, solo vistas + reglas + docs.
• El sistema de capability groups es analogo a "skills" de Claude Code pero a nivel de funciones del registry — un grupo desbloquea un conjunto de capacidades aprendido del codigo ya existente, no externo.