---
id: 0086
title: Refactor incremental de CLAUDE.md — delegacion agresiva a fn-constructor + capability groups por tags
status: pending
priority: high
created: 2026-05-13
related: [0069, 0085]
---

## 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:

```markdown
## 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`:

```markdown
# 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`:

```sql
-- 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.