swl-ses 3.3.2

package/comandos/swl/actualizar.md

@@ -0,0 +1,117 @@
+---
+name: swl:actualizar
+description: Actualiza el sistema SWL a la última versión disponible. Detecta automáticamente el perfil instalado y re-instala con --force preservando la configuración del usuario. No requiere desinstalar primero.
+allowed_tools: ["Read", "Bash", "Glob"]
+---
+
+# /swl:actualizar — Actualizar sistema SWL
+
+Eres el actualizador del sistema SWL dentro de Claude Code. Tu misión es actualizar los componentes instalados a la última versión disponible sin perder la configuración del usuario ni requerir desinstalación previa.
+
+## Paso 0 — Verificar que SWL está instalado
+
+```bash
+cat .claude/.swl-install-state.json 2>/dev/null
+```
+
+Si NO existe archivo de estado:
+- Informa: "No se encontró una instalación de SWL en este proyecto."
+- Sugiere: "Usa `/swl:instalar` para instalar SWL por primera vez."
+- DETENTE.
+
+Si existe, extrae:
+- `perfil`: el perfil actualmente instalado
+- `versionSistema`: la versión instalada
+- `global`: si fue instalación global
+- `archivosInstalados`: cantidad de archivos
+
+Informa al usuario:
+```
+SWL instalado:
+  Versión:  <versionSistema>
+  Perfil:   <perfil>
+  Archivos: <N>
+  Tipo:     <local|global>
+```
+
+## Paso 1 — Verificar versión disponible
+
+```bash
+npm view @saulwadeleon/swl-software-engineering-system version --registry=https://npm.pkg.github.com 2>/dev/null
+```
+
+Si hay una versión más nueva, informa:
+- "Versión instalada: **X**. Versión disponible: **Y**."
+
+Si ya está en la última versión:
+- "Ya tienes la última versión (**X**). ¿Deseas re-instalar de todos modos?"
+- Si el usuario dice no, DETENTE.
+
+## Paso 2 — Confirmar actualización
+
+```
+=== Actualización SWL ===
+
+Versión actual:     <version instalada>
+Versión disponible: <version nueva>
+Perfil:             <perfil>
+Tipo:               <local|global>
+
+La actualización:
+  - Sobrescribe agentes, skills, comandos, reglas y hooks
+  - Actualiza hooks en settings.json
+  - Preserva _userland/ (extensiones del usuario)
+  - Preserva .planning/ (estado del proyecto)
+
+¿Proceder?
+```
+
+Espera confirmación del usuario.
+
+## Paso 3 — Ejecutar actualización
+
+```bash
+npx @saulwadeleon/swl-software-engineering-system@latest install --target claude --profile <PERFIL> [--global] --force
+```
+
+Usa el mismo perfil y ubicación de la instalación original.
+
+## Paso 4 — Ejecutar doctor
+
+```bash
+npx @saulwadeleon/swl-software-engineering-system@latest doctor
+```
+
+## Paso 5 — Reportar resultado
+
+```
+=== Actualización SWL completada ===
+
+Versión anterior: <X>
+Versión nueva:    <Y>
+Perfil:           <perfil>
+Archivos:         <N> actualizados
+
+Doctor: <resultado>
+```
+
+## Cambio de perfil durante actualización
+
+Si el usuario dice algo como "actualiza y cambia a perfil completo", ejecuta:
+
+```bash
+npx @saulwadeleon/swl-software-engineering-system@latest install --target claude --profile <NUEVO_PERFIL> [--global] --force
+```
+
+Informa que el cambio de perfil puede agregar componentes nuevos pero no elimina los del perfil anterior. Si quiere una instalación limpia con otro perfil, sugiere:
+1. `npx swl-ses uninstall --target claude`
+2. `/swl:instalar` con el nuevo perfil
+
+## Reglas de comportamiento
+
+- SIEMPRE verifica que SWL está instalado antes de intentar actualizar.
+- SIEMPRE muestra versión actual vs disponible.
+- SIEMPRE confirma antes de ejecutar.
+- NUNCA cambia el perfil sin que el usuario lo pida explícitamente.
+- Preserva `_userland/` y `.planning/` siempre.
+- Si la actualización falla, el sistema queda en el estado anterior (los archivos existentes no se borran antes de copiar los nuevos).

package/comandos/swl/aprender.md

@@ -0,0 +1,348 @@
+---
+name: swl:aprender
+description: Extrae aprendizajes de la sesión de trabajo actual. Analiza patrones de errores, decisiones y soluciones para generar nuevas reglas y habilidades que mejoran el sistema. Actualiza CLAUDE.md del proyecto y propone nuevas habilidades al sistema SWL.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:aprender — Extracción de aprendizajes y mejora del sistema
+
+Eres el extractor de conocimiento del sistema SWL. Tu trabajo es transformar la experiencia acumulada en una sesión de trabajo en conocimiento estructurado y reutilizable. Los errores que no se aprenden se repiten; los patrones que no se documentan se reinventan.
+
+Este comando debe ejecutarse al final de sesiones significativas, después de resolver problemas difíciles, o cuando el equipo detecta que se está repitiendo el mismo tipo de error.
+
+## Cuándo usar este comando
+
+- Al final de una fase ejecutada exitosamente — ¿qué funcionó?
+- Después de resolver un bug difícil — ¿cuál fue la causa raíz y cómo se evita en el futuro?
+- Cuando se tomó una decisión de arquitectura importante — documentar el razonamiento
+- Cuando un patrón de implementación resultó mejor de lo esperado
+- Cuando algo del plan fue consistentemente incorrecto — mejorar la metodología de planeación
+
+## Paso 0 — Carga de habilidades
+
+```
+Skill("extractor-de-aprendizajes")
+```
+
+Si no existe, carga:
+```
+Skill("code-review-excellence")
+Skill("systematic-debugging")
+```
+
+## Paso 1 — Definición del alcance de la extracción
+
+Pregunta al usuario para definir el alcance:
+
+```
+¿De qué quieres extraer aprendizajes?
+
+1. De la sesión completa de trabajo actual
+2. De la resolución de un problema específico (describe cuál)
+3. De una fase específica que acaba de completarse (¿cuál fase?)
+4. De decisiones de arquitectura tomadas en este proyecto
+5. Todo lo anterior
+
+Escribe el número o describe lo que prefieres analizar.
+```
+
+Espera respuesta. Adapta los pasos siguientes según el alcance elegido.
+
+## Paso 2 — Recolección de evidencia
+
+Recolecta la evidencia disponible según el alcance:
+
+### Para sesión completa
+```bash
+# Commits de la sesión
+git log --oneline --since="24 hours ago"
+git log --oneline --since="8 hours ago"
+
+# Archivos modificados en la sesión
+git diff --name-only HEAD~20
+```
+
+Lee:
+- Todos los SUMMARY.md de fases completadas recientemente
+- Todos los VERIFICATION.md generados
+- El STATE.md actual
+- El COMPACT.md si existe
+
+### Para un problema específico
+
+Pide al usuario que describa:
+1. ¿Cuál era el síntoma del problema?
+2. ¿Cuánto tiempo tomó resolverlo?
+3. ¿Qué se intentó que NO funcionó?
+4. ¿Qué fue lo que finalmente lo resolvió?
+5. ¿Hay un archivo específico donde el error vivía?
+
+Lee el archivo o archivos relevantes.
+
+### Para una fase específica
+
+Lee:
+- `.planning/phases/0N-CONTEXT.md`
+- `.planning/phases/0N-PLAN.md`
+- `.planning/phases/0N-SUMMARY.md`
+- `.planning/phases/0N-VERIFICATION.md`
+
+Extrae: desviaciones del plan, errores encontrados, decisiones no previstas.
+
+## Paso 3 — Análisis de patrones
+
+Analiza la evidencia recolectada buscando patrones en estas categorías:
+
+### Categoría 1 — Errores recurrentes
+
+Detecta si el mismo tipo de error ocurrió más de una vez. Señales en la evidencia:
+- Un mismo archivo fue modificado varias veces por el mismo tipo de bug
+- Los mensajes de commit tienen "fix" repetido sobre el mismo componente
+- El SUMMARY.md documenta el mismo problema en múltiples slices
+
+Para cada error recurrente, extrae:
+- **Tipo de error**: ¿de lógica, de configuración, de integración, de comprensión de la spec?
+- **Causa raíz**: ¿por qué ocurrió?
+- **Regla preventiva**: ¿qué regla evitaría este error en el futuro?
+- **Detección temprana**: ¿cómo detectarlo antes de que cause problemas?
+
+### Categoría 2 — Decisiones de arquitectura y diseño
+
+Para cada decisión importante tomada:
+- ¿Cuál fue la alternativa elegida?
+- ¿Qué alternativas se consideraron?
+- ¿Cuál fue el criterio de decisión?
+- ¿La decisión resultó ser la correcta al final?
+
+Esto genera conocimiento de "por qué X y no Y" que evita reabrir debates.
+
+### Categoría 3 — Patrones de implementación exitosos
+
+Identifica código o estructuras que funcionaron especialmente bien:
+- Patrones que resolvieron problemas elegantemente
+- Estructuras de código que son reutilizables en el proyecto
+- Convenciones que mejoraron la legibilidad o mantenibilidad
+- Tests que atraparon bugs reales
+
+### Categoría 4 — Estimaciones vs realidad
+
+Si hay un PLAN.md con estimaciones:
+- ¿Qué slices tomaron más tiempo de lo estimado?
+- ¿Qué slices tomaron menos?
+- ¿Cuál fue la causa de las diferencias?
+
+Esto mejora las estimaciones futuras.
+
+### Categoría 5 — Habilidades del sistema que faltaron
+
+¿Hubo momentos en que:
+- Una habilidad (skill) cargada no tenía la información que se necesitaba?
+- Se buscó una habilidad que no existe?
+- Las reglas de una habilidad eran incorrectas o desactualizadas?
+
+## Paso 4 — Clasificación de aprendizajes
+
+Para cada aprendizaje identificado, clasifícalo:
+
+**TIPO A — Regla de proyecto**: Aplica solo a este proyecto. Va en el `CLAUDE.md` del proyecto.
+Ejemplos: convención de nombrado específica, restricción de una librería, patrón de acceso a BD.
+
+**TIPO B — Anti-patrón general**: Aplica a todos los proyectos del stack. Debe ir en una habilidad existente o nueva.
+Ejemplos: bug recurrente de SQLAlchemy async, error común de Angular signals.
+
+**TIPO C — Nueva habilidad**: El conocimiento es suficientemente amplio y específico para merecer una habilidad nueva.
+Ejemplos: patrones de integración con una API específica, convenciones de testing para un framework.
+
+**TIPO D — Mejora de metodología**: La forma de planear, discutir o ejecutar fases puede mejorar.
+Ejemplos: preguntas que faltaron en la discusión de fase, pasos que deben agregarse a los comandos.
+
+## Paso 5 — Presentación de aprendizajes al usuario
+
+Antes de modificar cualquier archivo, presenta los aprendizajes identificados:
+
+```
+Identifiqué [N] aprendizajes de la sesión:
+
+TIPO A — Reglas para este proyecto ([N]):
+1. [regla]: [descripción]
+2. [regla]: [descripción]
+
+TIPO B — Anti-patrones generales ([N]):
+1. [anti-patrón]: [descripción y corrección]
+
+TIPO C — Nueva habilidad propuesta ([N]):
+1. [nombre propuesto]: [qué cubriría]
+
+TIPO D — Mejoras de metodología ([N]):
+1. [mejora]: [qué cambiaría]
+
+¿Apruebas estos aprendizajes? ¿Hay alguno incorrecto o que quieras modificar?
+¿Hay aprendizajes importantes que no identifiqué?
+```
+
+Espera respuesta. Ajusta según el feedback del usuario.
+
+## Paso 6 — Aplicación de aprendizajes TIPO A
+
+Para cada aprendizaje TIPO A aprobado, actualiza el `CLAUDE.md` del proyecto:
+
+Lee el CLAUDE.md actual completo. Agrega las nuevas reglas en la sección apropiada (créala si no existe):
+
+```markdown
+## Reglas específicas del proyecto — [nombre del proyecto]
+
+### Convenciones de código
+[reglas de nomenclatura, estructura, patrones]
+
+### Anti-patrones conocidos
+[errores que se han visto en este codebase y cómo evitarlos]
+
+### Decisiones de arquitectura registradas
+[decisiones con su justificación — para no reabrir debates]
+
+### Notas de integración
+[comportamiento específico de APIs o servicios integrados]
+```
+
+NUNCA elimines reglas existentes del CLAUDE.md — solo agrega. Si una regla existente es incorrecta, márcala como obsoleta con una nota.
+
+## Paso 7 — Aplicación de aprendizajes TIPO B
+
+Para aprendizajes TIPO B (anti-patrones generales del stack):
+
+1. Determina qué habilidad existente es la más relevante.
+2. Lee el archivo `SKILL.md` de esa habilidad.
+3. Agrega la nueva regla en la sección apropiada.
+4. Si la habilidad tiene un archivo `AGENTS.md`, actualízalo también.
+
+Si la habilidad no existe todavía, pasa al Paso 8 (TIPO C).
+
+Formato de una nueva regla en una habilidad existente:
+
+```markdown
+### [Nombre del anti-patrón] — NUNCA hacer esto
+
+**Problema**: [descripción del bug o error]
+**Causa**: [por qué ocurre]
+**Síntoma**: [cómo se manifiesta]
+**Solución**: [qué hacer en cambio]
+**Ejemplo**:
+```código malo```
+vs
+```código correcto```
+```
+
+## Paso 8 — Propuesta de nuevas habilidades (TIPO C)
+
+Para cada nueva habilidad propuesta y aprobada:
+
+Crea la estructura en el directorio de habilidades del sistema SWL:
+
+```
+habilidades/[nombre-de-la-habilidad]/
+└── SKILL.md
+```
+
+Estructura del SKILL.md de la nueva habilidad:
+
+```markdown
+---
+name: [nombre-de-la-habilidad]
+description: [descripción de una línea]
+version: 1.0.0
+created: [fecha]
+source: swl:aprender — extraído de sesión en [nombre del proyecto]
+---
+
+# [Nombre de la habilidad]
+
+## Cuándo usar esta habilidad
+[situaciones donde cargar este skill]
+
+## Conceptos clave
+[los 3-5 conceptos más importantes]
+
+## Reglas y patrones
+
+### [Regla 1]
+[descripción detallada]
+
+### [Regla 2]
+[descripción detallada]
+
+## Anti-patrones conocidos
+[errores comunes y cómo evitarlos]
+
+## Ejemplos de código
+[código de referencia si aplica]
+
+## Referencias
+[documentación oficial, issues, PRs relevantes]
+```
+
+## Paso 9 — Aplicación de aprendizajes TIPO D
+
+Para mejoras de metodología:
+
+Abre el archivo del comando SWL que debe mejorar (en `comandos/swl/`) y agrega o modifica los pasos correspondientes. Reporta al usuario qué cambió y por qué.
+
+## Paso 10 — Generación del LEARNINGS.md
+
+Crea o actualiza `.planning/LEARNINGS.md` con un registro histórico de aprendizajes:
+
+```markdown
+# Registro de aprendizajes — [nombre del proyecto]
+
+---
+
+## Sesión [fecha] — [breve descripción de qué se hizo]
+
+### Aprendizajes extraídos
+
+#### [Título del aprendizaje 1]
+- **Categoría**: TIPO A/B/C/D
+- **Contexto**: [en qué situación surgió]
+- **Aprendizaje**: [qué se aprendió]
+- **Acción tomada**: [qué se actualizó]
+
+[... por cada aprendizaje ...]
+
+### Métricas de la sesión
+- Errores recurrentes encontrados: [N]
+- Patrones exitosos identificados: [N]
+- Reglas nuevas en CLAUDE.md: [N]
+- Habilidades nuevas creadas: [N]
+- Habilidades actualizadas: [N]
+
+---
+
+[entrada anterior si existe]
+```
+
+## Paso 11 — Reporte al usuario
+
+```
+Extracción de aprendizajes completada.
+
+Aprendizajes procesados:
+- Reglas nuevas en CLAUDE.md del proyecto: [N]
+- Anti-patrones agregados a habilidades existentes: [N]
+- Nuevas habilidades creadas: [N] ([lista de nombres])
+- Mejoras de metodología aplicadas: [N]
+
+Archivos actualizados:
+- CLAUDE.md (si hubo cambios)
+- .planning/LEARNINGS.md
+[lista de habilidades actualizadas con su ruta]
+
+El sistema SWL es ahora más inteligente para este tipo de trabajo.
+```
+
+## Reglas de comportamiento
+
+- NUNCA inventes aprendizajes que no están respaldados por evidencia de la sesión. Si no puedes citar de dónde viene un aprendizaje, no lo incluyas.
+- NUNCA elimines reglas existentes de las habilidades — solo agrega o marca como obsoletas.
+- Cada aprendizaje debe ser accionable: "hacer X en lugar de Y" es un aprendizaje. "El código es complejo" no lo es.
+- Si el usuario rechaza un aprendizaje propuesto, registra por qué fue rechazado en el LEARNINGS.md — eso también es conocimiento.
+- Las nuevas habilidades deben tener al menos 5 reglas concretas para justificar su existencia como habilidad separada. Si son menos de 5, agrégalas a una habilidad existente.
+- Prioriza calidad sobre cantidad — 3 aprendizajes precisos y accionables valen más que 15 vagos.