@saulwade/swl-ses 1.0.0

package/habilidades/mapear-codebase/SKILL.md

@@ -0,0 +1,275 @@
+---
+name: mapear-codebase
+description: Análisis profundo de un codebase existente. Genera árbol de directorios anotado, identifica puntos de entrada, tecnologías usadas, estándares del proyecto, deuda técnica visible y zonas de riesgo. Produce un documento estructurado que sirve como mapa de navegación para el equipo.
+version: "1.1.0"
+evolved: true
+evolved-from: "1.0.0"
+evolved-at: "2026-04-24"
+evolved-by: "aprender"
+evolved-note: "Sección nueva: validar parser jerárquico contra árbol real antes de congelar dataclass"
+herramientasPermitidas: [Read, Write, Edit, Bash, Glob, Grep]
+exclusiones:
+  - "No cargar cuando el codebase ya tiene un `CODEBASE-MAP.md` generado en los últimos 30 días y no ha habido cambios arquitectónicos — ejecutar este skill produce un mapa redundante con costo de análisis innecesario."
+  - "No cargar para análisis de seguridad del código — el mapa identifica zonas de riesgo estructural, no vulnerabilidades; para auditoría de seguridad cargar `reglas/seguridad.md` o invocar `revisor-seguridad-swl`."
+  - "No cargar para entender el codebase de un proyecto SWL propio (este mismo repo) — usar `.planning/ESTADO.md`, `INVENTARIO.md` y `ARQUITECTURA.md` que ya documentan la estructura interna."
+  - "No cargar para búsquedas puntuales de una función o patrón específico — `Grep` directo es suficiente y no requiere generar un CODEBASE-MAP.md completo."
+evolvable: true  # default para skill estandar
+---
+# Habilidad: Mapear Codebase Existente
+
+## Propósito
+
+Antes de modificar cualquier sistema heredado o desconocido, el equipo necesita
+un mapa preciso. Esta habilidad genera ese mapa de forma sistemática y sin
+suposiciones. El output es un documento que cualquier desarrollador puede leer
+para orientarse en menos de 15 minutos.
+
+## Cuándo activar
+
+- Se incorpora un desarrollador nuevo al proyecto
+- Se va a añadir una feature a un proyecto no familiar
+- Se detectan inconsistencias entre documentación y código
+- El planificador necesita entender el estado actual antes de planear
+
+---
+
+## Paso 1 — Reconocimiento inicial (5 minutos de exploración)
+
+Ejecutar los siguientes comandos de exploración antes de generar el documento:
+
+```bash
+# Árbol de directorios (excluir node_modules, .git, __pycache__, dist)
+find . -type f | grep -v node_modules | grep -v .git | grep -v __pycache__ \
+  | grep -v dist | grep -v .egg-info | sort | head -200
+
+# Conteo de archivos por extensión
+find . -type f | grep -v node_modules | grep -v .git \
+  | sed 's/.*\.//' | sort | uniq -c | sort -rn | head -20
+
+# Archivos de configuración en raíz
+ls -la . | grep -E "\.(toml|json|yaml|yml|env|cfg|ini|lock)$"
+
+# Tamaño de los módulos principales
+du -sh */ 2>/dev/null | sort -rh | head -20
+```
+
+---
+
+## Paso 2 — Identificación de tecnologías
+
+Para cada uno de los siguientes indicadores, verificar si existe en el proyecto:
+
+### Backend
+- `requirements.txt` / `pyproject.toml` / `Pipfile` → Python
+- `pom.xml` / `build.gradle` → Java/Kotlin
+- `package.json` en raíz sin framework frontend → Node.js
+- `go.mod` → Go
+- `Cargo.toml` → Rust
+- `Gemfile` → Ruby
+
+### Frontend
+- `angular.json` → Angular
+- `next.config.*` → Next.js
+- `vite.config.*` → Vite (React/Vue/Svelte)
+- `nuxt.config.*` → Nuxt
+- Presencia de `tailwind.config.*`
+- Presencia de `material` en package.json
+
+### Infraestructura
+- `Dockerfile` / `docker-compose.yml` → Docker
+- `terraform/` o `*.tf` → Terraform
+- `.github/workflows/` → GitHub Actions
+- `Makefile` → Build automation
+- `alembic/` → Migraciones SQLAlchemy
+
+---
+
+## Paso 3 — Identificar puntos de entrada
+
+Buscar explícitamente:
+
+| Tecnología | Punto de entrada típico |
+|-----------|------------------------|
+| FastAPI | `app = FastAPI()` en `main.py` o `app/main.py` |
+| Django | `manage.py`, `wsgi.py`, `asgi.py` |
+| Express | `app.listen` en `index.js` / `server.js` |
+| Angular | `main.ts` → `bootstrapApplication` o `AppModule` |
+| Next.js | `pages/_app.tsx` o `app/layout.tsx` |
+| Go | `func main()` en `cmd/*/main.go` |
+| Rust | `fn main()` en `src/main.rs` |
+
+Anotar: archivo exacto, función, puerto si es visible en config.
+
+---
+
+## Paso 4 — Detectar estándares del proyecto
+
+Verificar presencia y contenido de:
+
+- **Linting**: `.eslintrc*`, `ruff.toml`, `.pylintrc`, `flake8`
+- **Formateo**: `.prettierrc`, `black` en pyproject.toml, `editorconfig`
+- **Tests**: `pytest.ini`, `jest.config.*`, carpeta `tests/` o `__tests__/`
+- **Commits**: `.commitlintrc`, `CHANGELOG.md`, convenciones en README
+- **Branching**: documentado en README o CONTRIBUTING.md
+- **Tipo de imports**: absolutos vs relativos, alias configurados
+
+---
+
+## Paso 5 — Identificar deuda técnica visible
+
+Buscar activamente:
+
+```bash
+# TODOs y FIXMEs
+grep -r "TODO\|FIXME\|HACK\|XXX\|DEPRECATED" --include="*.py" \
+  --include="*.ts" --include="*.js" -n | head -50
+
+# Print/console.log de debug
+grep -r "console\.log\|print(" --include="*.py" --include="*.ts" \
+  --include="*.js" -n | grep -v "test\|spec\|logger" | head -30
+
+# Código comentado (señal de deuda)
+grep -r "^[[:space:]]*#.*def \|^[[:space:]]*//" --include="*.py" \
+  --include="*.ts" -n | head -20
+```
+
+Categorizar deuda encontrada:
+- **Deuda de código**: TODOs, prints, código comentado
+- **Deuda de test**: módulos sin cobertura visible
+- **Deuda de docs**: funciones públicas sin docstring/JSDoc
+- **Deuda de dependencias**: packages con versiones `*` o muy antiguas
+
+---
+
+## Estructura del documento de salida: `CODEBASE-MAP.md`
+
+```markdown
+# CODEBASE-MAP.md — [Nombre del Proyecto]
+**Generado**: [fecha]  **Analizado por**: [agente/persona]
+
+## Resumen ejecutivo
+[2-3 oraciones: qué hace el sistema, en qué estado está, nivel de madurez]
+
+## Stack tecnológico confirmado
+| Capa | Tecnología | Versión | Notas |
+|------|-----------|---------|-------|
+|      |           |         |       |
+
+## Árbol de directorios (anotado)
+```
+proyecto/
+├── src/              # Código fuente principal
+│   ├── api/          # Endpoints REST
+│   ├── models/       # Modelos ORM
+│   └── services/     # Lógica de negocio
+├── tests/            # Suite de tests
+├── migrations/       # Migraciones de BD
+└── .planning/        # Documentación del proyecto
+```
+
+## Puntos de entrada
+| Tipo | Archivo | Función/Clase | Puerto/URL |
+|------|---------|--------------|-----------|
+|      |         |              |           |
+
+## Módulos principales
+| Módulo | Responsabilidad | Dependencias internas | LOC aprox. |
+|--------|----------------|----------------------|-----------|
+|        |                |                      |           |
+
+## Convenciones detectadas
+- Estilo de código: [PEP8 / Airbnb / Google / sin estándar detectado]
+- Tests: [pytest / jest / sin tests detectados]
+- Commits: [conventional commits / libre]
+- Branching: [gitflow / trunk / no documentado]
+
+## Deuda técnica
+| Tipo | Descripción | Archivo(s) | Severidad |
+|------|-------------|-----------|----------|
+|      |             |           | Alta/Media/Baja |
+
+## Zonas de riesgo
+- [ ] [Módulo X]: sin tests, alta complejidad ciclomática
+- [ ] [Módulo Y]: dependencia no mantenida (última versión: 20XX)
+
+## Decisiones de arquitectura detectadas (implícitas)
+1.
+2.
+
+## Preguntas sin respuesta (para el equipo)
+- ¿Por qué se usa X en lugar de Y?
+- ¿Existe documentación de la API externa Z?
+```
+
+---
+
+## Reglas de calidad del mapa
+
+- NUNCA escribir "no encontrado" sin haber buscado activamente
+- Cada zona de riesgo debe tener evidencia (archivo y línea)
+- El árbol NO es el output de `tree` — es el árbol anotado con semántica
+- Si el codebase supera 50k LOC, mapear solo los módulos de mayor impacto
+
+## Cuándo NO cargar
+
+- El `CODEBASE-MAP.md` fue generado hace menos de 30 días y el proyecto no tuvo cambios arquitectónicos desde entonces — el análisis es caro en tool calls y el mapa existente es válido.
+- El objetivo es detectar vulnerabilidades de seguridad o código inseguro — este skill mapea estructura, no analiza patrones de seguridad. Para eso cargar `reglas/seguridad.md` o invocar `revisor-seguridad-swl`.
+- Se trabaja en el propio repositorio SWL — `INVENTARIO.md`, `.planning/ESTADO.md` y `ARQUITECTURA.md` ya documentan la estructura; generar un CODEBASE-MAP redundante fragmenta la documentación.
+- La necesidad es encontrar dónde está una función o clase específica — `Grep` directo con la firma de la función es suficiente y no requiere el análisis completo de los 5 pasos.
+
+## Gotchas / Errores comunes no obvios
+
+- **Árbol de directorios generado con `tree` sin anotar**: el CODEBASE-MAP.md tiene el árbol de directorios crudo sin explicar qué contiene cada carpeta. Causa: copiar el output de `tree` directamente en lugar de recorrer cada directorio y agregar semántica. Solución: el árbol en CODEBASE-MAP.md es obligatoriamente anotado — cada directorio no obvio debe tener un comentario breve (`# Lógica de negocio`, `# Endpoints REST`, etc.); sin anotaciones no es un mapa, es un listado.
+- **Deuda técnica marcada sin evidencia de archivo y línea**: el reporte dice "hay código comentado" sin indicar dónde. Causa: los `grep` de deuda se ejecutan pero el resultado no se procesa para extraer los archivos y líneas específicos. Solución: cada entrada en la tabla de deuda técnica debe incluir el path del archivo y el número de línea aproximado — una deuda sin ubicación no puede priorizarse ni corregirse.
+- **Zonas de riesgo inferidas sin verificación**: el mapa marca `api/auth.py` como "sin tests" sin haber verificado si existe `tests/test_auth.py` en otro directorio. Causa: buscar tests solo en el directorio adyacente al módulo. Solución: el Paso 4 requiere detectar la convención de organización de tests del proyecto (adyacente, directorio `tests/` raíz, o ambos) antes de marcar un módulo como sin cobertura.
+- **Preguntas sin respuesta omitidas porque "parecen obvias"**: el mapa no registra por qué se usa una dependencia inusual o por qué un módulo tiene una estructura atípica. Causa: el agente asume conocimiento del equipo. Solución: toda decisión implícita no documentada en el codebase debe aparecer en "Preguntas sin respuesta" — el propósito es exactamente capturar lo que no es obvio para alguien externo al proyecto.
+
+## Validar parser jerárquico contra el árbol REAL antes de congelar el dataclass
+
+### SIEMPRE: ejecutar `find <raíz> -type d | sort` sobre datos reales antes de diseñar
+
+**Cuándo aplicar**: al diseñar un `dataclass`, parser o modelo de estructura jerárquica (árbol de archivos, taxonomía de categorías, segmentos de ruta con numerales anidados) cuya forma exacta se desconoce a priori. Aplica especialmente cuando la jerarquía es heterogénea entre ramas.
+
+**Problema que previene**: asumir una profundidad fija (p.ej. "5 niveles") o una gramática regular (p.ej. "siempre letra + número + letra") basándose en una muestra pequeña o en la documentación del dominio. La realidad de los datos suele tener:
+- Profundidad variable entre ramas (5 niveles en una, 7 en otra).
+- Numerales compuestos (árabe + romano + inciso + subinciso).
+- Fusiones donde un nodo combina inciso con descripción en un solo segmento.
+- Saltos de niveles porque el dato fuente los omitió.
+
+Si el dataclass se congela sin ver estos casos, el parser requiere re-diseño completo al encontrar la primera rama atípica. Las 15 minutos de exploración ahorran horas de refactor.
+
+**Regla operativa**:
+
+1. Antes de escribir la primera línea del dataclass/parser, ejecutar:
+   ```bash
+   find <raíz-del-dataset> -type d -mindepth 1 | sort | head -200
+   # o para dataset enorme:
+   find <raíz-del-dataset> -type d -mindepth 1 | awk -F/ '{print NF-1}' | sort | uniq -c
+   ```
+2. Inspeccionar a ojo 3-5 ramas distintas. Anotar variaciones en profundidad, tipos de numeral, presencia/ausencia de segmentos esperados.
+3. Diseñar el dataclass para la variedad observada, no para el caso modal.
+4. Si después se descubre un caso no cubierto, el fix es extender el parser — no colapsar el caso a un molde que no lo acomoda.
+
+### Ejemplo genérico
+
+```python
+# MAL — dataclass con profundidad fija asumida
+@dataclass
+class RutaJerarquica:
+    nivel_1: str           # asume siempre letra mayúscula
+    nivel_2: int           # asume siempre número
+    nivel_3: str           # asume siempre inciso
+    nivel_4: str | None    # ocasionalmente un 4to nivel
+
+# Cuando llega una rama "A.7 d) I 1/" el parser explota o pierde información.
+
+# BIEN — dataclass con estructura variable comprobada contra datos reales
+@dataclass(frozen=True)
+class RutaJerarquica:
+    segmentos: tuple[str, ...]                   # profundidad variable
+    numeral_romano: str | None = None            # presente solo en algunas ramas
+    numeral_arabe_secundario: int | None = None  # caso observado en rama B
+    inciso_fusionado: bool = False               # caso donde inciso+desc vienen juntos
+```
+
+**Relacionado**: ver también `testing-python` (tests multi-formato ANTES de refactorizar un parser) y `patrones-python` (normalizadores al formato canónico del proyecto).

package/habilidades/memoria-busqueda/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: memoria-busqueda
+description: >
+  Búsqueda progresiva (Progressive Disclosure) sobre la memoria del sistema SWL:
+  aprendizajes en APRENDIZAJES.md, sesiones en sessions/*.json e instintos en
+  instintos/proyecto.yaml. Cargar cuando se necesite recuperar trabajo pasado,
+  buscar decisiones anteriores, entender qué se hizo en sesiones previas, o
+  evitar repetir errores ya documentados.
+version: "1.0.0"
+herramientasPermitidas: [Read]
+exclusiones:
+  - "No cargar para búsquedas triviales en el codebase (nombre de función, ruta de archivo); `Grep` directo es más barato y no requiere el índice de sesiones."
+  - "No cargar si la información ya está en el contexto activo de la sesión — no hacer una búsqueda de memoria para algo que se dijo hace 2 turnos."
+  - "No cargar para escribir o actualizar aprendizajes; este skill es de solo lectura. Para escribir, usar `extractor-de-aprendizajes`."
+  - "No cargar cuando el proyecto no tiene historial (primer día) — no hay sesiones en `.planning/sessions/` ni entradas en APRENDIZAJES.md que buscar."
+evolvable: true  # default para skill estandar
+---
+# Memoria Búsqueda — Progressive Disclosure Search
+
+## Cuándo cargar esta skill
+
+- Antes de empezar una tarea: verificar si hay aprendizajes relevantes previos.
+- Cuando el usuario pregunta "¿ya resolvimos esto antes?" o "¿qué hicimos la semana pasada?".
+- Al iniciar una sesión nueva en un proyecto con historial acumulado.
+- Para recuperar el contexto de una sesión anterior sin cargar todo a memoria.
+- Cuando se detecta un error potencialmente ya visto y documentado.
+
+---
+
+## El problema que resuelve
+
+Cargar APRENDIZAJES.md completo o todas las sesiones en contexto es costoso:
+- APRENDIZAJES.md puede tener 200+ entradas = 50,000+ tokens.
+- 50 sesiones x 1,000 tokens promedio = 50,000 tokens adicionales.
+- Total sin progressive disclosure: ~100,000 tokens para una búsqueda.
+
+Con las 3 capas, el costo típico es:
+- 20 índices (Capa 1): ~2,000 tokens.
+- 5 timelines (Capa 2): ~2,500 tokens.
+- 2 fetch completos (Capa 3): ~2,000 tokens.
+- **Total: ~6,500 tokens. Ahorro: ~93%.**
+
+---
+
+## Las 3 capas de búsqueda
+
+### Capa 1 — search(): índices compactos
+
+**Cuándo usar**: Siempre primero. Retorna solo id, tipo, título, fecha y relevancia.
+
+```js
+const { search } = require('./hooks/lib/memory-search');
+
+// Busqueda basica
+const resultados = search(baseDir, "error build classpath");
+// → [
+//     { id: "apr-5",               tipo: "aprendizaje", titulo: "Fix classpath Maven en CI", fecha: "2026-03-10", relevancia: 0.9 },
+//     { id: "ses-20260310-142000", tipo: "sesion",      titulo: "Investigacion build Java",  fecha: "2026-03-10", relevancia: 0.6 },
+//   ]
+
+// Con filtros
+const soloAprendizajes = search(baseDir, "autenticación JWT", {
+  tipo:        'aprendizaje',
+  fecha_desde: '2026-01-01',
+  limit:       10,
+});
+```
+
+**Filtros disponibles**:
+- `tipo`: `'aprendizaje'` | `'sesion'` | `'instinto'` (sin filtro = todas las fuentes)
+- `fecha_desde`: string YYYY-MM-DD — excluye resultados anteriores
+- `fecha_hasta`: string YYYY-MM-DD — excluye resultados posteriores
+- `limit`: número máximo de resultados (default: 20)
+
+**Costo por resultado**: ~50-100 tokens. Seguro pedir hasta 20 resultados.
+
+---
+
+### Capa 2 — timeline(): contexto cronológico
+
+**Cuándo usar**: Después de search(), para los 3-7 resultados más relevantes.
+Agrega contexto resumido sin traer el contenido completo.
+
+```js
+const { timeline } = require('./hooks/lib/memory-search');
+
+// Tomar los 5 ids mas relevantes de search()
+const ids  = resultados.slice(0, 5).map(r => r.id);
+const ctx  = timeline(baseDir, ids);
+// → [
+//     { id: "apr-5", tipo: "aprendizaje", titulo: "...", contenido: "<primeros 500 chars>", fecha: "2026-03-10" },
+//     { id: "ses-...", tipo: "sesion", contenido: "Modo: dev | Tool calls: 47 | Archivos: build.gradle | ...", fecha: "2026-03-10" },
+//   ]
+// Ordenado descendente por fecha (más reciente primero).
+```
+
+**Costo por entrada**: ~200-500 tokens. Seguro para 5-7 entradas simultáneas.
+
+---
+
+### Capa 3 — fetch(): detalle completo
+
+**Cuándo usar**: Solo para los 1-3 resultados definitivamente relevantes.
+Retorna el contenido completo sin truncar.
+
+```js
+const { fetch } = require('./hooks/lib/memory-search');
+
+// Solo para el resultado más relevante
+const detalle = fetch(baseDir, "apr-5");
+// → { id: "apr-5", tipo: "aprendizaje", contenido: "<bloque completo del APRENDIZAJES.md>" }
+
+const sesionCompleta = fetch(baseDir, "ses-20260310-142000");
+// → { id: "ses-...", tipo: "sesion", contenido: { ...objeto JSON completo... } }
+```
+
+**Costo**: ~500-1,000 tokens por resultado. NO hacer fetch de todos los resultados.
+
+---
+
+## Fuentes de datos y formato de IDs
+
+| Fuente | Formato de ID | Ejemplo |
+|--------|--------------|---------|
+| APRENDIZAJES.md | `apr-{N}` donde N es el índice del bloque H2 | `apr-0`, `apr-42` |
+| sessions/*.json | `ses-YYYYMMDD-HHmmss` (del campo `id` del JSON) | `ses-20260325-143000` |
+| instintos/proyecto.yaml | el valor del campo `id:` en el YAML | `inst-selectinload-async` |
+
+Los IDs de sesiones son estables (basados en timestamp). Los IDs de aprendizajes
+(`apr-N`) son posicionales: si se reordena APRENDIZAJES.md, los índices cambian.
+Siempre obtenerlos desde search(), no hardcodearlos.
+
+---
+
+## Protocolo de busqueda recomendado
+
+```
+1. search(query, { limit: 20 })
+   → Leer títulos y relevancias. Identificar los 3-7 más prometedores.
+
+2. timeline(ids_seleccionados)
+   → Leer el contenido resumido. Confirmar cuáles son relevantes.
+
+3. fetch(id_mas_relevante)
+   → Solo si el contenido resumido no es suficiente.
+   → Máximo 2-3 fetch por consulta.
+```
+
+**Regla de oro**: Si la respuesta de timeline es suficiente, no hacer fetch.
+
+---
+
+## Anti-patrones
+
+- **Fetch masivo**: `resultados.forEach(r => fetch(baseDir, r.id))` — anula el ahorro.
+- **Búsqueda sin query**: `search(baseDir, "")` — retorna vacío (protección intencional).
+- **Términos muy cortos**: "es", "el", "un" se filtran (longitud mínima: 3 caracteres).
+- **Ignorar la capa 1**: Ir directo a fetch sin buscar primero.
+- **Cargar APRENDIZAJES.md directamente**: Usar siempre esta API en su lugar.
+
+---
+
+## Cuándo NO cargar
+
+- La consulta es una búsqueda de código (patrón, función, clase); `Grep` sobre el codebase es más eficiente y no involucra el índice de sesiones.
+- La información pedida ya está en el contexto de la conversación — re-buscarla en la memoria persistente cuando ya está disponible desperdicia tokens y tiempo.
+- El objetivo es agregar o actualizar un aprendizaje; este skill es de solo lectura. Usar `extractor-de-aprendizajes` para escrituras.
+- El proyecto no tiene sesiones anteriores ni entradas en APRENDIZAJES.md; la búsqueda devolvería vacío. Verificar con `ls .planning/sessions/` antes de cargar.
+
+## Gotchas / Errores comunes no obvios
+
+- **Fetch masivo de todos los resultados de search()**: el agente llama a `fetch()` para cada uno de los 20 resultados de `search()`, consumiendo ~20,000 tokens en lugar de los ~6,500 del protocolo de 3 capas. Causa: se implementó el fetch como iteración directa. Solución: la regla de oro es explícita — hacer fetch solo de los 1-3 resultados definitivamente relevantes; para los demás, el resumen de `timeline()` es suficiente.
+- **IDs de aprendizaje (`apr-N`) hardcodeados entre sesiones**: el agente guarda `apr-42` en ESTADO.md y lo usa en la sesión siguiente, pero el índice cambió porque se reordenó APRENDIZAJES.md. Causa: los IDs posicionales son estables solo dentro de una sesión. Solución: nunca hardcodear `apr-N` en persistencia larga; siempre obtenerlos desde `search()` en el momento de uso.
+- **Búsqueda con query de 1-2 caracteres retorna vacío sin advertencia**: el agente busca `"CI"` y recibe un array vacío sin entender por qué. Causa: el filtro de longitud mínima de 3 caracteres descarta el término. Solución: usar queries de al menos 3 caracteres o frases descriptivas; para acrónimos cortos, expandirlos ("CI" → "continuous integration" o "integración continua").
+- **Capa 3 (fetch) usada para instintos que `context-builder` ya inyectó**: el agente hace fetch del instinto `inst-selectinload-async` cuando ese instinto ya está en el bloque de contexto inyectado al inicio de sesión. Causa: no se verificó si el instinto ya estaba disponible en contexto. Solución: antes de hacer fetch de un instinto, verificar si aparece en el bloque `[SWL Context]` inyectado — si está ahí, no es necesario recuperarlo.
+
+## Integración en hooks y agentes
+
+Para usar desde un hook o agente SWL:
+
+```js
+// En cualquier hook dentro de hooks/
+const { search, timeline, fetch } = require('./lib/memory-search');
+const baseDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+// Ejemplo: al inicio de sesión, buscar aprendizajes relevantes al contexto
+const aprendizajes = search(baseDir, "FastAPI SQLAlchemy async", {
+  tipo:  'aprendizaje',
+  limit: 5,
+});
+```
+
+El módulo es síncrono, sin dependencias externas y sin efectos secundarios.
+Safe para usar en PreToolUse hooks sin riesgo de bloqueo.

package/habilidades/memoria-busqueda/evals/evals.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "../../../schemas/skill-evals.schema.json",
+  "skill_name": "memoria-busqueda",
+  "artifact_type": "skill",
+  "schema_version": 1,
+  "description": "Evals para memoria-busqueda — progressive disclosure de APRENDIZAJES/sessions/instintos.",
+  "evals": [
+    {
+      "id": 0,
+      "prompt": "Quiero saber si ya resolvimos un problema similar antes. ¿Qué capa de búsqueda uso primero?",
+      "files": [],
+      "expectations": [
+        "Comienza por Capa 1 (índices, ~2000 tokens).",
+        "Solo escala a Capa 2 (timelines) si Capa 1 indica relevancia.",
+        "Solo escala a Capa 3 (fetch completo) cuando la entrada es claramente relevante.",
+        "Menciona el ahorro ~93% de tokens vs cargar todo."
+      ],
+      "tags": ["progressive-disclosure"]
+    },
+    {
+      "id": "anti-pattern-load-all",
+      "prompt": "¿Puedo cargar APRENDIZAJES.md completo para que el contexto sea más rico?",
+      "files": [],
+      "expectations": [
+        "La respuesta indica que NO, sería ~50,000 tokens innecesarios.",
+        "La respuesta menciona el patrón de progressive disclosure.",
+        "La respuesta redirige a la Capa 1 (índices)."
+      ],
+      "grading_guidance": "Failure si sugiere cargar todo.",
+      "tags": ["anti-pattern", "tokens"]
+    },
+    {
+      "id": "fuentes",
+      "prompt": "¿Qué tres fuentes indexa esta skill?",
+      "files": [],
+      "expectations": [
+        "APRENDIZAJES.md",
+        "sessions/*.json",
+        "instintos/proyecto.yaml (o equivalente instintos.)"
+      ],
+      "tags": ["scope"]
+    }
+  ]
+}