# Referencia Completa — Protocolo de Auto-Evolución

## Métricas de Evolución del Sistema

El sistema rastrea estas métricas para medir su propia salud evolutiva:

```yaml
# metricas/evolucion.yml — actualizado por el verificador
metricas:
  skills:
    total: 40
    actualizados_ultimo_mes: 3
    con_version_semver: 15
    sin_version: 25  # Deuda técnica a reducir
    promedio_antiguedad_dias: 127

  errores_recurrentes:
    # Errores que el sistema ya conoce y previene
    prevenidos: 23
    # Errores nuevos observados este mes
    nuevos_este_mes: 2
    # Errores que se convirtieron en reglas del CLAUDE.md
    promovidos_a_reglas: 8

  evoluciones:
    total_historico: 47
    tipo:
      parche: 31
      menor: 12
      mayor: 4
    por_agente:
      verificador: 28
      desarrollador: 8
      revisor: 11
    tasa_exito: "94%"  # Cambios que resolvieron el problema observado

  tiempo_respuesta:
    error_a_parche_promedio_horas: 2.3
    error_a_menor_promedio_dias: 5.1
    error_a_mayor_promedio_dias: 21.0
```

---

## Changelog — Plantilla Estándar

Cada skill con versión semver mantiene un `CHANGELOG.md`:

```markdown
# Changelog — fastapi-python

## [2.1.0] — 2026-03-20

### Agregado
- Sección "Streaming Responses" con ejemplos de `StreamingResponse` y SSE.
- Regla anti-error: `GET endpoints NUNCA hacen db.commit()`.
- Ejemplo de `BackgroundTasks` para procesamiento asíncrono post-response.

### Cambiado
- Actualizado ejemplo de `Depends` para usar sintaxis de Python 3.10+.

## [2.0.1] — 2026-02-15

### Corregido
- Ejemplo de `selectinload` tenía typo en nombre de relación (`childen` → `children`).
- Clarificado que `db.flush()` no hace commit — confundía al desarrollador.

## [2.0.0] — 2026-01-10

### Cambiado (BREAKING)
- Cambiada convención de nombres de endpoints: `/api/v1/usuarios` → `/v1/api/usuarios`.
  **Migración requerida**: actualizar rutas en todos los proyectos existentes.

### Eliminado
- Ejemplos con Pydantic v1 — sistema usa Pydantic v2 exclusivamente.
```

---

## Proceso de Retroalimentación del Verificador

El verificador es el agente con mayor responsabilidad evolutiva porque
es quien observa el output real del desarrollador.

```markdown
## Protocolo del Verificador — Aprendizaje Continuo

Al finalizar la verificación de un PR, el verificador DEBE:

1. **Identificar gaps de skill**: ¿El desarrollador cometió un error
   que un skill existente debería prevenir pero no previene?

2. **Clasificar el gap**:
   - Skill inexistente → proponer nuevo skill al planificador.
   - Skill existe pero no cubre el caso → generar propuesta PARCHE/MENOR.
   - Error ya en el skill pero desarrollador no lo siguió → no es gap del skill.

3. **Registrar en VERIFICACION.md**:
   ```markdown
   ## Gaps de Skills Identificados
   - GAP-001: El skill `angular-avanzado` no cubre NG8107 (optional chaining en signals)
     Propuesta: PARCHE, agregar sección con ejemplo MAL/BIEN
     Archivo: habilidades/angular-avanzado/SKILL.md
   ```

4. **Auto-aplicar PARCHEs** si pasan los safety checks.
   Para MENORES y MAYOREs, documentar y pasar al planificador.
```

---

## Rollback — Revertir un Cambio Evolutivo

```bash
# Todo cambio evolutivo se hace en un commit atómico con mensaje estandarizado
# git commit -m "evolucion(angular-avanzado): agregar sección NG8107 [PATCH 1.0.1→1.0.2]"

# Rollback es simplemente revertir el commit
# git revert <hash-del-commit-evolutivo>

# Registro de rollback
cat >> metricas/rollbacks.md << 'EOF'
## Rollback 2026-03-25

- **Commit revertido**: abc123f
- **Cambio original**: Sección NG8107 en angular-avanzado
- **Razón del rollback**: El ejemplo agregado era incorrecto para Angular v18
- **Solución**: Re-proponer con ejemplo corregido
- **Agente responsable**: verificador
EOF
```

---

## Checklist de Revisión Completo — Auto-Evolución

- [ ] El cambio tiene al menos 2 instancias de evidencia observada.
- [ ] La versión semver del artefacto fue actualizada correctamente.
- [ ] El CHANGELOG.md fue actualizado con descripción del cambio.
- [ ] Los safety checks fueron ejecutados y pasaron.
- [ ] El nivel de autorización requerido fue respetado (PARCHE/MENOR/MAYOR).
- [ ] El cambio tiene plan de rollback documentado.
- [ ] El commit tiene el formato estándar `evolucion(nombre): descripción [TIPO v.ant→v.nue]`.
- [ ] Las métricas de evolución fueron actualizadas en `metricas/evolucion.yml`.
- [ ] No hay contradicciones introducidas con otros skills o reglas del sistema.
