swl-ses 3.3.2

package/comandos/swl/autoresearch.md

@@ -0,0 +1,346 @@
+---
+name: swl:autoresearch
+description: Ejecuta el loop de auto-mejora iterativa Autoresearch sobre un skill o agente. Crea o usa un checklist de evaluación (3-6 items binarios ponderados), obtiene baseline score, ejecuta mutaciones atómicas (una a la vez) evaluando contra el checklist, y decide keep/revert por round hasta alcanzar 95%+ ×3. Flags disponibles: --skill=[nombre], --agente=[nombre], --max-rounds=[N], --target=[N], --dry-run, --checklist=[path].
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:autoresearch — Loop de auto-mejora iterativa de skills
+
+Eres el motor de Autoresearch del sistema SWL. Tu responsabilidad es mejorar skills y agentes de forma medible e iterativa: defines un checklist de calidad, obtienes un baseline, y ejecutas un loop de mutaciones atómicas donde cada cambio se evalúa y se mantiene solo si mejora el score. Basado en el método de Andrej Karpathy.
+
+Este comando es distinto a `/swl:evolucionar`: donde evolucionar analiza evidencia histórica para proponer mejoras, autoresearch ejecuta un **loop cerrado de mejora medible** contra un checklist concreto.
+
+## Cuándo usar este comando
+
+- Cuando un skill específico produce outputs de baja calidad de forma consistente
+- Cuando se quiere elevar la calidad de un skill de forma medible antes de una release
+- Cuando `auto-evolucion-swl` identifica un skill candidato para mejora iterativa
+- Cuando se quiere optimizar cualquier prompt o template que se use repetidamente
+- Después de crear un skill nuevo para calibrarlo contra criterios de calidad
+
+## Flags soportados
+
+```
+--skill=[nombre]        Skill a mejorar (busca en habilidades/[nombre]/SKILL.md)
+--agente=[nombre]       Agente a mejorar (busca en agentes/[nombre].md)
+--max-rounds=[N]        Máximo de iteraciones del loop (default: 10)
+--target=[N]            Score objetivo en % (default: 95)
+--dry-run               Analizar y crear checklist sin ejecutar mutaciones
+--checklist=[path]      Ruta a checklist existente (si no se pasa, se crea uno)
+```
+
+**Nota**: Se debe pasar `--skill` o `--agente`, no ambos. Si no se pasa ninguno, preguntar al usuario.
+
+## Paso 0 — Parseo de flags y carga de habilidades
+
+Lee los flags del comando invocado. Determina el alcance:
+- `--skill=[nombre]`: mejorar el skill indicado
+- `--agente=[nombre]`: mejorar el agente indicado
+- `--max-rounds=[N]`: límite de iteraciones (default: 10)
+- `--target=[N]`: score objetivo (default: 95)
+- `--dry-run`: solo crear checklist y baseline, no mutar
+- `--checklist=[path]`: usar checklist existente
+
+Carga de habilidades:
+```
+Skill("autoresearch")
+```
+
+Reporta configuración:
+```
+=== Autoresearch — Configuración ===
+Objetivo: [skill/agente] [nombre]
+Max rounds: [N]
+Target score: [N]%
+Modo: [ejecutar | dry-run]
+Checklist: [existente: path | por crear]
+```
+
+## Paso 1 — Lectura del artefacto objetivo
+
+### Para skills
+
+```bash
+# Leer el skill completo
+cat habilidades/[nombre]/SKILL.md
+
+# Verificar si ya tiene checklist
+ls habilidades/[nombre]/recursos/checklist-autoresearch.md 2>/dev/null
+```
+
+### Para agentes
+
+```bash
+# Leer el agente completo
+cat agentes/[nombre].md
+
+# Verificar si ya tiene checklist en .planning/
+ls .planning/checklists/[nombre]-checklist.md 2>/dev/null
+```
+
+Lee el artefacto completo. Identifica:
+- Versión actual (frontmatter)
+- Secciones principales
+- Reglas existentes
+- Ejemplos de código
+- Anti-patrones documentados
+
+## Paso 2 — Crear o cargar checklist de evaluación
+
+### Si se pasó --checklist=[path]
+
+Lee el checklist indicado:
+```bash
+cat [path]
+```
+
+Valida que tenga entre 3 y 6 items con formato correcto (criterio, peso 1-5, verificación).
+
+### Si ya existe checklist para este skill/agente
+
+```bash
+# Para skills
+cat habilidades/[nombre]/recursos/checklist-autoresearch.md
+
+# Para agentes
+cat .planning/checklists/[nombre]-checklist.md
+```
+
+Pregunta al usuario si quiere usarlo o crear uno nuevo.
+
+### Si no existe checklist — crearlo
+
+Analiza el skill/agente y propone un checklist de 3-6 items:
+
+1. **Identificar el output típico** del skill — ¿qué genera cuando se invoca?
+2. **Extraer las 3-5 reglas más críticas** del SKILL.md
+3. **Convertir cada regla en criterio binario verificable**
+4. **Asignar pesos** (1-5) según impacto en calidad
+5. **Definir método de verificación** concreto
+
+Presenta al usuario:
+
+```
+Propuesta de checklist para [nombre]:
+
+| # | Criterio | Peso | Verificación |
+|---|----------|------|-------------|
+| 1 | [criterio] | [N] | [método] |
+| 2 | [criterio] | [N] | [método] |
+...
+
+Caso de prueba propuesto: [descripción]
+
+¿Aprobado? (sí / modificar / agregar items)
+```
+
+Espera confirmación antes de continuar. Guarda el checklist:
+
+```bash
+# Para skills
+mkdir -p habilidades/[nombre]/recursos
+# → guardar en habilidades/[nombre]/recursos/checklist-autoresearch.md
+
+# Para agentes
+mkdir -p .planning/checklists
+# → guardar en .planning/checklists/[nombre]-checklist.md
+```
+
+## Paso 3 — Definir caso de prueba
+
+El caso de prueba es un prompt concreto que se usará para evaluar el skill en cada round.
+
+Si el checklist ya incluye un caso de prueba, usarlo. Si no, proponer uno:
+
+```
+Caso de prueba propuesto:
+"[prompt concreto que active las reglas principales del skill]"
+
+¿Aprobado? (sí / modificar)
+```
+
+El caso debe ser:
+- **Representativo**: activa las reglas más críticas del skill
+- **Reproducible**: el mismo prompt siempre
+- **Concreto**: no genérico, con entidades y contexto específico
+
+## Paso 4 — Obtener baseline score
+
+Ejecuta el skill con el caso de prueba:
+
+1. Simula la invocación del skill (lee el SKILL.md y genera output aplicándolo)
+2. Evalúa el output contra cada item del checklist
+3. Calcula el score ponderado
+
+```bash
+# Calcular score
+node habilidades/autoresearch/scripts/calcular-score.js '[JSON con items evaluados]'
+```
+
+Presenta el baseline:
+
+```
+=== Baseline Score ===
+Skill: [nombre]
+Caso de prueba: [descripción]
+Score: [N]% ([puntos]/[max] puntos)
+Estado: [EXCELENTE|BUENO|REGULAR|DEFICIENTE]
+
+| # | Criterio | Peso | ✓/✗ | Notas |
+|---|----------|------|-----|-------|
+| 1 | [criterio] | [N] | ✓/✗ | [observación] |
+...
+```
+
+Si `--dry-run`, termina aquí con recomendaciones de qué mutar primero.
+
+Si el baseline ya es ≥ target:
+```
+El skill ya cumple el target de [N]%. No se requiere autoresearch.
+Considera elevar el target o agregar items más exigentes al checklist.
+```
+
+## Paso 5 — Loop de mutación
+
+Inicializa variables del loop:
+
+```
+best_score = baseline_score
+consecutive_passes = 0
+round = 0
+changelog = []
+```
+
+### Para cada round (hasta max_rounds):
+
+#### 5a. Seleccionar item target
+
+Elige el item con mayor impacto potencial:
+```
+prioridad = peso × (1 si no_cumple else 0) × factor_tipo
+```
+
+Donde factor_tipo favorece agregar (1.0) sobre eliminar (0.4).
+
+Si todos los items se cumplen pero el score es < target, buscar items que se cumplen parcialmente o agregar items más exigentes.
+
+#### 5b. Proponer mutación atómica
+
+Proponer UN solo cambio al skill/agente que aborde el item seleccionado:
+
+```
+Round [N] — Item target: #[X] ([criterio])
+Mutación propuesta: [tipo] — [descripción concreta]
+
+Cambio específico:
+  Archivo: [path]
+  Sección: [nombre de la sección]
+  Acción: [agregar/refinar/reordenar/eliminar]
+  Contenido: [el cambio concreto]
+```
+
+#### 5c. Aplicar la mutación
+
+Usa Edit para aplicar el cambio al skill/agente. Registra el estado antes del cambio para poder revertir.
+
+#### 5d. Re-evaluar
+
+Ejecuta el skill con el mismo caso de prueba y evalúa contra el checklist.
+
+```bash
+node habilidades/autoresearch/scripts/calcular-score.js '[JSON actualizado]'
+```
+
+#### 5e. Decidir keep/revert
+
+```
+Si new_score >= old_score:
+  → KEEP — El cambio se mantiene
+  → Actualizar best_score
+Else:
+  → REVERT — Deshacer el cambio con Edit
+  → Restaurar el estado anterior
+```
+
+#### 5f. Registrar en changelog
+
+```
+## Round [N] — Score: [old]% → [new]% ([+/-delta]%)
+Mutación: [tipo] — [descripción]
+Item target: #[X] ([criterio])
+Resultado: KEEP | REVERT
+```
+
+#### 5g. Verificar condiciones de salida
+
+```
+if new_score >= target:
+  consecutive_passes += 1
+  if consecutive_passes >= 3: → SALIR (éxito)
+else:
+  consecutive_passes = 0
+
+if 3 reverts consecutivos: → SALIR (estancamiento)
+if score bajó 2 rounds seguidos: → REVERT al mejor score y SALIR
+```
+
+## Paso 6 — Reporte final
+
+Al salir del loop (por cualquier condición):
+
+```
+=== Reporte Autoresearch — [nombre] ===
+
+Fecha: [fecha]
+Rounds ejecutados: [N]
+Score: [baseline]% → [final]%
+Mutaciones KEEP: [N] | Mutaciones REVERT: [N]
+Resultado: [ÉXITO | PLATEAU | ESTANCAMIENTO | DEGRADACIÓN]
+
+### Mutaciones aplicadas (en orden)
+1. [tipo]: [descripción] — Score [X]% → [Y]%
+2. [tipo]: [descripción] — Score [X]% → [Y]%
+
+### Mutaciones revertidas
+1. [tipo]: [descripción] — Razón: [por qué empeoró]
+
+### Score final por item
+| # | Criterio | Peso | ✓/✗ |
+|---|----------|------|-----|
+| 1 | [criterio] | [N] | ✓/✗ |
+
+### Recomendaciones
+- [qué hacer si no se alcanzó el target]
+- [items que requieren atención manual]
+```
+
+## Paso 7 — Versionado y persistencia
+
+Si el score mejoró respecto al baseline:
+
+1. **Actualizar versión** del skill/agente en el frontmatter:
+   - Score mejoró < 10 puntos → PATCH
+   - Score mejoró ≥ 10 puntos → MINOR
+
+2. **Guardar el reporte** en `.planning/autoresearch/[nombre]-[fecha].md`
+
+3. **Registrar en APRENDIZAJES.md** las mutaciones más impactantes:
+   ```markdown
+   ## [fecha] patrón — Autoresearch de [nombre]: [baseline]% → [final]%
+   **Agente**: auto-evolucion-swl (via autoresearch)
+   **Contexto**: Las mutaciones más efectivas fueron: [lista]
+   ```
+
+4. **Actualizar el checklist** si se descubrieron items nuevos durante el loop
+
+## Reglas de comportamiento
+
+- NUNCA ejecutar mutaciones sin checklist aprobado por el usuario
+- NUNCA cambiar más de una cosa por round — esto es la regla más importante del protocolo
+- NUNCA modificar el checklist durante el loop (salvo al finalizar, para la próxima vez)
+- SIEMPRE revertir si el score baja — no hay excepciones
+- SIEMPRE mostrar el diff concreto antes de cada mutación
+- Si el skill tiene dependencias (otros skills que lo referencian), verificar que las mutaciones no rompen la interfaz
+- Si después de 3 rounds el score no mejora, preguntar al usuario si quiere continuar, cambiar estrategia, o parar
+- El caso de prueba NO cambia durante el loop — es la constante del experimento
+- Mantener un log completo de todo el loop para auditoría posterior

package/comandos/swl/checkpoint.md

@@ -0,0 +1,296 @@
+---
+name: swl:checkpoint
+description: Guarda el estado completo del proyecto en un momento dado para poder retomarlo después. Captura contexto activo, progreso detallado, decisiones tomadas y pendientes. Produce STATE.md actualizado y continue-here.md con instrucciones de retoma.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:checkpoint — Guardar estado para retoma posterior
+
+Eres el guardián del estado del proyecto SWL. Cuando el usuario necesita pausar el trabajo, tu misión es capturar TODO el contexto necesario para que otra sesión (o el mismo usuario días después) pueda retomar exactamente donde se quedó, sin perder nada.
+
+Un checkpoint mal hecho significa horas de reconstrucción de contexto. Un checkpoint bien hecho permite retomar en minutos.
+
+## Cuándo usar este comando
+
+- Antes de cerrar la sesión de trabajo
+- Antes de un cambio de contexto largo
+- Cuando el contexto de la conversación está cerca de su límite
+- Antes de que otro desarrollador tome el trabajo
+- Antes de un descanso largo (fin de semana, vacaciones)
+
+## Paso 0 — Lectura del estado actual
+
+Lee en orden sin modificar nada todavía:
+
+1. `.planning/STATE.md` — estado previo si existe.
+2. `.planning/ROADMAP.md` — estado global del proyecto.
+3. `.planning/PROJECT.md` — contexto del proyecto.
+4. Cualquier `.planning/phases/0N-PLAN.md` de la fase activa.
+5. `git log --oneline -20` — commits recientes.
+6. `git status` — cambios sin commitear.
+7. `git stash list` — cambios en stash si los hay.
+
+## Paso 1 — Detección del estado activo
+
+Determina automáticamente:
+
+### ¿En qué fase está el proyecto?
+- Lee el ROADMAP.md y detecta la última fase con estado "En progreso" o "Planeada".
+- Si no hay fase activa, detecta la última fase "Completada".
+
+### ¿En qué punto del flujo de trabajo está?
+Determina la posición en el flujo SWL:
+
+```
+[ ] Sin inicializar           → /swl:nuevo-proyecto
+[ ] Proyecto inicializado     → /swl:discutir-fase N
+[ ] Fase discutida            → /swl:planear-fase N
+[ ] Fase planeada             → /swl:ejecutar-fase N
+[ ] Fase ejecutada            → /swl:verificar
+[ ] Verificación completada   → /swl:ejecutar-fase N+1 o entrega
+```
+
+### ¿Hay trabajo en progreso sin commitear?
+
+```bash
+git status --short
+git diff --stat
+```
+
+Si hay archivos modificados o sin trackear, registra EXACTAMENTE cuáles son y qué contienen.
+
+## Paso 2 — Inventario de contexto crítico
+
+Haz un inventario de todos los elementos de contexto que serían difíciles de reconstruir:
+
+### 2.1 — Decisiones técnicas recientes
+
+Busca en los archivos de planeación y en la sesión actual:
+- Decisiones de arquitectura tomadas y su justificación
+- Alternativas descartadas y por qué
+- Workarounds o soluciones no estándar aplicadas
+
+### 2.2 — Problemas encontrados y resoluciones
+
+Busca en los archivos de verificación y summary:
+- Errores que se encontraron y cómo se resolvieron
+- Problemas que están pendientes de resolución
+- Dependencias que fallaron o que se comportaron diferente a lo esperado
+
+### 2.3 — Decisiones pendientes
+
+Lee los archivos de contexto y plan buscando:
+- Items marcados como "[POR DEFINIR]"
+- Items marcados como "[REQUIERE VERIFICACIÓN MANUAL]"
+- Tareas HITL no resueltas
+- Preguntas al usuario sin respuesta
+
+### 2.4 — Contexto de conversación actual
+
+Si estás en una sesión activa, captura:
+- El último mensaje del usuario antes del checkpoint
+- La última acción que se completó
+- La próxima acción que se iba a ejecutar
+- Cualquier instrucción especial que el usuario dio en esta sesión
+
+## Paso 3 — Actualización del STATE.md
+
+Sobreescribe `.planning/STATE.md` con el estado completo y actual:
+
+```markdown
+# Estado del proyecto — Checkpoint
+
+**Proyecto**: [nombre del proyecto]
+**Directorio raíz**: [ruta absoluta]
+**Fecha del checkpoint**: [fecha y hora exacta]
+**Creado por**: swl:checkpoint
+
+---
+
+## Para retomar el trabajo
+
+Ejecuta este comando:
+```
+[comando exacto para continuar, ej: /swl:ejecutar-fase 2]
+```
+
+**Contexto inmediato**: [1-2 oraciones de qué estaba pasando exactamente]
+
+---
+
+## Posición en el flujo SWL
+
+**Fase activa**: Fase N — [nombre]
+**Estado de la fase**: [Discutida | Planeada | En ejecución | Ejecutada | Verificada]
+**Próximo paso**: [comando exacto]
+
+### Si la ejecución estaba en progreso:
+- Último slice completado: [nombre o "ninguno"]
+- Slice en progreso: [nombre o "no había"]
+- Próximo slice: [nombre]
+- Tareas completadas en el slice actual: [N de N]
+
+---
+
+## Estado de Git
+
+**Rama actual**: [nombre de la rama]
+**Último commit**: [hash] — [mensaje]
+**Cambios sin commitear**: [sí/no]
+
+### Archivos con cambios sin commitear (si los hay)
+[lista de archivos con su estado: M=modificado, U=sin trackear]
+
+**Importante**: Estos cambios deben manejarse antes de continuar:
+[instrucción específica: commitear, hacer stash, o descartar]
+
+---
+
+## Decisiones técnicas tomadas
+
+[lista de decisiones importantes tomadas desde el inicio del proyecto o desde el último checkpoint]
+
+1. **[Decisión]**: [qué se decidió y por qué]
+2. **[Decisión]**: [qué se decidió y por qué]
+
+---
+
+## Decisiones pendientes
+
+[lista de cosas que requieren decisión humana o están sin resolver]
+
+1. [ ] [qué debe decidirse] — **Bloqueante**: sí/no
+2. [ ] [qué debe decidirse] — **Bloqueante**: sí/no
+
+---
+
+## Problemas conocidos activos
+
+[lista de bugs, limitaciones o issues que están en el radar]
+
+1. [problema] — Severidad: ALTA/MEDIA/BAJA — Archivo: [ruta]
+
+---
+
+## Contexto de sesión
+
+**Último mensaje del usuario antes del checkpoint**:
+> [cita textual si está disponible, o resumen]
+
+**Última acción completada**:
+[descripción de la última cosa que se hizo]
+
+**Próxima acción planificada**:
+[descripción de lo que se iba a hacer a continuación]
+
+---
+
+## Estado del ROADMAP
+
+[copia simplificada del roadmap con estados actuales]
+
+| Fase | Nombre | Estado | Completada |
+|------|--------|--------|-----------|
+| 1 | [nombre] | Completada | [fecha] |
+| 2 | [nombre] | En progreso | — |
+| 3 | [nombre] | Pendiente | — |
+
+---
+
+## Archivos de referencia clave
+
+[lista de los archivos más importantes que la próxima sesión debe leer primero]
+
+1. `.planning/phases/0N-PLAN.md` — plan de la fase activa
+2. `.planning/phases/0N-CONTEXT.md` — contexto de la fase activa
+3. [otros archivos críticos]
+```
+
+## Paso 4 — Creación del continue-here.md
+
+Crea `.planning/continue-here.md` como guía de retoma rápida:
+
+```markdown
+# Guía de retoma — [nombre del proyecto]
+
+**Checkpoint creado**: [fecha y hora]
+
+## En 30 segundos
+
+[nombre del proyecto] — [descripción de 1 oración]
+Stack: [lenguajes/frameworks principales]
+Fase activa: Fase N — [nombre]
+
+## Para continuar ahora mismo
+
+1. Lee `.planning/STATE.md` para el contexto completo.
+2. Ejecuta: `[comando exacto]`
+
+## Qué se estaba haciendo
+
+[3-5 oraciones narrando el estado actual del trabajo en lenguaje humano, no técnico]
+
+## La siguiente tarea concreta
+
+[descripción específica de la siguiente tarea, con el archivo objetivo si aplica]
+
+## Lo que NO debes hacer al retomar
+
+[lista de acciones que podrían causar problemas: no commitear los cambios sin revisar, no regenerar X porque ya se hizo, etc.]
+
+## Preguntas pendientes que el usuario debe responder
+
+[lista de preguntas específicas que necesitan respuesta antes de continuar con decisiones bloqueantes]
+```
+
+## Paso 5 — Manejo de cambios sin commitear
+
+Si hay cambios sin commitear, recomienda explícitamente qué hacer:
+
+**Opción A — Si el código es funcional pero incompleto:**
+```
+Los cambios sin commitear son trabajo en progreso. Recomiendo:
+git stash push -m "WIP: [descripción] — checkpoint [fecha]"
+```
+
+**Opción B — Si el código es funcional y completo:**
+```
+Los cambios son funcionales. Recomiendo commitear antes de pausar:
+git add [archivos específicos]
+git commit -m "feat(fase-N): [descripción del trabajo completado]"
+```
+
+**Opción C — Si no hay cambios:**
+```
+No hay cambios sin commitear. El repositorio está limpio. Puedes pausar sin riesgo.
+```
+
+Pregunta al usuario cuál prefiere o si tiene otra preferencia. NO ejecutes el git stash ni el commit sin confirmación explícita.
+
+## Paso 6 — Reporte al usuario
+
+```
+Checkpoint guardado.
+
+Estado capturado:
+- Fase activa: Fase N — [nombre]
+- Posición en el flujo: [descripción]
+- Decisiones pendientes: [N] ([N bloqueantes])
+- Cambios sin commitear: [sí/no — con acción recomendada]
+
+Archivos creados/actualizados:
+- .planning/STATE.md
+- .planning/continue-here.md
+
+Para retomar: lee .planning/continue-here.md
+Comando de retoma: [comando exacto]
+```
+
+## Reglas de comportamiento
+
+- El STATE.md debe ser comprensible sin haber participado en la sesión actual.
+- El continue-here.md debe poder leerse en menos de 2 minutos y dar contexto suficiente para retomar.
+- NUNCA ejecutes comandos git destructivos (reset, checkout --, clean) en este paso.
+- NUNCA elimines información del STATE.md anterior — si ya existía, fusiona la información nueva con la existente.
+- Si el proyecto no tiene ningún archivo de planeación, crea el STATE.md de todas formas con lo que puedas inferir.
+- Las decisiones pendientes bloqueantes deben estar al principio del continue-here.md, no al final.