---
name: auto-evolucion-protocolo
description: >
  Protocolo de auto-evolución del sistema SWL. Cómo los agentes aprenden y se mejoran,
  proponen cambios, versionado semántico de agentes, changelog, métricas de evolución,
  governance de cambios, parser de señales de fricción y safety checks.
version: "1.1.1"
herramientasPermitidas: [Read, Bash, Grep]
evolvable: false  # bloqueado por lista (skill de seguridad/privacidad)
exclusiones:
  - "No cargar para evolución del código de aplicación del usuario (migración de APIs de frameworks, refactors de módulos propios) — para eso cargar el skill del framework correspondiente (`angular-moderno`, `react-optimizacion`, backend-*) o invocar `implementador-swl`."
  - "No cargar para migraciones de schema de base de datos o datos en reposo — para migraciones de persistencia cargar `postgresql-experto` y usar `migrador-swl`."
  - "No cargar para aplicar automáticamente cambios sobre skills o agentes con `evolvable: false` — estos artefactos requieren ADR explícito y decisión humana fuera del ciclo AGP."
  - "No cargar para evoluciones de dependencias externas (bumps de versión, deprecación de librerías) — para eso cargar `dependencias-auditoria` + `deprecacion-migracion`."
---
# Protocolo de Auto-Evolución del Sistema SWL

## Cuándo NO cargar

- La evolución es sobre código de aplicación del usuario (API de un framework cambió, hay que actualizar componentes): cargar el skill del framework (`angular-moderno`, `react-optimizacion`, backend-*) o invocar `implementador-swl`. Este skill es para evolución de artefactos del sistema SWL (agentes, skills, reglas), no del producto.
- La tarea es migrar schemas de base de datos o datos en producción: cargar `postgresql-experto` y delegar a `migrador-swl`. La auto-evolución no cubre migraciones de persistencia — son irreversibles y requieren plan propio.
- El artefacto objetivo tiene `evolvable: false`: este skill NO se auto-aplica sobre artefactos bloqueados. Requiere ADR explícito y edición manual por decisión humana.
- La evolución es un bump de versión de dependencia externa (npm, pip): cargar `dependencias-auditoria` y `deprecacion-migracion`. Este skill cubre evolución de conocimiento interno del sistema, no del árbol de deps.

## ¿Por qué auto-evolución?

El sistema SWL es una colección de agentes y skills que guían la implementación
de software. Con el tiempo, estos artefactos envejecen:
- Los frameworks cambian sus APIs.
- Los equipos descubren nuevos anti-patrones.
- Los errores recurrentes revelan gaps en los skills.
- Los workflows ineficientes se vuelven visibles a través de la práctica.

La auto-evolución es el proceso sistemático por el cual el sistema actualiza su propio
conocimiento de forma controlada, versionada y auditable.

---

## Anatomía de un Cambio Evolutivo

Todo cambio al sistema SWL pasa por este ciclo:

```
Observación → Diagnóstico → Propuesta → Revisión → Aplicación → Verificación → Registro
```

### 1. Observación — ¿Qué triggerea un cambio?

| Trigger | Ejemplo | Prioridad |
|---------|---------|-----------|
| Error recurrente en producción | `MissingGreenlet` en SQLAlchemy aparece 3+ veces | ALTA |
| Nueva versión mayor de framework | Angular v20 cambia la Resource API | ALTA |
| Patrón nuevo identificado | `satisfies` operator mejora type safety | MEDIA |
| Deprecación de API | `*ngIf` eliminado en Angular v21 | ALTA |
| Feedback de desarrollador | "Este skill no cubre migrations con datos" | MEDIA |

### 2. Diagnóstico — ¿Qué está desactualizado exactamente?

Documentar: fecha, observador, error recurrente, síntoma, causa raíz,
artefacto afectado (archivo + línea), severidad del gap.

---

## Versionado Semántico de Agentes y Skills

```
MAYOR.MENOR.PARCHE

MAYOR: cambio que rompe compatibilidad backward con proyectos existentes
       Requiere: aprobación de revisor humano

MENOR: nueva funcionalidad o cobertura de nuevos casos
       Requiere: revisión del plan-checker

PARCHE: corrección de error, clarificación, ejemplo mejorado
        Requiere: auto-aplicable por el verificador
```

---

## Protocolo de Propuesta de Cambio

Formato estándar:

```markdown
# PROPUESTA-EVOLUCION-NNN

## Metadatos
- **Fecha**: YYYY-MM-DD
- **Proponente**: agente
- **Tipo**: PARCHE | MENOR | MAYOR
- **Artefacto**: ruta/al/archivo
- **Urgencia**: Alta | Media | Baja

## Problema Observado
Descripción del error o gap.

## Evidencia
- PR/sesión donde se observó (mínimo 2 instancias)

## Cambio Propuesto
Diff o descripción del cambio.

## Impacto Estimado
Breaking changes, estimación de mejora.

## Verificación Post-Cambio
Cómo verificar que el cambio resolvió el problema.
```

---

## Governance — Quién Puede Cambiar Qué

```yaml
cambios_autonomos:
  - tipo: PARCHE
    condicion: "corrección de ejemplo de código erróneo"
  - tipo: PARCHE
    condicion: "agregar anti-patrón observado 3+ veces"

cambios_con_revision:
  - tipo: MENOR
    condicion: "nueva sección temática en un skill"
    aprobadores: ["planificador"]
  - tipo: MENOR
    condicion: "nuevo skill creado desde cero"
    aprobadores: ["planificador", "revisor"]

cambios_con_aprobacion_humana:
  - tipo: MAYOR
    condicion: "cambio de convención que afecta código existente"
  - tipo: cualquiera
    condicion: "modificar agentes (no skills)"
  - tipo: cualquiera
    condicion: "cambiar reglas en CLAUDE.md"
```

---

## Safety Checks — Antes de Aplicar un Cambio

Todo agente que proponga modificar un artefacto del sistema DEBE verificar:

1. **Consistencia**: Un PARCHE no modifica más de 50 líneas
2. **Scope**: Modificar agentes requiere aprobación humana
3. **Evidencia**: Mínimo 2 instancias de evidencia para un cambio
4. **Reversibilidad**: Todo cambio tiene un plan de rollback documentado
5. **No contradicciones**: El cambio no contradice otros skills o reglas

---

## Formato de Commit Evolutivo

```
evolucion(nombre-artefacto): descripción [TIPO v.anterior→v.nueva]
```

Rollback: `git revert <hash-del-commit-evolutivo>`

---

## Escalera de Adquisición de Capacidades

Cuando se identifica un patrón útil, la tentación es saltar de "lo resolví una vez"
a "crear un skill". Pero la maduración tiene niveles intermedios. Saltar niveles
produce skills frágiles que no se activan, workflows sin verificación y automatizaciones
que fallan silenciosamente.

| Nivel | Nombre | Qué implica | Criterio para avanzar al siguiente |
|-------|--------|-------------|-----------------------------------|
| 1 | **Solución ad hoc** | Se resolvió el problema una vez, en una sesión | El mismo problema aparece en otra sesión |
| 2 | **Repetible** | Pasos documentados en ESTADO.md o DECISIONS.md | Se ejecutó 3+ veces con éxito siguiendo los pasos |
| 3 | **Skill** | Codificado en SKILL.md con gotchas y restricciones | El skill se activa correctamente y cambia comportamiento (3-arm test) |
| 4 | **Workflow** | Orquestación multi-agente con delegación definida | Los agentes completan el flujo sin intervención manual en 70%+ |
| 5 | **Harness determinista** | Scripts en `scripts/` que validan output automáticamente | La validación detecta 90%+ de los errores conocidos |
| 6 | **Cobertura evaluativa** | Métricas pass@k registradas en EVALUACION.md | pass@1 ≥ objetivo del tipo de agente durante 10+ ejecuciones |
| 7 | **Automatizado** | Hook o cron que dispara la capacidad sin invocación manual | El hook se ejecuta sin errores en 95%+ de las veces |
| 8 | **Monitoreado** | Métricas observables: latencia, tasa de error, drift | Dashboards activos y alertas configuradas |
| 9 | **Autónomo con evidencia** | El sistema decide cuándo usar la capacidad basado en métricas, no en heurísticas | Decisiones autónomas acertadas en 85%+ |
| 10 | **Empaquetado** | Reutilizable entre proyectos como plugin o módulo independiente | Funciona en 2+ proyectos distintos sin modificación |

**Cómo usar**: Al proponer una evolución, identificar en qué nivel está la capacidad
actual y proponer avanzar **un solo nivel**. Saltar niveles requiere justificación
explícita en la propuesta de evolución — la mayoría de las veces es síntoma de
optimismo injustificado.

Para métricas de evolución, plantilla de changelog, proceso de retroalimentación
del verificador y checklist completo de revisión,
ver [recursos/referencia-completa.md](recursos/referencia-completa.md).

---

## Parser de señales de fricción (v1.1)

El hook `hooks/lib/etapa-auto-evolucion.js` (SubagentStop) alimenta el log
`.planning/auto-evolution/agentes.jsonl` y emite *nudges* hacia
`auto-evolucion-swl` cuando detecta umbrales cruzados. Este skill define
**qué cuenta como fricción** para que el agente tenga criterio uniforme al
interpretar el log.

### Categorías de fricción

| Categoría | Fuente | Fuerza | Contraseña en el log |
|-----------|--------|--------|----------------------|
| **Fallo duro** | Subagente terminó con `is_error:true` o excepción | Alta | `status: "failed"` |
| **Run vacío** | Subagente terminó sin producir cambios útiles (0 Edit/Write) | Media | `toolCalls < 3` en agente de implementación |
| **Trivial recurrente** | 10+ runs triviales (≤5 tool calls) del mismo agente | Baja | `trivial: true` |
| **Corrección del usuario** | Mensaje del usuario con keywords de corrección en el turno posterior al run | Alta | detectada por `etapa-perfil-usuario.js` |
| **Repetición de error** | Mismo tipo de error documentado ya en `APRENDIZAJES.md` | Alta | cruzar log con grep |
| **Reintento manual** | Usuario vuelve a invocar el mismo agente con instrucciones ajustadas | Media | comparar `session_id` + `agente` consecutivos |

### Keywords de corrección (es-MX)

Reutilizar la lista definida en `hooks/lib/etapa-perfil-usuario.js`:

```
KEYWORDS_CORRECCION = [
  'no así', 'no asi', 'mejor', 'en vez de', 'en lugar de',
  'evita', 'evites', 'no uses', 'nunca uses', 'nunca hagas',
  'siempre quiero', 'siempre usa', 'prefiero', 'prefiere',
  'no me gusta', 'deja de',
]
```

Si el mensaje del usuario inmediatamente posterior a un SubagentStop contiene
≥1 keyword de esta lista, **el último agente registrado hereda un punto de
fricción** en el reporte del próximo `/swl:evolucionar`.

### Cómo usar el log al evolucionar

Al invocar `auto-evolucion-swl` o `/swl:evolucionar <agente>`:

1. **Leer el log filtrado por agente:**
   ```bash
   grep "\"agente\":\"<nombre>\"" .planning/auto-evolution/agentes.jsonl | tail -50
   ```

2. **Cuantificar las 6 categorías** (fallo duro, run vacío, trivial recurrente,
   corrección, repetición, reintento).

3. **Priorizar la hipótesis de evolución** según la categoría dominante:

   | Categoría dominante | Hipótesis más probable |
   |---------------------|------------------------|
   | Fallo duro | Skills faltantes o instrucciones ambiguas del agente |
   | Corrección del usuario | Contradicción entre el comportamiento del agente y el perfil/instintos |
   | Repetición de error | Gap en `APRENDIZAJES.md` que no fue promovido a skill |
   | Trivial recurrente | El agente se invoca para trabajo que debería ir a uno más liviano (Haiku) |
   | Reintento manual | Prompts del agente con defaults malos; faltan preguntas de clarificación |

4. **Aplicar la escalera de adquisición** de capacidades (sección anterior)
   para decidir si el arreglo es un patch del skill, un skill nuevo, o un
   agente nuevo.

### Límites del parser

- **No interpretar sentimiento** ("esto está mal" es ambiguo; requiere contexto).
- **No evolucionar por 1 señal** sin importar la fuerza — mínimo 3 señales
  correlacionadas o 1 corrección explícita en CLAUDE.md.
- **No modificar agentes con `nivelRiesgo: ALTO`** automáticamente — siempre
  requieren confirmación humana (ver CLAUDE.md regla de privilegio mínimo).
- **No borrar entradas del log** — el log es append-only auditoría.

### Gotchas / Errores comunes no obvios

- **Saltar niveles de la escalera de adquisición**: proponer crear un skill nuevo cuando la capacidad está en nivel 1 ("se resolvió una vez") produce skills frágiles que no se activan y workflows sin verificación. Causa: la presión por capturar el patrón rápido ignora que cada nivel exige un criterio medible para avanzar. Solución: identificar el nivel actual según la tabla, proponer avanzar un solo nivel, y si se salta, justificar explícitamente en la propuesta por qué no es optimismo injustificado.
- **Evolucionar por 1 señal aislada**: aplicar un cambio tras detectar un solo fallo duro o una sola trivial recurrente produce churn sobre el artefacto sin evidencia real. Causa: el parser emite nudges por umbral cruzado, pero un nudge individual no prueba un patrón. Solución: requerir mínimo 3 señales correlacionadas del log o 1 corrección explícita en CLAUDE.md antes de redactar la propuesta; documentar ambas evidencias en el campo "Evidencia" de PROPUESTA-EVOLUCION.
- **Auto-aplicar sobre agentes con `nivelRiesgo: ALTO`**: el ciclo automatizado puede intentar modificar agentes de alto riesgo si el gate de governance no se consulta primero, violando el principio de privilegio mínimo de CLAUDE.md. Causa: los cambios tipo PARCHE son auto-aplicables por default, pero esa regla aplica a skills — no a agentes de alto riesgo. Solución: antes de aplicar cualquier cambio, verificar el frontmatter del artefacto; si es agente con `nivelRiesgo: ALTO` o si el artefacto tiene `evolvable: false`, escalar a aprobación humana sin importar el tipo de bump.
- **Interpretar sentimiento del usuario como señal de fricción**: capturar frases ambiguas ("esto está mal", "no me convence") como corrección atribuible al último agente produce evoluciones por ruido semántico. Causa: el parser reconoce solo keywords concretas de corrección; ampliar la lista por interpretación lleva a falsos positivos. Solución: usar exclusivamente la lista `KEYWORDS_CORRECCION` definida en `hooks/lib/etapa-perfil-usuario.js`; si el mensaje es ambiguo, no imputar fricción y esperar la siguiente señal.

### CHANGELOG del skill

- **v1.1.0** (2026-04-18): añadido parser de señales de fricción y tabla de
  categorías. Cierra gap "skill autoevolutiva tras cada tarea" vs. Hermes.
- **v1.0.0**: versión inicial del protocolo.
