@saulwade/swl-ses 2.6.0 → 2.8.0

package/comandos/swl/checkpoint.md

@@ -1,325 +1,325 @@
----
-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,
-imprimir el resumen estructurado con el subcomando del CLI (resuelve cross-scope;
-ver `docs/invocacion-cli-cross-scope.md`):
-
-```bash
-swl-ses execution-state
-# fallback: npx -y @saulwade/swl-ses@latest execution-state
-```
-
-Incluir ese resumen en el `continue-here.md` generado en el Paso 4, bajo la
-sección "Qué se estaba haciendo". El registro de agentes
-(`completarAgente`/`establecerProximo`) lo gestiona el skill `ejecutar-fase`
-internamente; aquí solo se lee el resumen.
-
-## 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.
+---
+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,
+imprimir el resumen estructurado con el subcomando del CLI (resuelve cross-scope;
+ver `docs/invocacion-cli-cross-scope.md`):
+
+```bash
+swl-ses execution-state
+# fallback: npx -y @saulwade/swl-ses@latest execution-state
+```
+
+Incluir ese resumen en el `continue-here.md` generado en el Paso 4, bajo la
+sección "Qué se estaba haciendo". El registro de agentes
+(`completarAgente`/`establecerProximo`) lo gestiona el skill `ejecutar-fase`
+internamente; aquí solo se lee el resumen.
+
+## 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.