---
name: swl:reflect-skills
description: Analiza el historial de sesiones de Claude Code para detectar patrones de uso repetidos que sean candidatos a convertirse en nuevos skills, comandos o agentes del sistema SWL. Inspirado en el patrón Reflect de claude-reflect (Karpathy). Sin dependencias externas.
allowed_tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
---

# /swl:reflect-skills — Descubrimiento de skills emergentes

Analiza los archivos JSONL del historial de Claude Code (`~/.claude/projects/<proyecto>/*.jsonl`) y la cola de feedback del usuario (`.planning/evolucion/feedback-queue.jsonl`) para detectar intenciones repetidas que podrían formalizarse como skills, comandos o agentes nuevos del sistema SWL.

Complementa a `/swl:aprender` (que trabaja sobre la sesión actual) y a `/swl:evolucionar` (que opera sobre metadatos de agentes/skills existentes). Este comando mira el **historial acumulado** y propone componentes emergentes basándose en la frecuencia real de uso.

## Cuándo usar este comando

- Cada 2-4 semanas, para identificar nuevos dominios donde el usuario está pidiendo cosas recurrentes sin un skill dedicado.
- Antes de publicar una versión MINOR del sistema SWL, para decidir si vale la pena formalizar algún patrón emergente.
- Después de un proyecto grande, para extraer el know-how ganado como componentes reutilizables.
- Cuando `auto-evolucion.js` reporte alta densidad de acciones sin skill asociado.

## Cuándo NO usar

- Para extraer aprendizajes de la sesión actual → usar `/swl:aprender`.
- Para mejorar un agente/skill existente basado en métricas de fallo → usar `/swl:evolucionar`.
- Para actualizar el perfil del usuario → usar el agente `perfilador-usuario-swl`.
- Para buscar conocimiento ya registrado → usar `/swl:wiki query` o `Skill("memoria-busqueda")`.

## Flujo

### Paso 1 — Ejecutar el análisis

Corre el script determinista que lee los JSONL del proyecto actual y clusteriza intenciones:

```bash
npx -y @saulwade/swl-ses@latest reflect-skills --ventana=30 --umbral=3
```

Parámetros:
- `--ventana N` — días de historial a analizar (default: 30)
- `--umbral N` — mínimo de ocurrencias para reportar cluster (default: 3)
- `--json` — salida estructurada en JSON

El script produce:
- Reporte textual en stdout
- Archivo estructurado en `.planning/evolucion/reflect-skills-report.json`

### Paso 2 — Leer y clasificar los candidatos

Lee el reporte generado y clasifica cada candidato en una de estas categorías:

| Categoría | Acción recomendada |
|-----------|-------------------|
| Patrón técnico nuevo (ej. "integrar redis cache") | Proponer como skill en el dominio correspondiente (`backend-`, `frontend-`, etc.) |
| Operación repetida con pasos fijos (ej. "ejecuta pruebas de carga") | Proponer como comando `/swl:<nombre>` |
| Tarea que cruza varios agentes (ej. "audita dependencias + actualiza CHANGELOG") | Proponer como flujo del `orquestador-swl` |
| Corrección del usuario repetida | Enviar al `perfilador-usuario-swl` |
| Falso positivo (prompt genérico, ruido) | Ignorar y anotar en la bitácora del comando |

### Paso 3 — Validar con el usuario

Presenta al usuario los top 3-5 candidatos con:
- Nombre propuesto y tipo (skill / comando / flujo)
- Cantidad de ocurrencias en la ventana
- 2-3 ejemplos de prompts reales
- Justificación de por qué formalizarlo

**Esperar aprobación explícita** antes de generar componentes. No crear skills automáticamente sin confirmación.

### Paso 4 — Crear los componentes aprobados

Para cada candidato aprobado:

- **Skill**: invocar `/swl:crear-skill` con el dominio correspondiente.
- **Comando**: delegar al agente `orquestador-swl` para crear `comandos/swl/<nombre>.md` siguiendo la plantilla.
- **Flujo**: delegar al `auto-evolucion-swl` para proponer evolución al orquestador.

Registrar la decisión en `.planning/APRENDIZAJES.md` bajo la sección **Patrones emergentes**.

### Paso 5 — Cerrar ciclo

- Actualizar `CLAUDE.md` si se agregó un componente al sistema (tabla de comandos, skills por dominio).
- Bumpar versión del sistema si procede (MINOR para skill/comando nuevo, ver `git-workflow.md`).
- Commit atómico con mensaje: `feat(sistema): agrega <componente> desde /swl:reflect-skills`.

## Salida esperada

Reporte legible como:

```
━━━ Reflect Skills — análisis de historial ━━━
  Ventana: últimos 30 días
  Prompts analizados: 412
  Umbral de repetición: 3

  2 candidato(s) detectado(s):

  1. [SKILL] redis-cache-integrar
     Intención: "integrar redis" (5×)
     Motivo: Intención "integrar redis" repetida 5× → candidato a skill que encapsule el patrón.
     Ejemplos:
       • integra redis como cache layer en el endpoint de productos
       • integrar redis con invalidation por tags
       • quiero integrar redis stream para workers

  2. [COMANDO] release-verificar
     Intención: "verificar release" (4×)
     Motivo: Verbo operativo "verificar" repetido 4× → candidato a automatización por comando slash.
     Ejemplos:
       • verifica que el release esté listo
       • verificar release antes de publicar
       • verificar release 5.10.5

  Feedback del usuario capturado: 7 entradas
    - correccion: 3
    - preferencia: 2
    - memoria: 2
  → Revisar con perfilador-usuario-swl y /swl:aprender.
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

## Notas

- El clustering es heurístico (tokens + verbos de acción), **no semántico con embeddings**. Busca simplicidad y zero-deps sobre precisión absoluta.
- Si un candidato tiene nombre similar a un skill/comando existente, revisar primero si se puede **extender** en lugar de crear uno nuevo.
- El comando NO escribe a APRENDIZAJES.md automáticamente — el usuario decide qué formalizar.
- Para el modo con embeddings (SentenceTransformers + ChromaDB), ver `Skill("wiki-conocimiento")` y `/swl:wiki` que ya implementan el patrón Karpathy completo.
