@saulwade/swl-ses 2.6.0 → 2.8.0

package/comandos/swl/compactar.md

@@ -1,310 +1,310 @@
----
-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 en `~/.claude/skills/` (skills oficiales de Anthropic) o procede sin skill auxiliar — el algoritmo de 5 fases es zero-deps. Documenta lo que cargaste o que procediste sin skill.
-
-## 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 estado está a salvo en disco. IMPORTANTE: este comando NO compacta la
-ventana de contexto — eso es una operación del harness que el agente no
-puede ejecutar. Para compactar de verdad, AHORA ejecuta TÚ una de estas:
-
-  /compact          ← built-in de Claude Code: trunca la ventana usando
-                       el estado ya persistido (recomendado para seguir
-                       en la misma sesión)
-  /clear o sesión nueva ← arranque limpio; pega la instrucción de arranque
-                       del Paso 7
-
-Próximo comando de trabajo (tras compactar): [comando exacto]
-```
-
-## Paso 9 — Por qué este comando NO compacta la ventana (límite del harness)
-
-La compactación REAL del contexto (truncar la conversación) es una operación
-exclusiva del harness de Claude Code: el `/compact` built-in o el auto-compact.
-Un comando `/swl:*` corre DENTRO de la conversación y el modelo no tiene
-ninguna herramienta para truncar su propia ventana — por diseño.
-
-División de responsabilidades:
-
-| Mitad | Quién | Qué hace |
-|-------|-------|----------|
-| `/swl:compactar` | el agente | Persiste el estado a disco (COMPACTACION.md + ESTADO.md) para que NADA se pierda al truncar |
-| `/compact` | el usuario (harness) | Trunca la ventana de verdad. Sin la mitad anterior, perdería las decisiones no escritas |
-
-El error a prevenir: ejecutar `/compact` SIN haber corrido `/swl:compactar`
-antes (estado solo en la memoria de la conversación → se pierde). El orden
-correcto siempre es: `/swl:compactar` → `/compact`.
-
-## 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.
+---
+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 en `~/.claude/skills/` (skills oficiales de Anthropic) o procede sin skill auxiliar — el algoritmo de 5 fases es zero-deps. Documenta lo que cargaste o que procediste sin skill.
+
+## 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 estado está a salvo en disco. IMPORTANTE: este comando NO compacta la
+ventana de contexto — eso es una operación del harness que el agente no
+puede ejecutar. Para compactar de verdad, AHORA ejecuta TÚ una de estas:
+
+  /compact          ← built-in de Claude Code: trunca la ventana usando
+                       el estado ya persistido (recomendado para seguir
+                       en la misma sesión)
+  /clear o sesión nueva ← arranque limpio; pega la instrucción de arranque
+                       del Paso 7
+
+Próximo comando de trabajo (tras compactar): [comando exacto]
+```
+
+## Paso 9 — Por qué este comando NO compacta la ventana (límite del harness)
+
+La compactación REAL del contexto (truncar la conversación) es una operación
+exclusiva del harness de Claude Code: el `/compact` built-in o el auto-compact.
+Un comando `/swl:*` corre DENTRO de la conversación y el modelo no tiene
+ninguna herramienta para truncar su propia ventana — por diseño.
+
+División de responsabilidades:
+
+| Mitad | Quién | Qué hace |
+|-------|-------|----------|
+| `/swl:compactar` | el agente | Persiste el estado a disco (COMPACTACION.md + ESTADO.md) para que NADA se pierda al truncar |
+| `/compact` | el usuario (harness) | Trunca la ventana de verdad. Sin la mitad anterior, perdería las decisiones no escritas |
+
+El error a prevenir: ejecutar `/compact` SIN haber corrido `/swl:compactar`
+antes (estado solo en la memoria de la conversación → se pierde). El orden
+correcto siempre es: `/swl:compactar` → `/compact`.
+
+## 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.