swl-ses 3.3.2

package/habilidades/aprendizaje-continuo/SKILL.md

@@ -0,0 +1,369 @@
+---
+name: aprendizaje-continuo
+description: Sistema de aprendizaje continuo v2 basado en instintos. Cubre observación de sesión via hooks, creación y gestión de instintos con niveles de confianza, scopes de proyecto vs global, promoción a skills/comandos/agentes, evolución (merge, split, deprecate) y protección contra contaminación cross-proyecto.
+---
+
+# 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 |
+
+### Hook de observación mínimo (Node.js)
+
+```javascript
+// hooks/observe-post.js
+const fs = require('fs');
+
+const input = JSON.parse(fs.readFileSync('/dev/stdin', 'utf8'));
+const { tool_name, tool_input, tool_response } = input;
+
+const event = {
+  ts: Date.now(),
+  tool: tool_name,
+  success: !tool_response?.error,
+  duration_ms: tool_response?.duration_ms ?? null,
+  project: process.env.PROJECT_NAME ?? 'global',
+};
+
+// Append al log de observaciones
+const logPath = process.env.OBSERVATIONS_LOG ?? '.claude/observations.jsonl';
+fs.appendFileSync(logPath, JSON.stringify(event) + '\n');
+
+// Exit 0 obligatorio — nunca bloquear el flujo
+process.exit(0);
+```
+
+**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. Formato de un Instinto
+
+Cada instinto es un archivo Markdown con frontmatter YAML:
+
+```yaml
+---
+id: instinto-20240315-001
+titulo: "Siempre usar selectinload en queries con relaciones"
+confianza: 0.75
+scope: proyecto              # "proyecto" | "global"
+proyecto: sigaf-backend      # solo si scope=proyecto
+observaciones: 7             # cuántas veces se observó
+primera_vez: "2024-03-10"
+ultima_vez: "2024-03-15"
+estado: activo               # "draft" | "activo" | "deprecado" | "promovido"
+promovido_a: null            # "skill:fastapi-experto" | "comando:fix-selectin" | null
+tags: [sqlalchemy, async, orm]
+---
+
+## Descripción
+
+Al usar SQLAlchemy async, cada vez que se accede a una relación en la
+serialización Pydantic sin `selectinload()` se produce `MissingGreenlet`.
+
+## Patrón observado
+
+En 7 sesiones de trabajo con el modelo `fastapi-experto`, se detectó que
+queries sin eager loading causaban errores en producción que no aparecían
+en tests síncronos.
+
+## Acción correctiva
+
+```python
+# SIEMPRE incluir selectinload para relaciones accedidas
+stmt = select(Modelo).options(selectinload(Modelo.relacion))
+```
+
+## Condiciones de activación
+
+- Proyecto usa SQLAlchemy async (detectado en requirements.txt)
+- Se están escribiendo endpoints FastAPI con Pydantic
+
+## Evidencia
+
+- Sesión 2024-03-10: error MissingGreenlet en endpoint /usuarios
+- Sesión 2024-03-12: mismo error en endpoint /proyectos
+- Sesión 2024-03-15: prevenido al aplicar selectinload preventivamente
+```
+
+---
+
+## 3. 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.
+
+---
+
+## 4. Scope: Proyecto vs Global
+
+### Scope de proyecto
+
+- El instinto aplica solo en el directorio del proyecto
+- Se almacena en `.claude/instintos/`
+- Se activa cuando `PROJECT_NAME` coincide
+- Ejemplo: "En este proyecto, los modelos usan prefijo `tb_`"
+
+### Scope global
+
+- El instinto aplica en cualquier proyecto
+- Se almacena en `~/.claude/instintos/`
+- Se activa siempre
+- Ejemplo: "Nunca usar `except: pass` en Python"
+
+### Regla de promoción de scope
+
+Un instinto de proyecto puede ascender a global si:
+1. Se observa en 3+ proyectos distintos con la misma estructura
+2. La confianza es >= 0.7 en todos los proyectos
+3. No contradice ningún instinto global existente
+
+```bash
+# Comando para promover scope
+node scripts/instinto-promover-scope.js \
+  --id instinto-20240315-001 \
+  --de proyecto \
+  --a global
+```
+
+---
+
+## 5. Promoción de Instintos
+
+### A Skill
+
+Cuando un instinto tiene confianza >= 0.85 y cubre un dominio técnico bien definido:
+
+```bash
+# Genera un borrador de SKILL.md a partir del instinto
+node scripts/instinto-a-skill.js \
+  --instinto .claude/instintos/instinto-20240315-001.md \
+  --skill-dir habilidades/selectinload-sqlalchemy/
+```
+
+El instinto se marca `estado: promovido` y `promovido_a: skill:selectinload-sqlalchemy`.
+
+### A Comando
+
+Cuando el instinto describe una acción repetitiva que puede automatizarse:
+
+```bash
+node scripts/instinto-a-comando.js \
+  --instinto .claude/instintos/instinto-20240318-003.md \
+  --comando-dir comandos/fix-missing-selectin/
+```
+
+### A Agente
+
+Cuando el instinto describe un workflow completo y recurrente (confianza >= 0.90):
+
+```bash
+node scripts/instinto-a-agente.js \
+  --instinto .claude/instintos/instinto-20240320-007.md \
+  --agente-dir agentes/revisor-sqlalchemy/
+```
+
+---
+
+## 6. Evolución de Instintos
+
+### Merge (fusión)
+
+Dos instintos con patrones solapados se fusionan:
+
+```yaml
+# merge-plan.yaml
+fuente_a: instinto-20240310-001   # "usar selectinload"
+fuente_b: instinto-20240312-003   # "lazy='selectin' en relaciones Usuario"
+resultado: instinto-20240320-010  # "estrategia completa de eager loading async"
+razon: "Ambos instintos cubren el mismo dominio desde ángulos complementarios"
+```
+
+Regla: el instinto fusionado hereda `confianza = max(a, b) × 0.9` (penalty por fusión).
+
+### Split (división)
+
+Un instinto demasiado genérico se divide en instintos más específicos:
+
+```yaml
+# split-plan.yaml
+fuente: instinto-20240301-001   # "buenas prácticas SQLAlchemy"
+resultados:
+  - instinto-20240320-011       # "eager loading en queries async"
+  - instinto-20240320-012       # "session management en endpoints"
+  - instinto-20240320-013       # "commit solo en endpoint, nunca en service"
+razon: "El instinto original era demasiado amplio para activación precisa"
+```
+
+### Deprecate (deprecación)
+
+Un instinto se depreca cuando:
+- La librería cambió y el patrón ya no aplica
+- Se encontró una mejor práctica que lo reemplaza
+- La confianza cayó por debajo de 0.2 tras múltiples refutaciones
+
+```yaml
+estado: deprecado
+deprecado_en: "2024-04-01"
+razon: "SQLAlchemy 2.1 agregó lazy loading seguro en async por defecto"
+reemplazado_por: instinto-20240401-020
+```
+
+---
+
+## 7. Protección contra Contaminación Cross-Proyecto
+
+### El problema
+
+Si los instintos de un proyecto contaminan otro proyecto, se generan
+sugerencias incorrectas. Ejemplo: el prefijo `tb_` de tablas de un proyecto
+legacy no debe aplicarse en un proyecto nuevo con convención `snake_case`.
+
+### Mecanismo de aislamiento
+
+```javascript
+// hooks/instinto-loader.js
+const projectName = process.env.PROJECT_NAME;
+const instintosGlobales = loadInstintos('~/.claude/instintos/');
+const instintosProyecto = loadInstintos(`.claude/instintos/`);
+
+// Los instintos de proyecto NUNCA se exportan a otros proyectos
+const instintosActivos = [
+  ...instintosGlobales.filter(i => i.scope === 'global'),
+  ...instintosProyecto.filter(i => i.proyecto === projectName),
+];
+```
+
+### Cuarentena de instintos sospechosos
+
+Cuando un instinto produce una sugerencia que el humano rechaza 3+ veces,
+entra en cuarentena automática:
+
+```yaml
+estado: cuarentena
+cuarentena_inicio: "2024-03-20"
+rechazos: 3
+cuarentena_fin: "2024-03-27"   # revisión en 7 días
+```
+
+Durante la cuarentena, el instinto no se activa pero tampoco se borra —
+se espera revisión humana.
+
+---
+
+## 8. Directorio de Instintos
+
+Estructura recomendada en el proyecto:
+
+```
+.claude/
+└── instintos/
+    ├── index.yaml           # índice de todos los instintos activos
+    ├── draft/               # instintos con confianza < 0.5
+    ├── activos/             # instintos con confianza >= 0.5
+    ├── cuarentena/          # instintos rechazados en revisión
+    └── promovidos/          # instintos ya convertidos a skill/cmd/agente
+```
+
+### index.yaml mínimo
+
+```yaml
+version: 2
+ultimo_update: "2024-03-20"
+totales:
+  draft: 3
+  activos: 12
+  cuarentena: 1
+  promovidos: 5
+instintos:
+  - id: instinto-20240315-001
+    titulo: "Siempre usar selectinload en queries con relaciones"
+    confianza: 0.75
+    scope: proyecto
+    estado: activo
+```
+
+---
+
+## 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