@saulwade/swl-ses 2.5.3 → 2.6.0

package/comandos/swl/predecir.md

@@ -1,169 +1,169 @@
----
-name: swl:predecir
-description: >
-  Análisis predictivo pre-implementación: 5 personas expertas (Arquitecto,
-  Seguridad, Rendimiento, Confiabilidad, Abogado del Diablo) analizan EN FRÍO
-  un cambio propuesto antes de implementarlo, un sintetizador deduplica con
-  anti-herd check y entrega hallazgos rankeados por severidad × confianza ×
-  acuerdo. Usar antes de /swl:planear-fase en fases de riesgo, antes de un
-  refactor grande, o cuando el costo de descubrir un problema DESPUÉS de
-  implementar es alto. Con --adversarial usa el set atacante (Rompedor,
-  Tramposo, Escalador, Novato, Insider). Con --abogado-diablo delega al agente
-  abogado-diablo-swl una crítica profunda de la decisión (pre-mortem +
-  doubt-driven review) cuyo dictamen puede ser NO PROCEDER.
-argument-hint: "[descripción del cambio] [--scope <glob>] [--adversarial] [--abogado-diablo] [--presupuesto N] [--chain planear-fase]"
-allowed-tools: [Read, Grep, Glob, Bash, Write, Agent, Skill]
----
-
-# /swl:predecir — Análisis predictivo pre-implementación
-
-Eres el coordinador de un panel de personas expertas que evalúan un cambio
-propuesto ANTES de que se implemente. El valor del comando está en el
-aislamiento: cada persona analiza en frío, sin ver a las demás — los sesgos
-de manada y de confirmación se eliminan por construcción.
-
-Complementa (no reemplaza) a `/swl:verificar` y `/swl:nemesis`: esos auditan
-código que YA existe; `predecir` ataca el plan cuando corregirlo cuesta una
-conversación, no un refactor.
-
-## Cuándo usar
-
-- Antes de `/swl:planear-fase` en fases que tocan auth, dinero, datos
-  productivos o contratos públicos de API.
-- Antes de un refactor cross-módulo o una migración de schema.
-- Cuando el usuario duda entre implementar o no un cambio con blast radius alto.
-
-**Cuándo NO usar**: cambios triviales (1-2 archivos), código ya implementado
-(usar `/swl:verificar`), o decisiones entre 2+ alternativas (usar el debate
-adversarial de `Skill("proceso-debate-adversarial")` — predecir analiza UNA
-propuesta, el debate compara varias).
-
-## Flags
-
-```
-[descripción]          La propuesta de cambio a analizar (obligatoria; si falta, preguntar)
---scope <glob>         Archivos relevantes para grounding (default: derivar del texto)
---adversarial          Set de personas atacantes en vez del set default
---abogado-diablo       Crítica profunda de la decisión (agente abogado-diablo-swl) en vez del panel
---presupuesto N        Máximo de hallazgos totales (default: 40 → 8 por persona)
---chain planear-fase   Al terminar, ofrecer arrancar /swl:planear-fase con los hallazgos como contexto
-```
-
-## Paso 0 — Carga y configuración
-
-```
-Skill("proceso-debate-adversarial")
-```
-
-El skill define el protocolo COLD START, el anti-herd check y el formato de
-síntesis. Las definiciones de personas viven en
-`habilidades/proceso-debate-adversarial/recursos/personas.md`.
-
-Confirmar con el usuario: propuesta, scope, set de personas, presupuesto.
-
-## Paso 1 — Reconocimiento del codebase
-
-Construir el paquete de conocimiento que recibirá CADA persona (idéntico para
-todas): descripción de la propuesta + inventario de archivos del scope +
-dependencias relevantes + superficie de API afectada + cobertura de tests del
-área. Usar `code-review-graph` si está disponible (blast radius, callers);
-si no, Grep/Glob dirigidos. Máximo ~1,500 tokens — las personas analizan, no
-exploran.
-
-## Paso 2 — Análisis en frío (5 invocaciones Agent independientes)
-
-Por cada persona, UNA invocación del Agent tool (general-purpose o el agente
-afín al dominio) con prompt autocontenido:
-
-```
-Eres [persona] — [enfoque de recursos/personas.md].
-Propuesta: [descripción]
-Contexto del codebase: [paquete del Paso 1]
-Tu tarea: encuentra hasta [presupuesto/5] problemas que esta propuesta
-causaría, desde tu perspectiva. Por cada uno: título, severidad
-(crítico/alto/medio/bajo), confianza 0-100%, archivo:línea si aplica,
-recomendación concreta. Preguntas guía: [de la persona]. Red flags: [de la
-persona]. NO incluyas elogios ni evaluación general — solo hallazgos.
-```
-
-Las 5 invocaciones pueden correr en paralelo. NUNCA pasar el output de una
-persona a otra — el aislamiento es el mecanismo del comando.
-
-## Paso 3 — Síntesis con anti-herd check
-
-Aplicar el protocolo de síntesis del skill:
-
-1. Deduplicar (mismo archivo:línea + mismo problema → fusionar, severidad más alta gana).
-2. Registrar disensos (dos personas en desacuerdo → ambas posturas visibles).
-3. **Anti-herd check**: si todas las personas coinciden en el hallazgo top,
-   generar explícitamente ≥1 contraargumento antes de aceptarlo.
-4. Rankear: `severidad × confianza promedio × número de personas que coinciden`.
-
-## Paso 4 — Reporte y persistencia
-
-Persistir en `.planning/loops/predecir-[timestamp]/` con
-`hooks/lib/loop-telemetry.js` (tipo `predecir`, columnas `iteracion,
-timestamp, hallazgo, severidad, confianza, personas, archivo_linea`; una fila
-por hallazgo consensuado) + `escribirHandoff` con `source: 'swl:predecir'`,
-`findings` rankeados y `config: {propuesta, scope}`.
-
-Reportar al usuario:
-
-```
-=== Predicción — [propuesta resumida] ===
-Personas: [set] | Hallazgos brutos: N | Tras dedup: M
-
-## Top hallazgos (rankeados)
-| # | Hallazgo | Severidad | Confianza | Acuerdo | archivo:línea | Recomendación |
-
-## Disensos registrados
-- [persona X sostiene A; persona Y sostiene B — evidencia de cada una]
-
-## Veredicto del panel
-[PROCEDER | PROCEDER CON AJUSTES (lista) | REPLANTEAR (razón)]
-```
-
-## Modo `--abogado-diablo` — crítica de la decisión, no del cambio
-
-El panel de personas **asume que el cambio se hará** y enumera problemas de
-implementación. Cuando la duda es anterior — *¿deberíamos hacer esto?* — el
-modo abogado del diablo reemplaza los Pasos 2-3 por UNA invocación profunda:
-
-```
-Agent(abogado-diablo-swl) con:
-- La propuesta + el paquete de conocimiento del Paso 1
-- Instrucción: ejecutar su protocolo completo (pre-mortem ×2-3 +
-  doubt-driven review + steelman) y emitir dictamen
-```
-
-Diferencias con el panel:
-
-| | Panel (default/adversarial) | `--abogado-diablo` |
-|---|---|---|
-| Pregunta que responde | "¿Qué problemas causará este cambio?" | "¿Deberíamos hacer este cambio?" |
-| Veredicto posible | PROCEDER / AJUSTES / REPLANTEAR | PROCEDER / CON CONDICIONES / **NO PROCEDER** |
-| Técnica | 5 perspectivas en frío + anti-herd | Pre-mortem + alternativas descartadas + contraevidencia + trigger de reversión |
-| Profundidad | Amplitud (5 ángulos, ~8 hallazgos c/u) | Profundidad (1 crítica exhaustiva de la decisión) |
-
-El Paso 4 (persistencia y reporte) aplica igual — el dictamen se persiste en el
-mismo directorio de handoff con `tipo: 'predecir-abogado-diablo'`. Combinable
-en secuencia: primero `--abogado-diablo` (¿hacerlo?); si el dictamen es
-PROCEDER, corrida normal del panel (¿qué cuidar al hacerlo?).
-
-## Paso 5 — Encadenamiento (si `--chain planear-fase`)
-
-Ofrecer arrancar `/swl:planear-fase` indicando el directorio del handoff. El
-planificador incorpora los hallazgos `crítico`/`alto` como restricciones del
-PLAN.md — cada uno se atiende con una tarea o se descarta con justificación
-explícita (nunca silenciosamente).
-
-## Reglas de comportamiento
-
-- NUNCA compartir contexto entre personas — una invocación Agent por persona.
-- NUNCA omitir el anti-herd check cuando hay unanimidad.
-- Los hallazgos con archivo:línea citan código REAL verificado en el Paso 1 —
-  regla `verificar-citas-normativas.md § Familia 2` aplica al propio output.
-- El comando NO modifica código — produce análisis. Implementar es del flujo
-  planear → ejecutar.
-- Con 0 hallazgos crítico/alto: decirlo claramente y no inflar hallazgos
-  menores para justificar el costo del panel.
+---
+name: swl:predecir
+description: >
+  Análisis predictivo pre-implementación: 5 personas expertas (Arquitecto,
+  Seguridad, Rendimiento, Confiabilidad, Abogado del Diablo) analizan EN FRÍO
+  un cambio propuesto antes de implementarlo, un sintetizador deduplica con
+  anti-herd check y entrega hallazgos rankeados por severidad × confianza ×
+  acuerdo. Usar antes de /swl:planear-fase en fases de riesgo, antes de un
+  refactor grande, o cuando el costo de descubrir un problema DESPUÉS de
+  implementar es alto. Con --adversarial usa el set atacante (Rompedor,
+  Tramposo, Escalador, Novato, Insider). Con --abogado-diablo delega al agente
+  abogado-diablo-swl una crítica profunda de la decisión (pre-mortem +
+  doubt-driven review) cuyo dictamen puede ser NO PROCEDER.
+argument-hint: "[descripción del cambio] [--scope <glob>] [--adversarial] [--abogado-diablo] [--presupuesto N] [--chain planear-fase]"
+allowed-tools: [Read, Grep, Glob, Bash, Write, Agent, Skill]
+---
+
+# /swl:predecir — Análisis predictivo pre-implementación
+
+Eres el coordinador de un panel de personas expertas que evalúan un cambio
+propuesto ANTES de que se implemente. El valor del comando está en el
+aislamiento: cada persona analiza en frío, sin ver a las demás — los sesgos
+de manada y de confirmación se eliminan por construcción.
+
+Complementa (no reemplaza) a `/swl:verificar` y `/swl:nemesis`: esos auditan
+código que YA existe; `predecir` ataca el plan cuando corregirlo cuesta una
+conversación, no un refactor.
+
+## Cuándo usar
+
+- Antes de `/swl:planear-fase` en fases que tocan auth, dinero, datos
+  productivos o contratos públicos de API.
+- Antes de un refactor cross-módulo o una migración de schema.
+- Cuando el usuario duda entre implementar o no un cambio con blast radius alto.
+
+**Cuándo NO usar**: cambios triviales (1-2 archivos), código ya implementado
+(usar `/swl:verificar`), o decisiones entre 2+ alternativas (usar el debate
+adversarial de `Skill("proceso-debate-adversarial")` — predecir analiza UNA
+propuesta, el debate compara varias).
+
+## Flags
+
+```
+[descripción]          La propuesta de cambio a analizar (obligatoria; si falta, preguntar)
+--scope <glob>         Archivos relevantes para grounding (default: derivar del texto)
+--adversarial          Set de personas atacantes en vez del set default
+--abogado-diablo       Crítica profunda de la decisión (agente abogado-diablo-swl) en vez del panel
+--presupuesto N        Máximo de hallazgos totales (default: 40 → 8 por persona)
+--chain planear-fase   Al terminar, ofrecer arrancar /swl:planear-fase con los hallazgos como contexto
+```
+
+## Paso 0 — Carga y configuración
+
+```
+Skill("proceso-debate-adversarial")
+```
+
+El skill define el protocolo COLD START, el anti-herd check y el formato de
+síntesis. Las definiciones de personas viven en
+`habilidades/proceso-debate-adversarial/recursos/personas.md`.
+
+Confirmar con el usuario: propuesta, scope, set de personas, presupuesto.
+
+## Paso 1 — Reconocimiento del codebase
+
+Construir el paquete de conocimiento que recibirá CADA persona (idéntico para
+todas): descripción de la propuesta + inventario de archivos del scope +
+dependencias relevantes + superficie de API afectada + cobertura de tests del
+área. Usar `code-review-graph` si está disponible (blast radius, callers);
+si no, Grep/Glob dirigidos. Máximo ~1,500 tokens — las personas analizan, no
+exploran.
+
+## Paso 2 — Análisis en frío (5 invocaciones Agent independientes)
+
+Por cada persona, UNA invocación del Agent tool (general-purpose o el agente
+afín al dominio) con prompt autocontenido:
+
+```
+Eres [persona] — [enfoque de recursos/personas.md].
+Propuesta: [descripción]
+Contexto del codebase: [paquete del Paso 1]
+Tu tarea: encuentra hasta [presupuesto/5] problemas que esta propuesta
+causaría, desde tu perspectiva. Por cada uno: título, severidad
+(crítico/alto/medio/bajo), confianza 0-100%, archivo:línea si aplica,
+recomendación concreta. Preguntas guía: [de la persona]. Red flags: [de la
+persona]. NO incluyas elogios ni evaluación general — solo hallazgos.
+```
+
+Las 5 invocaciones pueden correr en paralelo. NUNCA pasar el output de una
+persona a otra — el aislamiento es el mecanismo del comando.
+
+## Paso 3 — Síntesis con anti-herd check
+
+Aplicar el protocolo de síntesis del skill:
+
+1. Deduplicar (mismo archivo:línea + mismo problema → fusionar, severidad más alta gana).
+2. Registrar disensos (dos personas en desacuerdo → ambas posturas visibles).
+3. **Anti-herd check**: si todas las personas coinciden en el hallazgo top,
+   generar explícitamente ≥1 contraargumento antes de aceptarlo.
+4. Rankear: `severidad × confianza promedio × número de personas que coinciden`.
+
+## Paso 4 — Reporte y persistencia
+
+Persistir en `.planning/loops/predecir-[timestamp]/` con
+`hooks/lib/loop-telemetry.js` (tipo `predecir`, columnas `iteracion,
+timestamp, hallazgo, severidad, confianza, personas, archivo_linea`; una fila
+por hallazgo consensuado) + `escribirHandoff` con `source: 'swl:predecir'`,
+`findings` rankeados y `config: {propuesta, scope}`.
+
+Reportar al usuario:
+
+```
+=== Predicción — [propuesta resumida] ===
+Personas: [set] | Hallazgos brutos: N | Tras dedup: M
+
+## Top hallazgos (rankeados)
+| # | Hallazgo | Severidad | Confianza | Acuerdo | archivo:línea | Recomendación |
+
+## Disensos registrados
+- [persona X sostiene A; persona Y sostiene B — evidencia de cada una]
+
+## Veredicto del panel
+[PROCEDER | PROCEDER CON AJUSTES (lista) | REPLANTEAR (razón)]
+```
+
+## Modo `--abogado-diablo` — crítica de la decisión, no del cambio
+
+El panel de personas **asume que el cambio se hará** y enumera problemas de
+implementación. Cuando la duda es anterior — *¿deberíamos hacer esto?* — el
+modo abogado del diablo reemplaza los Pasos 2-3 por UNA invocación profunda:
+
+```
+Agent(abogado-diablo-swl) con:
+- La propuesta + el paquete de conocimiento del Paso 1
+- Instrucción: ejecutar su protocolo completo (pre-mortem ×2-3 +
+  doubt-driven review + steelman) y emitir dictamen
+```
+
+Diferencias con el panel:
+
+| | Panel (default/adversarial) | `--abogado-diablo` |
+|---|---|---|
+| Pregunta que responde | "¿Qué problemas causará este cambio?" | "¿Deberíamos hacer este cambio?" |
+| Veredicto posible | PROCEDER / AJUSTES / REPLANTEAR | PROCEDER / CON CONDICIONES / **NO PROCEDER** |
+| Técnica | 5 perspectivas en frío + anti-herd | Pre-mortem + alternativas descartadas + contraevidencia + trigger de reversión |
+| Profundidad | Amplitud (5 ángulos, ~8 hallazgos c/u) | Profundidad (1 crítica exhaustiva de la decisión) |
+
+El Paso 4 (persistencia y reporte) aplica igual — el dictamen se persiste en el
+mismo directorio de handoff con `tipo: 'predecir-abogado-diablo'`. Combinable
+en secuencia: primero `--abogado-diablo` (¿hacerlo?); si el dictamen es
+PROCEDER, corrida normal del panel (¿qué cuidar al hacerlo?).
+
+## Paso 5 — Encadenamiento (si `--chain planear-fase`)
+
+Ofrecer arrancar `/swl:planear-fase` indicando el directorio del handoff. El
+planificador incorpora los hallazgos `crítico`/`alto` como restricciones del
+PLAN.md — cada uno se atiende con una tarea o se descarta con justificación
+explícita (nunca silenciosamente).
+
+## Reglas de comportamiento
+
+- NUNCA compartir contexto entre personas — una invocación Agent por persona.
+- NUNCA omitir el anti-herd check cuando hay unanimidad.
+- Los hallazgos con archivo:línea citan código REAL verificado en el Paso 1 —
+  regla `verificar-citas-normativas.md § Familia 2` aplica al propio output.
+- El comando NO modifica código — produce análisis. Implementar es del flujo
+  planear → ejecutar.
+- Con 0 hallazgos crítico/alto: decirlo claramente y no inflar hallazgos
+  menores para justificar el costo del panel.

package/comandos/swl/reflect-skills.md

@@ -1,125 +1,125 @@
----
-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/evolution/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/evolution/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.
+---
+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/evolution/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/evolution/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.