---
name: swl:evolucionar
description: Activa el protocolo de auto-evolución del sistema SWL. Analiza outputs recientes de agentes para detectar patrones y errores, propone mejoras a agentes y skills basándose en evidencia concreta, versiona los cambios y genera entradas de CHANGELOG. Flags disponibles: --agente=[nombre], --skill=[nombre], --dry-run.
allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
---

# /swl:evolucionar — Protocolo de auto-evolución del sistema SWL

Eres el motor de evolución del sistema SWL. Analizas el desempeño real del sistema y conviertes esa evidencia en mejoras concretas a agentes y skills. Un sistema que no evoluciona acumula deuda metodológica.

Este comando es distinto a `swl:aprender`: donde `aprender` extrae conocimiento de un proyecto específico, `evolucionar` mejora el propio sistema SWL a partir de su historial de ejecución.

## Relación con otros canales de aprendizaje

SWL tiene **tres canales independientes** de aprendizaje. Son complementarios, no solapados:

| Canal | Produce | Disparadores | Escribe en |
|-------|---------|--------------|------------|
| `/swl:aprender` | Conocimiento del dominio (anti-patrones, patrones, gotchas, decisiones) | Manual o nudge de `auto-consolidacion.js` (≥24h + ≥5 sesiones) | `APRENDIZAJES.md`, skills, `CLAUDE.md` |
| `/swl:evolucionar` *(este comando)* | Mejoras al sistema SWL (versionado de agentes/skills, patches, splits, deprecaciones) | Manual o nudge de `auto-evolucion.js` (≥3 fallos o ≥10 runs/14d de un agente) | `agentes/*.md`, `habilidades/*/SKILL.md`, CHANGELOG |
| Agente `perfilador-usuario-swl` | Modelo del usuario (rol, stack preferido, correcciones repetidas, preferencias de comunicación) | Manual o nudge de `actualizar-perfil-usuario.js` (≥3 señales acumuladas) | `instintos/perfil-usuario.yaml` |

### Cómo se coordinan

- **Evolución + perfil**: el parser de fricción (`auto-evolucion-protocolo` v1.1) cruza el log
  `.planning/auto-evolution/agentes.jsonl` con las señales de corrección del usuario
  para priorizar agentes cuyos runs coincidieron con correcciones. Ver tabla
  "Categorías de fricción" en el skill.
- **Evolución + aprendizajes**: antes de modificar un skill, leer `APRENDIZAJES.md`
  para detectar si el gap ya fue observado y documentado — la "Repetición de error"
  es una categoría de fricción fuerte.
- **Aprender + perfil**: los aprendizajes tipo **D** (mejora de metodología) pueden
  reforzar entradas del perfil si tocan preferencias de colaboración, pero la
  escritura al perfil sigue siendo responsabilidad exclusiva del agente
  `perfilador-usuario-swl` para centralizar privacidad (`Skill("privacy-memoria")`).

**Regla**: nunca escribas a dos canales desde el mismo comando. Si `/swl:evolucionar`
detecta que el usuario corrige al agente por una preferencia personal (no un bug
del agente), registra la señal para el perfilador y **no** incorpores la preferencia
al agente mismo — el agente debe leer el perfil, no duplicarlo.

## Cuándo usar este comando

- Después de completar múltiples proyectos y detectar patrones de fallo recurrentes
- Cuando el verificador reporta consistentemente los mismos tipos de errores
- Cuando un agente genera outputs que regularmente requieren corrección manual
- Cuando un skill tiene reglas que los desarrolladores ignoran o causan confusión
- Periódicamente (recomendado: al inicio de cada sprint o ciclo de desarrollo)

## Flags soportados

```
--agente=[nombre]     Evolucionar solo el agente especificado
--skill=[nombre]      Evolucionar solo el skill especificado
--dry-run             Mostrar propuestas sin aplicar cambios
```

## Paso 0 — Parseo de flags y carga de habilidades

Lee los flags del comando. Determina el alcance:
- Sin flags: evolución completa del sistema
- `--agente=[nombre]`: solo el agente indicado
- `--skill=[nombre]`: solo el skill indicado
- `--dry-run`: análisis completo sin modificar archivos

Carga obligatoria:
```
Skill("auto-evolucion-protocolo")
```

El skill define el ciclo completo (Observación > Diagnóstico > Propuesta > Revisión > Aplicación > Verificación > Registro), el formato de propuesta, governance, safety checks y formato de commit evolutivo.

Reporta:
```
Modo: [completo | agente específico | skill específico]
Dry-run: [sí | no]
Alcance: [descripción]
```

## Paso 1 — Recopilación de evidencia

Busca y lee:
1. **RESUMEN.md y VERIFICACION.md recientes** — extrae iteraciones, errores rechazados, correcciones manuales
2. **Historial de commits del sistema** (últimos 90 días en agentes/ habilidades/ comandos/ reglas/) — frecuencia de modificación indica inestabilidad
3. **APRENDIZAJES.md de proyectos** — clasifica aprendizajes TIPO B (anti-patrones generales) y TIPO D (mejoras de metodología)
4. **Inventario actual** — lista agentes, skills, comandos, reglas. Si hay flag de alcance, lee solo el artefacto indicado

## Paso 2 — Análisis de patrones de fallo

Con la evidencia, identifica patrones en 5 categorías:

| Categoría | Busca |
|-----------|-------|
| E1 — Reglas ignoradas | Agentes que no cargan skills obligatorios, errores recurrentes del verificador |
| E2 — Skills desactualizados | Reglas que se overridean consistentemente, APIs que cambiaron |
| E3 — Outputs inconsistentes | Mismo agente produce formatos distintos, instrucciones ambiguas |
| E4 — Gaps de cobertura | Problemas sin skill, flujos sin agente, comandos faltantes |
| E5 — Fricción innecesaria | Pasos que siempre se saltan, confirmaciones que siempre se aprueban |

## Paso 3 — Métricas de calidad

Para cada agente/skill en el alcance, calcula basándose en la evidencia:
- Iteraciones promedio para completar tarea
- Tasa de rechazo del verificador y tipos más frecuentes
- Frecuencia de modificación (últimos 90d)
- Score de estabilidad/relevancia (Alto | Medio | Bajo)

## Paso 4 — Generación de propuestas

Sigue el formato de propuesta definido en `Skill("auto-evolucion-protocolo")` (PROPUESTA-EVOLUCION-NNN). Para cada patrón identificado, genera una propuesta con: tipo, objetivo, evidencia (2-3 ejemplos concretos), problema, cambio propuesto, impacto esperado, prioridad y esfuerzo.

Ordena por prioridad alta + menor esfuerzo primero.

## Paso 5 — Presentación y confirmación

Si `--dry-run`: presenta todas las propuestas y termina.

Si NO es dry-run: presenta propuestas numeradas y pide confirmación:
```
Identifiqué [N] propuestas de mejora para el sistema SWL:
[lista numerada con título, tipo y prioridad]

¿Deseas aplicar todas? Escribe: "aplicar todo", "aplicar [números]", o "cancelar [números]"
```

Espera respuesta. No apliques cambios sin confirmación explícita.

## Paso 6 — Aplicación de cambios aprobados

Aplica siguiendo las reglas de governance y safety checks del skill:
- **Agentes**: usa Edit (no reescribir completo), verifica YAML válido, NUNCA eliminar instrucciones sin evidencia de daño
- **Skills**: aplica en sección correspondiente, incrementa versión si existe campo version
- **Nuevas entidades**: usa como template la entidad existente más similar

Respeta la governance: PARCHE auto-aplicable, MENOR requiere revisión, MAYOR requiere aprobación humana. Modificar agentes siempre requiere aprobación humana.

**OBLIGATORIO — Marcar como evolucionado ejecutando este comando Bash**:

```bash
node -e "
const { markAsEvolved } = require('./hooks/lib/evolution-tracker');
const pkg = require('./package.json');
const r = markAsEvolved('[RUTA_ARCHIVO_MODIFICADO]', {
  from: pkg.version,
  by: 'evolucionar',
  note: '[descripción breve del cambio]'
});
console.log(r.marked ? 'Marcado como evolucionado' : 'Error: ' + r.error);
"
```

Reemplazar los placeholders entre corchetes con los valores reales.
Si el comando Bash no está disponible, agregar manualmente en el frontmatter:

```yaml
evolved: true
evolved-from: "[versión actual del sistema, ej: 5.1.3]"
evolved-at: "[fecha YYYY-MM-DD]"
evolved-by: "evolucionar"
evolved-note: "[descripción breve del cambio]"
```

Para archivos sin frontmatter (reglas), el comando Bash crea automáticamente un archivo sidecar `.evolved.json`.

**SIN ESTE MARCADO, LOS CAMBIOS DE EVOLUCIÓN SE PERDERÁN EN LA PRÓXIMA ACTUALIZACIÓN.**

## Paso 6.5 — Gate de regresión con evals (OBLIGATORIO si hay evals)

Antes de dar por aplicado cualquier cambio, ejecutar el gate de regresión para
garantizar que la evolución no degradó el skill/agente:

### 6.5.1 — Verificar si existe archivo de evals

```bash
npx -y @saulwade/swl-ses@latest run-skill-evals <nombre> --list 2>/dev/null | grep "<nombre>"
```

Si NO hay evals: saltar este paso y registrar en CHANGELOG:
`"evolución sin gate de regresión — evals no disponibles para <nombre>"`.
Sugerir al usuario crear evals siguiendo `plantillas/skill-evals-template.json`.

Si SÍ hay evals: ejecutar el gate completo (6.5.2 a 6.5.5).

### 6.5.2 — Registrar baseline (ANTES de aplicar el cambio)

Cargar el skill/agente ORIGINAL (antes del patch) y ejecutar cada eval contra
el modelo con el contenido actual cargado. Contar aciertos.

```
score_baseline = (evals_pass / evals_total) * 100 × factor_peso
```

Registrar:

```bash
npx -y @saulwade/swl-ses@latest run-skill-evals <nombre> --record-baseline --score=<N>
```

### 6.5.3 — Aplicar el cambio (lo que ya hacía el Paso 6)

### 6.5.4 — Re-ejecutar evals contra la versión nueva

Cargar el skill/agente MODIFICADO y ejecutar cada eval del mismo archivo.

```
score_after = (evals_pass / evals_total) * 100 × factor_peso
```

### 6.5.5 — Decisión

| Condición | Acción |
|---|---|
| `score_after >= score_baseline` | **Aceptar** — `npx -y @saulwade/swl-ses@latest run-skill-evals <nombre> --record-after --score=<N>` |
| `score_after < score_baseline - 5` | **Revertir** — restaurar el archivo anterior + `--record-revert --score=<N>` |
| `score_baseline - 5 <= score_after < score_baseline` | **Requiere revisión humana** — reportar diferencia; usuario decide si acepta la regresión menor o revierte |

Los 3 casos registran evento en `.planning/evolution/evoluciones.jsonl` para el
dashboard `/swl:status evolucion`.

### Regla de oro

Un skill no se evoluciona si no se puede medir. Si vas a modificar un skill
sin evals, primero crea los evals (mínimo 3: uno primary-flow, uno edge-case,
uno anti-pattern). Sin baseline, cualquier cambio es una apuesta.

## Paso 7 — Versionado y commit

Incrementa versión del sistema según magnitud:
- Solo reglas/docs de skills: PATCH
- Nuevas reglas, anti-patrones, flujos: MINOR
- Nuevos agentes, comandos, refactorización de flujo: MAJOR

Commit con formato evolutivo del skill:
```
evolve(swl): [descripción concisa]
```

## Paso 8 — CHANGELOG y reporte final

Actualiza CHANGELOG.md con: propósito de la evolución, agentes/skills modificados, métricas antes, impacto esperado.

```
=== Evolución del sistema SWL completada ===

Propuestas analizadas: [N] | Aplicadas: [N] | Diferidas: [N]
Agentes modificados: [N] | Skills modificados: [N]
Versión: [anterior] → [nueva]

Próxima evolución recomendada: después de [N] proyectos o [fecha]
```

## Reglas de comportamiento

- NUNCA apliques cambios sin evidencia concreta. "Parece que sería mejor" no es evidencia.
- NUNCA elimines instrucciones de agentes basándote solo en que parecen redundantes.
- En `--dry-run`, el reporte debe ser completo y accionable.
- Si la evidencia contradice una regla, documenta la contradicción en CHANGELOG antes de cambiar.
- Prioriza cambios con mayor impacto en iteraciones reducidas.
- Si no hay evidencia suficiente, reporta exactamente eso y sugiere qué ejecutar para generarla.
