@saulwade/swl-ses 2.3.0 → 2.4.1

package/habilidades/auto-evolucion-protocolo/SKILL.md

@@ -1,276 +1,276 @@
----
-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.
+---
+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.