@saulwade/swl-ses 1.0.0

package/comandos/swl/checkpoint.md

@@ -0,0 +1,330 @@
+---
+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 ESTADO.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/ESTADO.md` — estado previo si existe.
+2. `.planning/HOJA-RUTA.md` — estado global del proyecto.
+3. `.planning/PROYECTO.md` — contexto del proyecto.
+4. Cualquier `.planning/fases/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 HOJA-RUTA.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 ESTADO.md
+
+Sobreescribe `.planning/ESTADO.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/fases/0N-PLAN.md` — plan de la fase activa
+2. `.planning/fases/0N-CONTEXTO.md` — contexto de la fase activa
+3. [otros archivos críticos]
+````
+
+## Paso 3b — Actualización del execution-state.json
+
+Si hay un plan multi-agente activo, persistir el estado de ejecución serializable
+en `.planning/execution-state.json`. Este archivo complementa ESTADO.md con datos
+estructurados que permiten reanudar sin reconstruir contexto desde texto.
+
+```bash
+# Ver el estado actual si existe
+cat .planning/execution-state.json 2>/dev/null || echo "(sin estado de ejecución activo)"
+```
+
+Si existe, actualizar el campo `proximoAgente` con la siguiente tarea pendiente.
+Si no existe y hay un plan en progreso con agentes ejecutados en esta sesión, crear el estado:
+
+```javascript
+// Ejemplo de actualización manual desde el orquestador o skill ejecutar-fase:
+const es = require('./hooks/lib/execution-state');
+
+// Registrar agentes completados en esta sesión
+// es.completarAgente(cwd, 'nombre-agente', 'slice', { resumen: '...' });
+
+// Registrar el próximo agente a ejecutar
+// es.establecerProximo(cwd, 'proximo-agente', 'proximo-slice');
+
+// Ver resumen del estado
+console.log(es.formatearResumen(process.cwd()));
+```
+
+Incluir el resumen de `formatearResumen()` en el `continue-here.md` generado en el Paso 4,
+bajo la sección "Qué se estaba haciendo".
+
+## 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/ESTADO.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/ESTADO.md
+- .planning/continue-here.md
+
+Para retomar: lee .planning/continue-here.md
+Comando de retoma: [comando exacto]
+```
+
+## Reglas de comportamiento
+
+- El ESTADO.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 ESTADO.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 ESTADO.md de todas formas con lo que puedas inferir.
+- Las decisiones pendientes bloqueantes deben estar al principio del continue-here.md, no al final.

package/comandos/swl/compactar.md

@@ -0,0 +1,283 @@
+---
+name: swl:compactar
+description: Anti-context-rot. Guarda el estado completo del trabajo actual, genera un resumen denso de todo lo hecho y prepara el contexto para una sesión fresca. Úsalo cuando el contexto de la conversación se vuelve largo o cuando hay pérdida de coherencia.
+allowed_tools: ["Read", "Write", "Edit", "Bash", "Glob", "Grep"]
+---
+
+# /swl:compactar — Gestión de contexto y anti-rot
+
+Eres el gestor de continuidad del proyecto SWL. El "context rot" (degradación del contexto) ocurre cuando la conversación se vuelve tan larga que el modelo pierde precisión, repite errores ya resueltos o pierde el hilo del trabajo. Tu trabajo es prevenir ese deterioro.
+
+Este comando es diferente de `/swl:checkpoint`: mientras checkpoint guarda estado para reanudar *después*, compactar prepara el contexto para continuar *en la misma sesión o en la siguiente*, generando un briefing denso que permite un arranque de contexto fresco sin pérdida de información.
+
+## Señales de que necesitas este comando
+
+- La conversación tiene más de 30 intercambios
+- El modelo empieza a olvidar decisiones tomadas antes en la sesión
+- Hay inconsistencias entre lo que se dijo al inicio y lo que se está haciendo
+- El usuario dice "creía que habíamos decidido que..." y hay discrepancia
+- Estás a punto de empezar una tarea larga y quieres contexto limpio
+
+## Paso 0 — Carga de habilidades
+
+```
+Skill("compactacion-contexto")
+```
+
+Si no existe, busca alternativas: `Skill("systematic-debugging")` para razonamiento estructurado. Documenta lo que cargaste.
+
+## Paso 1 — Auditoría del contexto activo
+
+Antes de compactar, audita el estado del trabajo haciendo una lectura rápida:
+
+### Archivos de planeación
+Lee en orden:
+1. `.planning/PROYECTO.md`
+2. `.planning/HOJA-RUTA.md`
+3. `.planning/ESTADO.md` (si existe)
+4. `.planning/continue-here.md` (si existe)
+5. El PLAN.md de la fase activa
+6. El RESUMEN.md de la fase activa (si existe)
+7. El CONTEXTO.md de la fase activa
+
+### Estado de Git
+```bash
+git log --oneline -30
+git status
+git stash list
+```
+
+### Código reciente
+Identifica los 5 archivos de código más recientemente modificados:
+```bash
+git log --name-only --pretty=format: -10 | grep -v '^$' | sort -u | head -20
+```
+
+Lee brevemente esos archivos para entender el estado actual del código.
+
+## Paso 2 — Construcción del mapa de decisiones
+
+Reconstruye el árbol de decisiones importantes de la sesión. Busca en los archivos de planeación y en la conversación activa:
+
+### Decisiones de arquitectura
+- ¿Qué patrón arquitectónico se eligió y por qué?
+- ¿Qué alternativas se descartaron?
+
+### Decisiones de implementación
+- ¿Qué librerías/versiones se eligieron?
+- ¿Qué workarounds se aplicaron y por qué?
+- ¿Qué cambios respecto al plan original se hicieron?
+
+### Decisiones de producto
+- ¿Qué funcionalidades se incluyeron o excluyeron?
+- ¿Qué prioridades cambiaron durante la ejecución?
+
+### Convenciones establecidas
+- Convenciones de nomenclatura de archivos
+- Estructura de módulos
+- Patrones de código adoptados en este proyecto
+
+## Paso 3 — Inventario de trabajo completado
+
+Genera una lista completa y precisa de todo lo que se hizo:
+
+### Por fase y slice
+Para cada fase ejecutada, lista:
+- Nombre y descripción de la fase
+- Slices completados con descripción de 1 línea
+- Commits creados (hash corto + mensaje)
+- Archivos creados (nuevos, no existentes antes del proyecto)
+- Archivos modificados (existían y se cambiaron)
+
+### Por área funcional
+Agrupa el trabajo por área:
+- Modelos de datos: qué tablas/colecciones se crearon
+- Endpoints/servicios: qué funcionalidad se expuso
+- Frontend: qué vistas/componentes se crearon
+- Infraestructura: qué configuración se estableció
+- Tests: qué cobertura existe
+
+## Paso 4 — Inventario de trabajo pendiente
+
+### Pendiente en la fase actual
+Si hay un plan con tareas sin completar, lista exactamente:
+- Slice actual: última tarea completada y siguiente tarea
+- Slices restantes: lista con nombre y descripción breve
+
+### Pendiente en el proyecto
+Todas las fases con estado "Pendiente" del HOJA-RUTA.md.
+
+### Deuda técnica registrada
+De los RESUMEN.md y VERIFICACION.md: lista de items de deuda con su severidad.
+
+### Decisiones pendientes
+De los archivos de contexto y plan: todo lo marcado como "[POR DEFINIR]", "[REQUIERE DECISIÓN]", o "[PENDIENTE DE ACLARAR]".
+
+## Paso 5 — Generación del COMPACTACION.md
+
+Crea `.planning/COMPACTACION.md` — el briefing de contexto denso:
+
+```markdown
+# Contexto compactado — [nombre del proyecto]
+
+**Compactado**: [fecha y hora]
+**Versión**: [número incremental — llevar contador]
+**Estado del proyecto**: [En progreso | Fase N de M completada]
+
+---
+
+## TL;DR — Para leer en 60 segundos
+
+**Proyecto**: [nombre] — [descripción de 1 oración]
+**Stack**: [tecnologías principales en una línea]
+**Posición actual**: Fase N — [nombre] — [estado]
+**Próximo comando**: `[comando exacto]`
+**Bloqueantes activos**: [N — listar si hay, o "ninguno"]
+
+---
+
+## Mapa de decisiones críticas
+
+### No repetir estas discusiones — ya están resueltas
+
+| Decisión | Resolución | Razón |
+|----------|-----------|-------|
+| [tema] | [qué se decidió] | [por qué] |
+| [tema] | [qué se decidió] | [por qué] |
+
+### Convenciones de código en este proyecto
+
+[lista de convenciones adoptadas — nombrado, estructura, patrones]
+
+### Restricciones conocidas
+
+[lista de cosas que NO se pueden hacer en este proyecto y por qué]
+
+---
+
+## Trabajo completado
+
+### Fase 1 — [nombre] — COMPLETADA
+- [descripción de 2-3 oraciones de qué se hizo]
+- Archivos clave: [lista de 3-5 archivos más importantes]
+- Tests: [N tests, cobertura si conocida]
+
+[... por cada fase completada ...]
+
+### Fase N — [nombre] — EN PROGRESO
+**Completado**:
+- [slice 1]: [descripción]
+- [slice 2]: [descripción]
+
+**Pendiente**:
+- [slice 3]: [descripción] — PRÓXIMO
+- [slice 4]: [descripción]
+
+---
+
+## Estado técnico actual
+
+### Arquitectura implementada hasta ahora
+[descripción breve pero completa de la arquitectura real — no la planificada, la real]
+
+### Modelos de datos existentes
+[lista de tablas/colecciones/modelos con sus campos principales]
+
+### Endpoints existentes
+[lista de endpoints implementados con método y ruta]
+
+### Componentes frontend existentes
+[lista de componentes/vistas implementadas]
+
+---
+
+## Trabajo pendiente
+
+### Inmediato (esta sesión o la siguiente)
+[lista ordenada por prioridad]
+
+### Corto plazo (próximas fases)
+[fases pendientes del roadmap]
+
+### Deuda técnica registrada
+[lista con severidad]
+
+---
+
+## Decisiones pendientes que requieren respuesta humana
+
+[lista numerada — las que bloquean el trabajo van primero]
+
+1. **[BLOQUEANTE]** [pregunta]
+2. **[NO BLOQUEANTE]** [pregunta]
+
+---
+
+## Contexto de la última sesión de trabajo
+
+[narrativa de 3-5 oraciones describiendo qué se hizo en la sesión actual, qué problemas se encontraron, qué decisiones se tomaron, y dónde se paró]
+
+---
+
+## Cómo usar este documento al arrancar sesión nueva
+
+1. Lee la sección TL;DR primero.
+2. Lee "Mapa de decisiones críticas" para no repetir discusiones.
+3. Ejecuta `[comando de continuación]`.
+4. Carga las habilidades relevantes según el stack.
+5. Lee el PLAN.md de la fase activa si vas a ejecutar.
+```
+
+## Paso 6 — Actualización del ESTADO.md
+
+Actualiza `.planning/ESTADO.md` con referencia al COMPACTACION.md:
+
+Agrega al inicio del ESTADO.md:
+```markdown
+> Contexto compactado disponible: `.planning/COMPACTACION.md` — [fecha]
+> Para contexto completo, lee COMPACTACION.md antes de ESTADO.md.
+```
+
+## Paso 7 — Preparación del contexto fresco
+
+Genera una instrucción de arranque para la próxima sesión. Esta instrucción es lo que el usuario puede copiar y pegar al inicio de una conversación nueva:
+
+```
+Para retomar el trabajo en [nombre del proyecto]:
+
+1. El proyecto está en [directorio absoluto]
+2. Lee .planning/COMPACTACION.md para el contexto completo
+3. El próximo comando es: [comando exacto]
+4. Hay [N] decisiones pendientes en el COMPACTACION.md sección "Decisiones pendientes"
+
+Copia y pega este mensaje al inicio de la nueva sesión.
+```
+
+## Paso 8 — Reporte al usuario
+
+```
+Contexto compactado.
+
+Resumen de la compactación:
+- Decisiones críticas documentadas: [N]
+- Trabajo completado capturado: [N slices en M fases]
+- Trabajo pendiente mapeado: [N slices en K fases]
+- Deuda técnica registrada: [N items]
+- Decisiones pendientes: [N (M bloqueantes)]
+
+Archivos actualizados:
+- .planning/COMPACTACION.md (creado/actualizado)
+- .planning/ESTADO.md (referencia agregada)
+
+El contexto está listo para continuar con sesión fresca.
+Próximo comando: [comando exacto]
+```
+
+## Reglas de comportamiento
+
+- El COMPACTACION.md debe reemplazar la necesidad de releer toda la conversación. Si alguien lo lee, debe poder continuar el trabajo.
+- NUNCA comprimas o elimines información importante. La densidad viene de estructura, no de omisión.
+- Las decisiones en el "Mapa de decisiones críticas" son sagradas — si están ahí, no se vuelven a discutir.
+- Lleva un número de versión incremental en el COMPACTACION.md. Cada compactación es una nueva versión.
+- Si hay un COMPACTACION.md previo, léelo antes de crear el nuevo — puede tener decisiones que no están en otros archivos.
+- El documento debe poder leerse en menos de 5 minutos. Si es más largo, has incluido demasiado detalle.