---
name: aprendizaje-continuo
description: >
  Sistema de aprendizaje continuo v2.1 basado en instintos. Cubre observacion de
  sesion via hooks, creacion y gestion de instintos con niveles de confianza,
  tres scopes (proyecto/dominio/global), degradacion automatica por contradiccion,
  promocion a skills/comandos/agentes, evolucion (merge, split, deprecate) y
  proteccion contra contaminacion cross-proyecto.
version: "1.0.1"
evolved: true
evolved-from: "1.0.0"
evolved-at: "2026-05-16"
evolved-by: "aprender"
evolved-note: "v1.0.1 (PATCH): nuevo gotcha 'Filtro de exclusión de hooks debe cubrir tests/'. Origen: H3 sesión 2026-05-16 — el extractor de aprendizajes capturaba comentarios JSDoc de un test recién escrito (palabras 'bug', 'patrón', 'fix') y los promovía como entradas truncadas a APRENDIZAJES.md porque PATRONES_ARCHIVO_SWL_EXCLUIDO no incluía tests/."
herramientasPermitidas: [Read]
exclusiones:
  - "No cargar para consultar instintos ya cargados en la sesión actual — si el perfil fue leído, re-cargarlo es desperdicio de contexto."
  - "No cargar para registrar una decisión de proyecto; las decisiones de diseño van a `DECISIONS.md` o APRENDIZAJES.md, no al sistema de instintos."
  - "No cargar para gestionar la memoria nativa de Claude Code (auto-memory); este skill cubre instintos de `instintos/*.yaml`, canal distinto."
  - "No cargar para promover un draft a instinto global sin evidence_count ≥ 3 — la promoción prematura contamina el scope global con datos sin confirmar."
evolvable: true  # default para skill estandar
---
# Aprendizaje Continuo v2 — Sistema de Instintos

## Concepto Central

Un **instinto** es una unidad de conocimiento aprendido de la experiencia real de sesión.
A diferencia de las skills (conocimiento declarativo estático), los instintos son
conocimiento inductivo: emergen de observar patrones repetidos en el comportamiento
del agente y los resultados que produce.

El sistema tiene cuatro capas:

```
Observación → Instinto (draft) → Instinto (consolidado) → Promoción
   (hook)       confianza<0.5      confianza≥0.5         skill/cmd/agente
```

---

## 1. Observación via Hooks

### Cobertura del 100% de actividad de sesión

Todo lo que el agente hace pasa por hooks instrumentados:

```jsonc
// .claude/settings.json — hooks de observación
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [{ "type": "command", "command": "node hooks/observe-pre.js" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": ".*",
        "hooks": [{ "type": "command", "command": "node hooks/observe-post.js" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "node hooks/session-end.js" }]
      }
    ]
  }
}
```

### Qué observar en cada evento

| Evento | Datos relevantes | Señal de instinto |
|--------|-----------------|-------------------|
| PreToolUse | tool_name, input | Herramienta usada antes de X |
| PostToolUse | tool_name, output, duration_ms | Herramienta exitosa/fallida |
| Stop | session_id, turn_count | Patrón de sesión completa |

**Regla**: los hooks de observación NUNCA deben producir exit code != 0.
Un fallo de observación no debe interrumpir el trabajo del agente.

---

## 2. Niveles de Confianza

### Escala de confianza (0.0 — 1.0)

| Rango | Estado | Significado |
|-------|--------|-------------|
| 0.0 – 0.29 | draft | Observado 1-2 veces, no fiable |
| 0.30 – 0.49 | draft | Patrón emergente, necesita confirmación |
| 0.50 – 0.69 | activo | Confiable para el scope actual |
| 0.70 – 0.89 | activo | Alta confianza, considerar promoción |
| 0.90 – 1.00 | activo | Candidato inmediato a skill/comando |

### Algoritmo de actualización de confianza

```
nueva_confianza = confianza_actual + (0.1 × peso_evento)

peso_evento:
  confirmacion_exitosa    = +1.0
  confirmacion_prevencion = +0.8
  excepcion_encontrada    = -0.3
  refutacion_directa      = -0.5
```

La confianza nunca supera 0.95 automáticamente — el último 5% requiere
revisión humana explícita antes de promoción.

---

## 3. Scope: Proyecto, Dominio y Global

### Scope de proyecto

- El instinto aplica solo en el directorio del proyecto actual
- Se almacena en `.claude/instintos/`
- Se activa cuando `PROJECT_NAME` coincide
- Ejemplo: "En este proyecto, los modelos usan prefijo `tb_`"

### Scope de dominio (nuevo en v4.1)

- El instinto aplica a todos los proyectos que usan el mismo stack/dominio
- Se almacena en `~/.claude/instintos/dominio/`
- Se activa cuando el proyecto actual coincide con las condiciones de activación
- Ejemplo: "En FastAPI, los background tasks no tienen acceso a la session de BD del request"

### Scope global

- El instinto aplica en cualquier proyecto
- Se almacena en `~/.claude/instintos/`
- Se activa siempre
- Ejemplo: "Nunca usar `except: pass` en Python"

Para referencia completa de dominios válidos, reglas de promoción de scope, formato de instinto,
evolución (merge/split/deprecate), protección cross-proyecto y estructura de directorio,
ver [recursos/referencia-instintos.md](recursos/referencia-instintos.md).

---

## Gotchas / Errores comunes no obvios

- **Instinto de scope global demasiado específico de un framework**: un instinto como "En FastAPI siempre usar `selectinload`" se promueve a `global.yaml` porque tuvo alta confianza. Causa: el criterio de promoción no verificó que el patrón sea cross-proyecto y no de dominio. Solución: antes de mover a global, aplicar el filtro "¿le sirve esto a un ingeniero en cualquier stack?"; si no, mantenerlo en `dominio.yaml` o `proyecto.yaml`.
- **Hooks de observación con exit code != 0 interrumpen la sesión**: el hook `observe-pre.js` lanza una excepción y Claude Code detiene la tarea en curso. Causa: violación de la regla "los hooks de observación NUNCA deben producir exit code != 0". Solución: envolver toda la lógica del hook en `try/catch` y loggear el error al stderr sin propagarlo — la observabilidad nunca debe bloquear el trabajo productivo.
- **Duplicación de instintos entre `proyecto.yaml` y `APRENDIZAJES.md`**: el mismo anti-patrón existe en ambos canales con información inconsistente. Causa: el instinto se creó manualmente sin verificar si ya había una entrada en APRENDIZAJES.md. Solución: antes de crear un instinto nuevo, ejecutar `memoria-busqueda` para verificar si ya existe en otro canal; si existe, actualizar el canal correcto según `reglas/memoria-consolidada.md`.
- **Confianza llegando a 0.95 sin revisión humana**: el algoritmo suma 0.1 por evento y el instinto llega a 0.95 sin que nadie lo revise antes de la promoción. Causa: no se aplicó la restricción del último 5% (requiere revisión explícita). Solución: al llegar a 0.90, el sistema debe emitir un checkpoint `human-verify` antes de superar ese umbral — automatizar la vigilancia en `session-end.js`.
- **Filtro de exclusión de hooks de extracción no cubre `tests/`** [CONFIRMADO 2026-05-16]: el hook `hooks/extraccion-aprendizajes.js` capturaba comentarios JSDoc/docstring de tests recién escritos por el agente y los promovía como entradas truncadas a `APRENDIZAJES.md`. Caso real: al escribir `tests/lib/ui-spinner-prompt.test.js` con un comentario `/** Bug original: cuando un comando arrancaba un spinner y luego (dentro de la lógica...) */`, el hook detectaba la palabra "bug" y promovía una entrada con título cortado a mitad de frase. Causa: `PATRONES_ARCHIVO_SWL_EXCLUIDO` tenía `agentes/`, `habilidades/`, `comandos/swl/`, `hooks/`, `scripts/`, etc., pero **no incluía `tests/`**. Solución: cualquier filtro de exclusión que protege contra ruido auto-referente del agente DEBE incluir explícitamente todos los patrones de tests: `tests/`, `__tests__/`, `spec/`, `*.test.{js,ts,jsx,tsx,mjs,cjs}`, `test_*.py`, `_test.{py,go}`. Los comentarios de un test describen el SUT (System Under Test) — contienen las mismas keywords que un descubrimiento real ("bug", "patrón", "fix") pero NO son descubrimientos. Patrón general: al diseñar un filtro de exclusión para hooks de observación, listar **todas las convenciones de naming de tests del ecosistema target**, no solo los directorios. Verificado en commit `cb4332e` swl-ses v1.6.0.

## Anti-patrones

- Crear instintos sin evidencia (mínimo 2 observaciones para pasar de draft)
- Instintos con scope global demasiado específicos a un framework de nicho
- No actualizar la confianza cuando el instinto previene un error (refuerzo positivo)
- Fusionar instintos de dominios distintos sin justificación clara
- Ignorar instintos en cuarentena — siempre revisarlos en la fecha programada
