@saulwade/swl-ses 1.1.4 → 1.2.1

package/habilidades/doubt-driven-review/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: doubt-driven-review
+description: >
+  Adversarial peer review de decisiones técnicas antes de comprometerlas.
+  Cuestiona supuestos, fuerza la articulación de alternativas descartadas y
+  detecta confianza injustificada. Cargar antes de decidir arquitecturas
+  irreversibles, elegir un framework crítico, definir un contrato de API
+  público o aprobar un PR de alto impacto. NO cubre adversarial review de
+  memoria (eso lo hace red-team-swl) ni de seguridad de código (eso lo hace
+  revisor-seguridad-swl) — este skill se especializa en decisiones técnicas
+  con costo de cambio alto.
+---
+
+# Doubt-Driven Review
+
+## Cuándo cargar
+
+- Antes de aprobar un ADR que toma una decisión irreversible.
+- Antes de comprometer un contrato público de API o un schema de BD que afecta integraciones externas.
+- Antes de elegir un framework, librería o patrón con costo de migración alto.
+- Antes de fusionar un PR cuyo blast radius incluye módulos críticos.
+- Cuando el equipo o el agente exhibe **alta confianza con baja evidencia** sobre una decisión técnica.
+
+## Cuándo NO cargar
+
+- Para revisar código por calidad — eso es `revisor-codigo-swl` con `Skill("checklist-calidad")`.
+- Para revisar seguridad — eso es `revisor-seguridad-swl` con `Skill("checklist-seguridad")`.
+- Para validar memoria contra prompt injection o privacidad — eso es `red-team-swl`.
+- Para discutir alcances con el usuario — eso es `Skill("brainstorming")` o `swl:discutir-fase`.
+- Para fixes triviales o decisiones reversibles en menos de 10 minutos.
+
+## Principio
+
+> Una decisión cuya alternativa no se ha articulado, no es una decisión:
+> es una preferencia. Toda decisión técnica con costo de cambio alto debe
+> sobrevivir a un round adversarial antes de comprometerse.
+
+El skill ejecuta un protocolo en 5 pasos. Cada paso produce evidencia en
+texto. La salida del skill NO aprueba ni rechaza — produce un reporte que
+el agente o usuario humano usa para decidir.
+
+## Protocolo
+
+### Paso 1 — Articular la decisión y su irreversibilidad
+
+Pedir explícitamente:
+
+- **Qué se decide**: 1-3 oraciones, sin jerga ambigua.
+- **Qué se descarta**: la decisión opuesta concreta.
+- **Costo de revertir**: estimación en turnos / archivos / horas si en 3 meses se concluye que fue incorrecta.
+
+Si el costo de revertir es < 4 horas y < 5 archivos: la decisión NO es candidata
+a doubt-driven review. Cerrar el skill y proceder.
+
+### Paso 2 — Forzar 3 alternativas descartadas
+
+El agente o usuario debe articular las 3 alternativas más fuertes que NO se eligieron, con:
+
+- Por qué cada una es plausible (≥ 1 razón concreta).
+- Qué tradeoff la hace inferior a la elegida (sin frase genérica como "menos flexible").
+
+Si la persona/agente no puede articular 3 alternativas: **señal de decisión bajo-evidencia**.
+Reportar: "Decisión propuesta sin alternativas articuladas. Riesgo de selección por inercia."
+
+### Paso 3 — Buscar contraevidencia activamente
+
+Para la decisión propuesta:
+
+- Listar 3 escenarios donde la decisión **fallaría** o produciría costos no anticipados.
+- Listar 1 caso histórico (dentro o fuera del proyecto) donde una decisión similar resultó incorrecta.
+- Identificar 1 supuesto de la decisión que NO está validado con evidencia (corre el riesgo de ser falso).
+
+Si los 3 escenarios de falla son improbables Y el supuesto está validado: la decisión gana robustez.
+Si ≥ 1 escenario tiene probabilidad ≥ 30%: documentar el riesgo en el reporte.
+
+### Paso 4 — Detectar confianza injustificada
+
+Patrones a marcar como red flags:
+
+- "Es la mejor práctica" sin citar fuente o caso.
+- "Siempre se hace así" sin verificar el contexto del proyecto actual.
+- "Es lo que recomienda <autoridad>" sin verificar que la recomendación aplica al stack/escala/dominio.
+- "No hay otra opción razonable" cuando el paso 2 ya forzó 3 alternativas.
+- Cita de un blog post o tweet como evidencia única.
+- Argumentos de tipo "todo el mundo lo usa" sin métrica concreta.
+
+Por cada red flag detectado: 1 línea en el reporte con cita textual del argumento.
+
+### Paso 5 — Trigger de reversión
+
+Toda decisión que pase doubt-driven review debe incluir:
+
+- **Trigger de reversión**: condición observable que, de cumplirse, obliga a reabrir la decisión.
+  Ejemplos válidos: "p95 de latencia > 800ms en producción durante 7 días",
+  "≥3 reportes de bugs relacionados con la limitación X en 30 días", "vendor X
+  publica deprecation notice", "costo mensual de infra excede $Y".
+- **Fecha de reevaluación automática**: 6-12 meses desde la fecha de decisión.
+
+Si la decisión NO puede tener trigger observable: es una decisión **basada en preferencia**,
+no en hipótesis falsable. Documentarla como tal en el reporte.
+
+## Formato del reporte
+
+```markdown
+## Doubt-Driven Review — [decisión] — [fecha]
+
+### Decisión articulada
+- Qué se decide: [...]
+- Qué se descarta: [...]
+- Costo de revertir: [estimación]
+
+### Alternativas articuladas
+1. [alt-1]: plausible porque [...]; descartada porque [tradeoff concreto]
+2. [alt-2]: ...
+3. [alt-3]: ...
+
+### Contraevidencia
+- Escenario de falla 1 [prob: alta/media/baja]: [...]
+- Escenario de falla 2 [prob: ...]: [...]
+- Escenario de falla 3 [prob: ...]: [...]
+- Caso histórico relevante: [...]
+- Supuesto sin validar: [...]
+
+### Red flags detectados
+- [línea N: cita textual del argumento débil]
+- [...]
+- (o "Ninguno")
+
+### Trigger de reversión
+- Condición: [observable falsable]
+- Fecha de reevaluación: [YYYY-MM-DD]
+
+### Veredicto
+- ROBUSTA — pasó los 5 pasos sin red flags y con trigger claro
+- ACEPTABLE — pasó con 1-2 red flags documentados y trigger claro
+- BAJO-EVIDENCIA — falla en pasos 2, 4 o 5; reabrir antes de comprometer
+```
+
+## Anti-patrones del skill
+
+- **Auto-revisión**: el agente que tomó la decisión ejecuta el skill sobre sí mismo.
+  Pierde el efecto adversarial. Cargar el skill desde un agente distinto al
+  decisor (ej: `arquitecto-swl` decidió → `revisor-codigo-swl` ejecuta el skill
+  con foco en la decisión).
+- **Trigger inverificable**: "cuando el sistema deje de escalar" no es trigger.
+  Debe ser una métrica observable con valor numérico o evento concreto.
+- **Alternativas de paja**: las 3 alternativas no pueden ser opciones triviales
+  inferiores a propósito. Si las 3 son obviamente peores, el skill perdió su valor
+  — pedir 3 alternativas reales o aceptar que la decisión es bajo-evidencia.
+- **Convertirlo en proceso burocrático**: aplicar doubt-driven a decisiones
+  reversibles es overhead. El paso 1 filtra esto explícitamente.
+
+## Relación con otras capacidades del sistema
+
+- `red-team-swl`: cubre adversarial review de **memoria del sistema** (perfil-usuario,
+  instintos, APRENDIZAJES). Doubt-driven cubre **decisiones técnicas**. NO duplicación.
+- `arquitecto-swl`: produce ADRs. Doubt-driven se carga ANTES de aceptar el ADR.
+- `revisor-codigo-swl`: revisa calidad de código ya escrito. Doubt-driven revisa
+  decisiones ANTES de escribir código.
+- `Skill("verificar-trabajo")`: verificación goal-backward del resultado.
+  Doubt-driven es goal-backward del **diseño**, no del resultado.
+
+## Origen
+
+Patrón observado en `temp/agent-skills-main/skills/doubt-driven-development`
+(2026-05-09). Adaptado al sistema swl-ses: en español, con trigger de
+reversión obligatorio (alineado con `reglas/arquitectura.md` § ADRs en estado
+Propuesto), y con relación explícita a `red-team-swl` para evitar duplicar
+funciones que ya existen en el sistema.
+
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).

package/habilidades/doubt-driven-review/recursos/EXAMPLES.md

@@ -0,0 +1,130 @@
+# EXAMPLES — Doubt-Driven Review
+
+Tres aplicaciones concretas del skill, dos exitosas y una que detectó decisión bajo-evidencia.
+
+---
+
+## Ejemplo 1 — Decisión que pasó como ROBUSTA
+
+**Contexto**: equipo evalúa migrar de PostgreSQL local a un servicio managed (RDS).
+
+### ❌ Sin doubt-driven (hipotético)
+
+> "RDS es la mejor opción porque AWS lo recomienda y todos lo usan."
+
+Costo de revertir no estimado, alternativas no articuladas, cero contraevidencia.
+Decisión se toma. 8 meses después se descubre que la latencia p95 desde el
+único cluster on-premise legacy del cliente sube 40ms y rompe SLA.
+
+### ✓ Con doubt-driven
+
+**Paso 1 — Articular**:
+- Qué se decide: migrar a RDS Aurora PostgreSQL en us-east-1.
+- Qué se descarta: mantener PostgreSQL self-hosted en EC2.
+- Costo de revertir: ~3 semanas (migrar datos de vuelta, reconfigurar backups, ajustar IAM).
+
+**Paso 2 — 3 alternativas**:
+1. **Self-hosted PostgreSQL en EC2**: control total de versión y extensiones; descartada
+   por costo operativo (on-call para BD).
+2. **Cloud SQL en GCP**: feature parity con RDS; descartada porque el resto del
+   stack ya está en AWS y multi-cloud agrega complejidad de red.
+3. **Supabase managed**: incluye Auth + Realtime gratis; descartada porque el
+   equipo no necesita Realtime y el lock-in en API propietario es alto.
+
+**Paso 3 — Contraevidencia**:
+- Falla 1 (prob: media): vendor lock-in si Aurora introduce features no portables → mitigación: limitar uso a SQL estándar.
+- Falla 2 (prob: baja): outage regional de us-east-1 → mitigación: read replica en us-west-2.
+- Falla 3 (prob: baja): costo de I/O excede presupuesto → mitigación: alertas de costo en CloudWatch.
+- Caso histórico: cliente X migró a RDS, descubrió que `pg_cron` no estaba disponible y refactoró 3 jobs.
+- Supuesto sin validar: "la latencia desde nuestros clientes on-premise será aceptable" — necesita pruebas reales.
+
+**Paso 4 — Red flags**: ninguno. Cada argumento está respaldado con caso o métrica.
+
+**Paso 5 — Trigger**:
+- Condición: "p95 de latencia desde el cliente legacy excede 200ms durante 7 días consecutivos" o "costo mensual supera $1500".
+- Fecha de reevaluación: 2026-11-15 (6 meses).
+
+**Veredicto**: ROBUSTA con 1 supuesto pendiente de validar (latencia on-premise → ejecutar prueba antes de migrar).
+
+---
+
+## Ejemplo 2 — Decisión BAJO-EVIDENCIA detectada
+
+**Contexto**: agente propone "vamos a usar Kafka para todos los flujos asíncronos del sistema."
+
+**Paso 1 — Articular**:
+- Qué se decide: introducir Apache Kafka como broker único.
+- Qué se descarta: Redis Streams + RabbitMQ ya existentes en el stack.
+- Costo de revertir: alto — requiere rehacer 12 productores y 8 consumidores.
+
+**Paso 2 — 3 alternativas**: el agente solo articula 1 (RabbitMQ) y dice "los demás
+no son comparables." → **Red flag**: incapacidad de articular 3 alternativas reales.
+
+**Paso 3 — Contraevidencia**: el agente dice "Kafka nunca falla en producción
+porque tiene replication." → **Red flag**: argumento sin caso histórico.
+
+**Paso 4 — Red flags**:
+- "Es la mejor práctica para event-driven architectures" (sin fuente).
+- "Todo el mundo lo usa a escala" (sin métrica del proyecto actual).
+- "No hay otra opción razonable" (contradicho por el paso 2 incompleto).
+
+**Paso 5 — Trigger**: "cuando lo necesitemos a más escala" — **Trigger inverificable**.
+Reescribir como "throughput supera 10k msg/s sostenido durante 14 días."
+
+**Veredicto**: BAJO-EVIDENCIA. Reabrir antes de comprometer.
+
+Resultado real: la decisión se difiere; al revisar, se descubre que el throughput
+actual del sistema es ~80 msg/s — Kafka habría sido sobre-ingeniería con costo
+operativo de un cluster que el equipo no tiene capacidad de mantener.
+
+---
+
+## Ejemplo 3 — Decisión ACEPTABLE con red flag documentado
+
+**Contexto**: elegir framework frontend para un dashboard interno nuevo.
+
+**Paso 1**:
+- Qué se decide: Next.js App Router + Server Components.
+- Qué se descarta: SPA con Vite + React Query.
+- Costo de revertir: medio — 2 semanas de migración + reescritura de data fetching.
+
+**Paso 2 — 3 alternativas**:
+1. **SPA Vite + React Query**: más simple, menos magia; descartada porque queremos SSR para SEO interno y autenticación server-side.
+2. **Remix**: nested routing nativo; descartada porque el equipo ya tiene experiencia con Next.js y la curva de Remix agrega 2 semanas.
+3. **Astro con islands**: ideal si fuera contenido estático; descartada porque el dashboard es 80% interactivo.
+
+**Paso 3 — Contraevidencia**:
+- Falla 1 (prob: media): App Router introduce breaking changes y rompe el build (ya pasó con v13→v14).
+- Falla 2 (prob: baja): RSC mental model genera bugs sutiles de hidratación.
+- Falla 3 (prob: baja): vendor lock-in con Vercel — mitigación: deploy en Cloudflare Workers o self-hosted.
+- Caso histórico: equipo Y adoptó App Router en beta y tardó 3 meses en estabilizar.
+- Supuesto: "el equipo aprenderá RSC en 2 sprints" — moderadamente optimista.
+
+**Paso 4 — Red flags**:
+- "App Router es el futuro" (cita de blog post de Vercel — sesgo de fuente).
+
+**Paso 5 — Trigger**:
+- Condición: "≥3 bugs de hidratación reportados por usuarios en sprint 5" O "Vercel
+  anuncia deprecation de App Router".
+- Fecha de reevaluación: 2026-08-15 (3 meses, periodo corto por uso de feature reciente).
+
+**Veredicto**: ACEPTABLE — 1 red flag documentado (cita de Vercel como fuente única
+para "futuro"). El equipo procede con awareness del sesgo.
+
+---
+
+## Patrón de aplicación
+
+| Ejemplo | Costo revertir | Alternativas articuladas | Red flags | Trigger | Veredicto |
+|---|---|---|---|---|---|
+| 1 — RDS | 3 semanas | 3 sólidas | 0 | Métrico claro | ROBUSTA |
+| 2 — Kafka | 12+8 servicios | 1 (incompleto) | 3 | Inverificable | BAJO-EVIDENCIA |
+| 3 — Next.js | 2 semanas | 3 sólidas | 1 (sesgo de fuente) | Métrico + evento externo | ACEPTABLE |
+
+El skill es útil cuando:
+- El costo de revertir es alto Y
+- Hay tendencia a saltar al "qué" sin articular el "por qué no las otras".
+
+Es overhead cuando:
+- La decisión es reversible en horas O
+- La decisión ya fue auditada por un proceso equivalente (ADR formal con contexto + alternativas + consecuencias).

package/habilidades/eval-framework/SKILL.md

@@ -0,0 +1,212 @@
+---
+name: eval-framework
+description: >
+  Eval framework para validar y puntuar outputs estructurados de SWL
+  (aprendizajes, instintos, observaciones, resúmenes, contextos). Cargar
+  cuando un agente produzca un output estructurado y se quiera medir su
+  calidad antes de persistir, o cuando se audite la calidad histórica de
+  funciones críticas (extractor-de-aprendizajes, perfilador-usuario,
+  consolidador, planificador).
+version: "1.0.0"
+herramientasPermitidas: [Read, Bash]
+exclusiones:
+  - "No cargar para validación de input de usuario o request HTTP — eso es validación de boundary, usar Pydantic/Zod en el endpoint."
+  - "No cargar para auditoría de seguridad — usar `revisor-seguridad-swl` y `escaneo-secretos`."
+  - "No cargar para tests unitarios de código — usar `tdd-workflow` y Vitest."
+  - "No cargar cuando el output no tiene estructura definida (texto libre): el eval framework requiere schemas declarados o quality scorers específicos."
+evolvable: true  # default para skill estandar
+---
+# Eval Framework — Validación + Calidad de Outputs SWL
+
+## Cuándo cargar
+
+- Tras producir un output estructurado (observación, aprendizaje, resumen,
+  resultado de búsqueda) cuando se quiera puntuar su calidad antes de
+  persistir.
+- Para auditar histórico de calidad de una función crítica (ver métricas
+  agregadas en `.planning/evolucion/eval-metrics.json`).
+- En tests/CI cuando el contrato del output tenga campos obligatorios y
+  quality thresholds.
+- En loops de auto-corrección donde un output inválido debe regenerarse
+  con un prompt más estricto.
+
+---
+
+## Componentes del framework
+
+| Módulo | Propósito |
+|---|---|
+| `scripts/lib/eval-schemas.js` | Schemas JSON-lite para outputs (observación, resumen, search input, etc.). |
+| `scripts/lib/eval-validator.js` | Validador zero-deps de schemas (sin Zod). |
+| `scripts/lib/eval-quality.js` | Funciones de scoring: `scoreObservacion`, `scoreResumen`, `scoreAprendizaje`, `scoreInstinto`, `scoreRelevanciaContexto`. |
+| `scripts/lib/eval-self-correct.js` | Loop de retry con sufijo estricto cuando validador falla. |
+| `scripts/lib/eval-metrics-store.js` | Persistencia: JSONL append-only (`eval-results.jsonl`) + agregado JSON (`eval-metrics.json`). |
+| `scripts/run-eval.js` | CLI para evaluar un output desde archivo JSON. |
+
+---
+
+## Uso típico desde agente o test
+
+### Validar output contra schema
+
+```js
+const { validar } = require('./scripts/lib/eval-validator');
+const { COMPRESS_OUTPUT_SCHEMA } = require('./scripts/lib/eval-schemas');
+
+const observacion = {
+  type: 'discovery',
+  title: 'Detalle relevante',
+  facts: ['fact 1', 'fact 2'],
+  narrative: 'Narrativa con suficiente detalle para evaluar',
+  concepts: ['c1'],
+  files: ['ruta/al/archivo.js'],
+  importance: 7,
+};
+
+const r = validar(observacion, COMPRESS_OUTPUT_SCHEMA);
+if (!r.valid) {
+  console.error('Output inválido:', r.errors);
+} else {
+  // Persistir
+}
+```
+
+### Puntuar calidad (independiente de validez)
+
+```js
+const { scoreObservacion, scoreAprendizaje, scoreInstinto } = require('./scripts/lib/eval-quality');
+
+const score = scoreObservacion(observacion);
+// score ∈ [0, 100]. 100 = todos los campos óptimos.
+```
+
+### Loop de auto-corrección
+
+```js
+const { compresseConReintento } = require('./scripts/lib/eval-self-correct');
+
+const productor = async (sysPrompt, userPrompt) => {
+  // Llamar al LLM o ejecutar Skill que produzca el output
+  return await llamarClaude(sysPrompt, userPrompt);
+};
+
+const validador = (output) => {
+  const parsed = JSON.parse(output);
+  return validar(parsed, COMPRESS_OUTPUT_SCHEMA);
+};
+
+const r = await compresseConReintento({
+  productor, validador,
+  sysPrompt: '...', userPrompt: '...',
+  maxRetries: 2,
+});
+
+if (r.valid) {
+  // r.output es válido (puede haber requerido r.intentos retries)
+}
+```
+
+### Persistir métricas para auditoría histórica
+
+```js
+const ms = require('./scripts/lib/eval-metrics-store');
+
+ms.registrar(process.cwd(), {
+  functionId: 'extractor-de-aprendizajes::scorer',
+  latencyMs: 42,
+  success: true,
+  qualityScore: 85,
+});
+
+// Lectura agregada
+const m = ms.obtener(process.cwd(), 'extractor-de-aprendizajes::scorer');
+// → { totalCalls, successCount, failureCount, avgLatencyMs, avgQualityScore, ... }
+```
+
+### CLI desde Bash (para CI o manual)
+
+```bash
+# Crear archivo de eval
+cat > /tmp/eval.json << 'EOF'
+{
+  "functionId": "memoria-busqueda::search",
+  "schemaName": "MEMORY_SEARCH_RESULT_SCHEMA",
+  "qualityScorer": null,
+  "expectedKeys": ["id", "tipo", "titulo", "fecha", "relevancia"],
+  "output": { ... }
+}
+EOF
+
+# Ejecutar
+node scripts/run-eval.js /tmp/eval.json
+# Exit 0 si valid, 1 si inválido. Persiste métricas automáticamente.
+
+# Reconstruir agregado desde JSONL si se corrompe
+node scripts/run-eval.js --rebuild-aggregate
+```
+
+---
+
+## Schemas disponibles
+
+- `COMPRESS_OUTPUT_SCHEMA` — observación comprimida con type, title, facts,
+  narrative, concepts, files, importance.
+- `SUMMARY_OUTPUT_SCHEMA` — resumen de sesión con title, narrative,
+  keyDecisions, filesModified, concepts.
+- `SEARCH_INPUT_SCHEMA` — input de búsqueda { query, limit? }.
+- `REMEMBER_INPUT_SCHEMA` — input de "remember" { content, type?,
+  concepts?, files? }.
+- `EVAL_RESULT_SCHEMA` — resultado de evaluación { valid, errors?,
+  qualityScore, latencyMs, functionId, metadata? }.
+- `MEMORY_SEARCH_RESULT_SCHEMA` — resultado de `hooks/lib/memory-search`
+  con id, tipo, titulo, fecha, relevancia, combinedScore?, confidence?.
+
+Agregar más schemas en `scripts/lib/eval-schemas.js` siguiendo el formato
+JSON Schema-lite (subset documentado en `eval-validator.js`).
+
+---
+
+## Quality scorers disponibles
+
+- `scoreObservacion(obs)` — observación con type/title/facts/narrative/concepts/importance.
+- `scoreResumen(summary)` — resumen con title/narrative/keyDecisions/filesModified/concepts.
+- `scoreAprendizaje(aprendizaje)` — aprendizaje SWL con titulo/contenido/tipo (específico de SWL).
+- `scoreInstinto(instinto)` — instinto con pattern/confidence/status/source_*/evidence_count (específico de SWL).
+- `scoreRelevanciaContexto(context, project)` — contexto inyectado en sesión.
+
+Cada scorer devuelve un número en [0, 100]. Los criterios están documentados
+en cada función en `scripts/lib/eval-quality.js`.
+
+---
+
+## Diferencias con tests unitarios
+
+| Eval framework | Tests unitarios |
+|---|---|
+| Mide calidad subjetiva sobre estructura | Mide correctitud lógica |
+| Score graduado [0, 100] | Pass/fail binario |
+| Persiste histórico para auditoría | No persiste (corre en CI) |
+| Para outputs estructurados de agentes | Para funciones puras / API |
+| Permite retry con prompt estricto | No aplicable |
+
+Los dos son complementarios: tests unitarios para `scoring-instintos.js`,
+eval framework para "¿el aprendizaje que extrajo el hook es de calidad?".
+
+---
+
+## Gotchas / Errores comunes no obvios
+
+- **Validez estructural ≠ calidad**: un aprendizaje con `titulo: "X"` y
+  `contenido: "trivial"` puede pasar `expectedKeys` pero tener
+  `qualityScore: 0`. El framework los distingue. En CI gates, considerar
+  ambos: `valid && qualityScore >= 60`.
+- **Métricas agregadas se reescriben atómicamente**: si dos procesos
+  llaman `registrar()` en paralelo sobre el mismo `functionId`, el último
+  gana (race condition en agregado). Para alta concurrencia usar
+  `reconstruirAgregado()` periódicamente desde el JSONL append-only.
+- **`run-eval.js` exit code**: 0 = valid, 1 = inválido o error de I/O,
+  2 = error de uso. No confundir con quality threshold — el CLI no
+  bloquea por quality bajo, solo por validez.
+- **`compresseConReintento` no reintenta indefinidamente**: respeta
+  `maxRetries`. Tras agotar reintentos devuelve el último output con
+  `valid: false`. El caller decide qué hacer.

package/habilidades/memoria-busqueda/SKILL.md

@@ -6,7 +6,7 @@ description: >
   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"
+version: "1.1.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."
@@ -42,6 +42,29 @@ Con las 3 capas, el costo típico es:
 
 ---
 
+## Fusión de fuentes con RRF (desde v1.2.0)
+
+`search()` combina las 3 fuentes (aprendizajes, sesiones, instintos) usando
+**Reciprocal Rank Fusion** (`scripts/lib/rrf-fusion.js`). En lugar de
+sumar relevancias heterogéneas (que no son comparables — la "relevancia 0.7"
+de un aprendizaje no significa lo mismo que en una sesión), RRF combina
+basándose en la posición (rank) que cada documento ocupa en su propia lista.
+
+Fórmula: `score(d) = Σ_i  w_i / (k + rank_i(d))` con `k=60` y pesos
+empíricos `[aprendizajes 0.4, sesiones 0.4, instintos 0.2]`.
+
+Propiedades:
+- Documentos que aparecen en múltiples streams reciben boost natural.
+- Documentos que aparecen en un solo stream NO son penalizados.
+- Robust ante magnitudes distintas de score por fuente.
+
+Backward compatible: el retorno conserva el campo `relevancia` (calculado
+por la fuente). Se agrega `combinedScore` para que el caller pueda razonar
+sobre el ranking RRF si lo desea. Si `rrf-fusion.js` no está disponible,
+`search()` cae al merge por relevancia simple legado.
+
+---
+
 ## Las 3 capas de búsqueda
 
 ### Capa 1 — search(): índices compactos

package/habilidades/meta-skills-estandar/SKILL.md

@@ -263,6 +263,10 @@ el contenido específico, sin inflar el contexto con cada invocación:
 - **Mapeo a frameworks de seguridad (NIST CSF, NIST AI RMF, MITRE ATT&CK/ATLAS/
   D3FEND)** + **migración a nombres de campo en español (REC-S15)**. Ver
   [recursos/frameworks-seguridad.md](recursos/frameworks-seguridad.md).
+- **Convención `EXAMPLES.md` como recurso opcional** para skills críticos cuyo
+  valor depende de mostrar diff MAL→BIEN lado a lado (decisiones, arquitectura,
+  anti-patrones sutiles). NO retroactiva — las 63 carpetas `recursos/` existentes
+  no se renombran. Ver [recursos/convencion-examples.md](recursos/convencion-examples.md).
 
 Cada recurso tiene ToC al inicio y es autocontenido — leer solo el relevante
 al caso en cuestión en lugar de los tres.

package/habilidades/meta-skills-estandar/recursos/convencion-examples.md

@@ -0,0 +1,93 @@
+# Convención `EXAMPLES.md` — recurso opcional para skills críticos
+
+Convención **opcional** para skills cuyo valor depende de ejemplos concretos
+con diff MAL → BIEN. Esta convención NO es retroactiva: las 63 carpetas
+`recursos/` existentes en `habilidades/` no se renombran. Solo aplica a:
+
+- Skills nuevos cuyo dominio se entiende mejor con ejemplos lado a lado.
+- Skills existentes que reciban actualización mayor y agreguen ejemplos.
+
+---
+
+## Cuándo aplicarla
+
+Aplicar cuando:
+
+- El skill prescribe **decisiones técnicas** o **patrones** cuyo error es
+  sutil sin un caso concreto (ej: anti-patrones de async, gotchas de framework,
+  decisiones arquitecturales).
+- El skill se beneficia de mostrar 2-4 ejemplos lado a lado: el caso aplicado
+  correctamente vs el caso degenerado.
+- Los ejemplos suman > 100 líneas y meterlos en SKILL.md lo pasaría del
+  límite de 300 líneas.
+
+NO aplicar cuando:
+
+- El skill ya tiene `recursos/` con archivos temáticos específicos
+  (ej: `meta-skills-estandar/recursos/anti-patrones-y-leyes.md`). El nombre
+  temático es más informativo que `EXAMPLES.md`.
+- El skill es un how-to procedural sin antipatrones contrastables.
+- El skill tiene < 80 líneas en SKILL.md y los ejemplos caben en línea.
+
+---
+
+## Estructura recomendada
+
+```
+habilidades/<skill-name>/
+├── SKILL.md
+└── recursos/
+    └── EXAMPLES.md
+```
+
+`SKILL.md` enlaza al final con:
+
+```markdown
+Para ejemplos concretos de aplicación, ver [`recursos/EXAMPLES.md`](recursos/EXAMPLES.md).
+```
+
+`EXAMPLES.md` contiene 2-4 ejemplos siguiendo el patrón:
+
+```markdown
+## Ejemplo N — [título corto del escenario]
+
+**Contexto**: [1-2 líneas]
+
+### ❌ Sin <skill-name> (hipotético)
+[código o descripción del enfoque incorrecto + consecuencia observable]
+
+### ✓ Con <skill-name>
+[código o descripción del enfoque correcto + por qué evita la consecuencia]
+```
+
+Cierre de `EXAMPLES.md`: tabla resumen de los ejemplos con la dimensión
+clave que cambió (costo, tiempo, severidad de bug, etc.).
+
+---
+
+## Por qué OPCIONAL y no obligatoria
+
+- 63 carpetas `recursos/` ya existen con nomenclatura temática
+  (`anti-patrones-y-leyes.md`, `frameworks-seguridad.md`,
+  `idiomas-framework.md`). Forzar `EXAMPLES.md` rompería información
+  semántica del nombre.
+- La regla core `reglas/skills-estandar.md` ya prescribe que `SKILL.md`
+  no exceda 300 líneas y que los `recursos/` se nombren en kebab-case
+  con sufijo `.md` — esa regla cubre el 95% de los casos.
+- Esta convención **complementa** la regla core para skills donde un nombre
+  semántico genérico (`EXAMPLES.md`) comunica mejor el contenido que un
+  nombre específico (ej: `casos-decisiones-arquitecturales.md` es más largo
+  y menos buscable).
+
+---
+
+## Origen
+
+Patrón observado en repos externos analizados el 2026-05-09
+(`temp/agent-skills-main`, `temp/andrej-karpathy-skills-main`):
+varios skills críticos exponen un `EXAMPLES.md` con diffs MAL/BIEN
+auto-cargable como referencia rápida del agente.
+
+Adoptado en `habilidades/doubt-driven-review/recursos/EXAMPLES.md` como
+primera aplicación. Casos futuros: skills de decisiones arquitecturales,
+seguridad, debugging avanzado.