theus-cli-linux-x64 0.2.84

package/vendor/theus-arsenal/skills/cache-por-hash/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: cache-por-hash
+description: Cachea resultados de procesamiento costoso de archivos usando hashes de contenido SHA-256 — independiente de la ruta, con autoinvalidación y separación en capa de servicio.
+---
+
+# Patrón de caché de archivos por hash de contenido
+
+Cachea los resultados de procesamiento costoso de archivos (parseo de PDF, extracción de texto, análisis de imágenes) usando hashes SHA-256 del contenido como claves de caché. A diferencia del cacheo por ruta, este enfoque sobrevive a movimientos/renombrados de archivos y se autoinvalida cuando el contenido cambia.
+
+## Cuándo activarla
+
+- Al construir pipelines de procesamiento de archivos (PDF, imágenes, extracción de texto)
+- Cuando el costo de procesamiento es alto y los mismos archivos se procesan repetidamente
+- Cuando necesitas una opción de CLI `--cache/--no-cache`
+- Cuando quieres añadir caché a funciones puras existentes sin modificarlas
+
+## Patrón central
+
+### 1. Clave de caché basada en el hash del contenido
+
+Usa el contenido del archivo (no la ruta) como clave de caché:
+
+```python
+import hashlib
+from pathlib import Path
+
+_HASH_CHUNK_SIZE = 65536  # trozos de 64 KB para archivos grandes
+
+def compute_file_hash(path: Path) -> str:
+    """SHA-256 del contenido del archivo (en trozos para archivos grandes)."""
+    if not path.is_file():
+        raise FileNotFoundError(f"Archivo no encontrado: {path}")
+    sha256 = hashlib.sha256()
+    with open(path, "rb") as f:
+        while True:
+            chunk = f.read(_HASH_CHUNK_SIZE)
+            if not chunk:
+                break
+            sha256.update(chunk)
+    return sha256.hexdigest()
+```
+
+**¿Por qué hash de contenido?** Renombrar/mover el archivo = acierto de caché. Cambio de contenido = invalidación automática. No se necesita archivo de índice.
+
+### 2. Dataclass congelada para la entrada de caché
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class CacheEntry:
+    file_hash: str
+    source_path: str
+    document: ExtractedDocument  # El resultado cacheado
+```
+
+### 3. Almacenamiento de caché basado en archivos
+
+Cada entrada de caché se guarda como `{hash}.json` — búsqueda O(1) por hash, sin archivo de índice.
+
+```python
+import json
+from typing import Any
+
+def write_cache(cache_dir: Path, entry: CacheEntry) -> None:
+    cache_dir.mkdir(parents=True, exist_ok=True)
+    cache_file = cache_dir / f"{entry.file_hash}.json"
+    data = serialize_entry(entry)
+    cache_file.write_text(json.dumps(data, ensure_ascii=False), encoding="utf-8")
+
+def read_cache(cache_dir: Path, file_hash: str) -> CacheEntry | None:
+    cache_file = cache_dir / f"{file_hash}.json"
+    if not cache_file.is_file():
+        return None
+    try:
+        raw = cache_file.read_text(encoding="utf-8")
+        data = json.loads(raw)
+        return deserialize_entry(data)
+    except (json.JSONDecodeError, ValueError, KeyError):
+        return None  # Trata la corrupción como fallo de caché
+```
+
+### 4. Envoltorio en capa de servicio (SRP)
+
+Mantén pura la función de procesamiento. Añade el caché como una capa de servicio separada.
+
+```python
+def extract_with_cache(
+    file_path: Path,
+    *,
+    cache_enabled: bool = True,
+    cache_dir: Path = Path(".cache"),
+) -> ExtractedDocument:
+    """Capa de servicio: verificar caché -> extraer -> escribir caché."""
+    if not cache_enabled:
+        return extract_text(file_path)  # Función pura, no sabe nada del caché
+
+    file_hash = compute_file_hash(file_path)
+
+    # Verificar caché
+    cached = read_cache(cache_dir, file_hash)
+    if cached is not None:
+        logger.info("Acierto de caché: %s (hash=%s)", file_path.name, file_hash[:12])
+        return cached.document
+
+    # Fallo de caché -> extraer -> guardar
+    logger.info("Fallo de caché: %s (hash=%s)", file_path.name, file_hash[:12])
+    doc = extract_text(file_path)
+    entry = CacheEntry(file_hash=file_hash, source_path=str(file_path), document=doc)
+    write_cache(cache_dir, entry)
+    return doc
+```
+
+## Decisiones de diseño clave
+
+| Decisión | Justificación |
+|----------|---------------|
+| Hash de contenido SHA-256 | Independiente de la ruta, autoinvalida al cambiar el contenido |
+| Nombres de archivo `{hash}.json` | Búsqueda O(1), sin necesidad de archivo de índice |
+| Envoltorio en capa de servicio | SRP: la extracción se mantiene pura, el caché es una responsabilidad aparte |
+| Serialización JSON manual | Control total sobre la serialización de dataclasses congeladas |
+| La corrupción devuelve `None` | Degradación elegante, se reprocesa en la siguiente ejecución |
+| `cache_dir.mkdir(parents=True)` | Creación perezosa del directorio en la primera escritura |
+
+## Buenas prácticas
+
+- **Hashea contenido, no rutas** — las rutas cambian, la identidad del contenido no
+- **Trocea los archivos grandes** al hashear — evita cargar archivos completos en memoria
+- **Mantén puras las funciones de procesamiento** — no deben saber nada del caché
+- **Registra aciertos/fallos de caché** con hashes truncados para depurar
+- **Maneja la corrupción con elegancia** — trata las entradas inválidas como fallos de caché, nunca revientes
+
+## Antipatrones a evitar
+
+```python
+# MAL: caché basado en rutas (se rompe al mover/renombrar archivos)
+cache = {"/path/to/file.pdf": result}
+
+# MAL: meter la lógica de caché dentro de la función de procesamiento (viola SRP)
+def extract_text(path, *, cache_enabled=False, cache_dir=None):
+    if cache_enabled:  # Ahora esta función tiene dos responsabilidades
+        ...
+
+# MAL: usar dataclasses.asdict() con dataclasses congeladas anidadas
+# (puede causar problemas con tipos anidados complejos)
+data = dataclasses.asdict(entry)  # Usa serialización manual en su lugar
+```
+
+## Cuándo usarlo
+
+- Pipelines de procesamiento de archivos (parseo de PDF, OCR, extracción de texto, análisis de imágenes)
+- Herramientas de CLI que se benefician de opciones `--cache/--no-cache`
+- Procesamiento por lotes donde los mismos archivos aparecen en distintas ejecuciones
+- Añadir caché a funciones puras existentes sin modificarlas
+
+## Cuándo NO usarlo
+
+- Datos que siempre deben estar frescos (feeds en tiempo real)
+- Entradas de caché que serían extremadamente grandes (considera streaming en su lugar)
+- Resultados que dependen de parámetros más allá del contenido del archivo (p. ej., distintas configuraciones de extracción)

package/vendor/theus-arsenal/skills/campana-marketing/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: campana-marketing
+description: Planificación y ejecución integral de campañas de marketing. Cubre investigación de
+  audiencia, posicionamiento, definición del ángulo de campaña, copy de landing pages, secuencias
+  de correo, posts sociales, copy de anuncios, guiones de video corto y calendarios de contenido.
+  Úsala como capa de orquestación para lanzamientos multicanal de producto.
+---
+
+# Campaña de marketing
+
+Planifica y ejecuta campañas de lanzamiento que convierten — no solo campañas que se publican.
+
+## Cuándo usarla
+
+- Al planificar el lanzamiento de un producto o funcionalidad.
+- Al construir una suite completa de contenido a partir de un solo brief de producto.
+- Al definir el posicionamiento y el ángulo de campaña antes de escribir cualquier copy.
+- Al orquestar múltiples tipos de contenido en varios canales.
+- Al revisar copy por calidad de conversión y consistencia de marca.
+
+## Innegociables
+
+1. Define el posicionamiento antes de escribir cualquier copy. Todo el copy fluye del ángulo.
+2. Investiga a la audiencia antes de asumir que conoces su lenguaje o sus miedos.
+3. Cada entregable debe cumplir un propósito claro dentro del arco de la campaña.
+4. La especificidad vence a los adjetivos en todo formato y canal.
+5. La misma voz debe recorrer todos los canales y todas las piezas.
+6. Ningún copy se publica sin pasar la puerta de calidad.
+
+## Flujo de la campaña
+
+### Fase 1: Investigación
+
+Usa `investigacion-mercado` para:
+
+- Perfilar a la audiencia objetivo (jobs-to-be-done, miedos, lenguaje, alternativas que usa).
+- Mapear 3+ competidores directos o adyacentes (posicionamiento, huecos, debilidades de mensaje).
+- Identificar 1–3 insights de audiencia que el ángulo de la campaña explotará.
+
+Entregable: un brief de investigación corto (perfil de audiencia + resumen competitivo + insights clave).
+
+### Fase 2: Posicionamiento
+
+Produce:
+
+- Declaración del beneficio central (una frase, sin lista de features, sin jerga).
+- Fórmula de posicionamiento: "[Producto] ayuda a [audiencia] a [lograr resultado] mediante [mecanismo]".
+- Ángulo de campaña: la tensión, insight o momento específico en el que vive toda la campaña.
+- Perfil de tono: fíjalo antes de escribir (delega en `voz-de-marca` para una captura de voz durable y reutilizable entre sesiones).
+
+No escribas ningún copy hasta que el posicionamiento y el ángulo estén aprobados.
+
+### Fase 3: Producción de contenido
+
+Produce en este orden — cada capa informa a la siguiente:
+
+1. **Copy de landing page** (todas las secciones: hero, problema, solución, features, cómo funciona, prueba, CTA).
+2. **Secuencia de correos** (cada correo tiene un propósito; sigue el arco: problema → educación → agitación → solución → prueba → urgencia → CTA final).
+3. **Posts sociales** (nativos por plataforma vía `motor-de-contenido`; LinkedIn y X son formatos distintos, no el mismo copy redimensionado).
+4. **Guiones de video corto** (bloqueados por timestamps; escritos para pantalla y oído, no para la página).
+5. **Variantes de copy de anuncios** (3–4 variantes que prueben distintos ángulos o segmentos de audiencia).
+6. **Calendario de contenido** (cronograma día a día con canal, tipo, timing y dependencias).
+
+### Fase 4: Revisión
+
+Somete cada entregable a la puerta:
+
+- Prueba de 5 segundos en todo el copy hero / above-the-fold (claro para quién es, qué hace, por qué actuar ahora).
+- Auditoría de CTA (uno por pieza, específico, ganado — no exigido).
+- Verificación de consistencia de tono en todos los canales.
+- Auditoría de afirmaciones (toda afirmación es específica y respaldable).
+- Consistencia entre canales (las afirmaciones de los anuncios coinciden con la landing; el cuerpo del correo coincide con su asunto).
+
+## Contrato de salida
+
+Una campaña completa entrega:
+
+1. **Brief de posicionamiento** — ángulo, declaración del beneficio central, perfil de tono.
+2. **Copy de landing page** — hero, problema, solución, features, cómo funciona, prueba, CTA.
+3. **Secuencia de correos** — asunto + preview + cuerpo + CTA por correo, etiquetados por día y propósito.
+4. **Posts de LinkedIn** — 3+ posts nativos con ángulos distintos.
+5. **Posts de X** — 5+ posts independientes + 1 hilo.
+6. **Guiones de video corto** — 2+ guiones bloqueados por timestamps con notas de dirección visual.
+7. **Variantes de copy de anuncios** — titular corto / titular largo / cuerpo por variante.
+8. **Calendario de contenido** — cronograma día a día con canal, tipo de contenido, timing y dependencias.
+9. **Resumen de revisión de copy** — problemas señalados y preguntas abiertas antes de publicar nada.
+
+## Puerta de calidad
+
+Antes de entregar cualquier pieza:
+
+- Todos los entregables suenan al mismo autor.
+- No quedan superlativos huecos ni adjetivos de relleno.
+- Cada CTA es específico y ganado (nunca "saber más" o "haz clic aquí").
+- Ningún copy se duplica textualmente entre plataformas.
+- El copy hero pasa la prueba de 5 segundos.
+- Los asuntos de correo coinciden con el cuerpo (sin cebo y cambio).
+- Las afirmaciones de los anuncios coinciden exactamente con las de la landing.
+- Ningún copy funcionaría sin cambios para otro producto de la categoría.
+
+## Prohibiciones estrictas
+
+Borra y reescribe cualquier:
+
+- "revolucionario", "que cambia las reglas del juego", "de clase mundial", "de vanguardia".
+- "En el competitivo panorama actual".
+- Urgencia falsa sin un plazo real detrás.
+- Prueba social hueca sin datos concretos ("miles confían en nosotros").
+- CTA genérico ("saber más", "descubre más", "haz clic aquí").
+- Copy que podría trasplantarse sin cambios a la campaña de un competidor.
+
+## Skills relacionadas
+
+- `voz-de-marca` — captura de voz derivada de fuentes (ejecutar antes de la producción de contenido).
+- `motor-de-contenido` — producción de contenido nativo por plataforma.
+- `publicacion-cruzada` — distribución multiplataforma.
+- `investigacion-mercado` — inteligencia de audiencia y competencia.
+- `seo` — optimización on-page para el copy de la landing page.

package/vendor/theus-arsenal/skills/capacidad-producto/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: capacidad-producto
+description: Traduce la intención de un PRD, una petición de roadmap o una discusión de producto en un plan de capacidad listo para implementar, que expone restricciones, invariantes, interfaces y decisiones sin resolver antes de iniciar trabajo multi-servicio. Úsala cuando se necesita un carril PRD-a-SRS nativo de Theus en lugar de prosa de planificación vaga.
+version: "1.0.0"
+---
+
+# Capacidad de producto
+
+Esta skill convierte la intención de producto en restricciones de ingeniería explícitas.
+
+Úsala cuando la brecha no es "¿qué deberíamos construir?" sino "¿qué debe ser cierto exactamente antes de empezar a implementar?".
+
+## Cuándo usar
+
+- Existe un PRD, un ítem del roadmap, una discusión o una nota del fundador, pero las restricciones de implementación siguen implícitas
+- Una funcionalidad cruza varios servicios, repos o equipos y necesita un contrato de capacidad antes de programar
+- La intención de producto está clara, pero las implicaciones de arquitectura, datos, ciclo de vida o políticas siguen difusas
+- Los ingenieros senior repiten los mismos supuestos ocultos en cada revisión
+- Necesitas un artefacto reutilizable que sobreviva entre entornos y sesiones
+
+## Artefacto canónico
+
+Si el repo tiene un archivo duradero de contexto de producto como `PRODUCT.md`, `docs/product/` o un directorio de especificaciones de programa, actualízalo ahí.
+
+Si aún no existe un manifiesto de capacidades, crea uno usando la plantilla en:
+
+- `docs/examples/product-capability-template.md`
+
+El objetivo no es crear otra pila de planificación. El objetivo es hacer que las restricciones de capacidad ocultas sean duraderas y reutilizables.
+
+## Reglas innegociables
+
+- No inventes verdades de producto. Marca las preguntas sin resolver de forma explícita.
+- Separa las promesas visibles al usuario de los detalles de implementación.
+- Distingue qué es política fija, qué es preferencia de arquitectura y qué sigue abierto.
+- Si la petición entra en conflicto con restricciones existentes del repo, dilo con claridad en lugar de suavizarlo.
+- Prefiere un artefacto de capacidad reutilizable sobre notas ad hoc dispersas.
+
+## Entradas
+
+Lee solo lo necesario:
+
+1. Intención de producto
+   - issue, discusión, PRD, nota del roadmap, mensaje del fundador
+2. Arquitectura actual
+   - docs relevantes del repo, contratos, schemas, rutas, workflows existentes
+3. Contexto de capacidad existente
+   - `PRODUCT.md`, documentos de diseño, RFCs, notas de migración, docs del modelo operativo
+4. Restricciones de entrega
+   - auth, facturación, cumplimiento, rollout, compatibilidad hacia atrás, rendimiento, política de revisión
+
+## Flujo de trabajo central
+
+### 1. Reformula la capacidad
+
+Comprime la petición en una declaración precisa:
+
+- quién es el usuario u operador
+- qué nueva capacidad existe después de que esto se lance
+- qué resultado cambia gracias a ella
+
+Si esta declaración es débil, la implementación se desviará.
+
+### 2. Resuelve las restricciones de la capacidad
+
+Extrae las restricciones que deben cumplirse antes de la implementación:
+
+- reglas de negocio
+- límites de alcance
+- invariantes
+- fronteras de confianza
+- propiedad de los datos
+- transiciones del ciclo de vida
+- requisitos de rollout / migración
+- expectativas de fallo y recuperación
+
+Estas son las cosas que a menudo viven solo en la memoria de los ingenieros senior.
+
+### 3. Define el contrato de cara a la implementación
+
+Produce un plan de capacidad estilo SRS con:
+
+- resumen de la capacidad
+- no-objetivos explícitos
+- actores y superficies
+- estados y transiciones requeridos
+- interfaces / entradas / salidas
+- implicaciones en el modelo de datos
+- restricciones de seguridad / facturación / política
+- requisitos de observabilidad y de operador
+- preguntas abiertas que bloquean la implementación
+
+### 4. Traduce a ejecución
+
+Termina con el traspaso exacto:
+
+- listo para implementación directa
+- necesita revisión de arquitectura primero
+- necesita clarificación de producto primero
+
+Si resulta útil, apunta al siguiente carril nativo de Theus:
+
+- `constructor-conectores`
+- `flujo-tdd`
+- `bucle-verificacion`
+
+## Formato de salida
+
+Devuelve el resultado en este orden:
+
+```text
+CAPACIDAD
+- reformulación en un párrafo
+
+RESTRICCIONES
+- reglas fijas, invariantes y límites
+
+CONTRATO DE IMPLEMENTACIÓN
+- actores
+- superficies
+- estados y transiciones
+- implicaciones de interfaz/datos
+
+NO-OBJETIVOS
+- lo que este carril explícitamente no posee
+
+PREGUNTAS ABIERTAS
+- bloqueos o decisiones de producto aún pendientes
+
+TRASPASO
+- qué debe ocurrir a continuación y qué carril de Theus debe tomarlo
+```
+
+## Buenos resultados
+
+- La intención de producto es ahora lo bastante concreta para implementarla sin redescubrir restricciones ocultas a mitad de un PR.
+- La revisión de ingeniería tiene un artefacto duradero en vez de depender de la memoria o del contexto de chats.
+- El plan resultante es reutilizable entre sesiones y superficies de planificación de Theus.

package/vendor/theus-arsenal/skills/cazador-vulnerabilidades/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: cazador-vulnerabilidades
+description: Caza problemas de seguridad explotables y de impacto real en repositorios. Se centra en
+  vulnerabilidades alcanzables de forma remota que califican para reportes reales, en lugar de
+  hallazgos ruidosos de solo alcance local.
+---
+
+# Cazador de vulnerabilidades
+
+Usa esta skill cuando el objetivo sea el descubrimiento práctico de vulnerabilidades para divulgación responsable o para un programa de recompensas (bug bounty), no una revisión amplia de buenas prácticas.
+
+## Cuándo usarla
+
+- Al escanear un repositorio en busca de vulnerabilidades explotables.
+- Al preparar un envío para Huntr, HackerOne o un programa de recompensas similar.
+- En triaje donde la pregunta es "¿esto realmente califica?" en lugar de "¿es esto teóricamente inseguro?".
+
+## Cómo funciona
+
+Sesga el análisis hacia rutas de ataque alcanzables de forma remota y controladas por el usuario, y descarta los patrones que las plataformas suelen rechazar por informativos o fuera de alcance.
+
+## Patrones dentro de alcance
+
+Estas son las clases de problemas que importan de forma consistente:
+
+| Patrón | CWE | Impacto típico |
+| --- | --- | --- |
+| SSRF por URLs controladas por el usuario | CWE-918 | acceso a la red interna, robo de metadatos de la nube |
+| Bypass de autenticación en middleware o guardas de API | CWE-287 | acceso no autorizado a cuentas o datos |
+| Deserialización remota o rutas de subida-a-RCE | CWE-502 | ejecución de código |
+| Inyección SQL en endpoints alcanzables | CWE-89 | exfiltración de datos, bypass de autenticación, destrucción de datos |
+| Inyección de comandos en manejadores de peticiones | CWE-78 | ejecución de código |
+| Path traversal en rutas que sirven archivos | CWE-22 | lectura o escritura arbitraria de archivos |
+| XSS de disparo automático | CWE-79 | robo de sesión, compromiso de administrador |
+
+## Descarta estos
+
+Suelen ser de baja señal o fuera del alcance de una recompensa, salvo que el programa indique lo contrario:
+
+- `pickle.loads`, `torch.load` o equivalentes de solo alcance local, sin ruta remota
+- `eval()` o `exec()` en herramientas de solo CLI
+- `shell=True` sobre comandos totalmente hardcodeados
+- Cabeceras de seguridad ausentes por sí solas
+- Quejas genéricas de rate-limiting sin impacto explotable
+- Self-XSS que requiere que la víctima pegue código manualmente
+- Inyección en CI/CD que no forma parte del alcance del programa objetivo
+- Código de demo, ejemplo o solo de pruebas
+
+## Flujo de trabajo
+
+1. Comprueba primero el alcance: reglas del programa, SECURITY.md, canal de divulgación y exclusiones.
+2. Encuentra los puntos de entrada reales: manejadores HTTP, subidas, trabajos en segundo plano, webhooks, parsers y endpoints de integración.
+3. Ejecuta herramientas estáticas donde ayuden, pero trátalas solo como entrada de triaje.
+4. Lee la ruta de código real de principio a fin.
+5. Demuestra que el control del usuario alcanza un sink relevante.
+6. Confirma la explotabilidad y el impacto con la PoC más pequeña y segura posible.
+7. Comprueba si hay duplicados antes de redactar un reporte.
+
+## Bucle de triaje de ejemplo
+
+```bash
+semgrep --config=auto --severity=ERROR --severity=WARNING --json
+```
+
+Después filtra manualmente:
+
+- descarta pruebas, demos, fixtures y código vendorizado
+- descarta rutas de solo alcance local o no alcanzables
+- conserva solo los hallazgos con una ruta clara de red o controlada por el usuario
+
+## Estructura del reporte
+
+```markdown
+## Descripción
+[Qué es la vulnerabilidad y por qué importa]
+
+## Código vulnerable
+[Ruta del archivo, rango de líneas y un fragmento pequeño]
+
+## Prueba de concepto
+[Petición o script mínimo que funciona]
+
+## Impacto
+[Qué puede lograr el atacante]
+
+## Versión afectada
+[Versión, commit u objetivo de despliegue probado]
+```
+
+## Puerta de calidad
+
+Antes de enviar:
+
+- La ruta de código es alcanzable desde un usuario real o desde una frontera de red
+- La entrada está genuinamente controlada por el usuario
+- El sink es relevante y explotable
+- La PoC funciona
+- El problema no está ya cubierto por un advisory, un CVE o un ticket abierto
+- El objetivo está realmente dentro del alcance del programa de recompensas
+
+## Skills relacionadas
+
+- `revision-seguridad`
+- `vigilancia-canary`

package/vendor/theus-arsenal/skills/compactacion-estrategica/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: compactacion-estrategica
+description: Sugiere compactar el contexto manualmente en puntos lógicos del flujo de trabajo (fin de fase, cambio de tarea) en lugar de depender de la auto-compactación arbitraria. Incluye guía de decisión y qué sobrevive a la compactación.
+---
+
+# Compactación estratégica
+
+Sugiere ejecutar `/compact` manualmente en puntos estratégicos del flujo de trabajo, en lugar de depender de la auto-compactación en momentos arbitrarios.
+
+## Cuándo activarla
+
+- Sesiones largas que se acercan al límite de contexto (200K+ tokens)
+- Tareas multifase (investigar → planificar → implementar → probar)
+- Al alternar entre tareas no relacionadas dentro de la misma sesión
+- Tras completar un hito importante y empezar trabajo nuevo
+- Cuando las respuestas se ralentizan o pierden coherencia (presión de contexto)
+
+## ¿Por qué compactación estratégica?
+
+La auto-compactación se dispara en puntos arbitrarios:
+- A menudo en mitad de una tarea, perdiendo contexto importante
+- Sin conciencia de los límites lógicos de la tarea
+- Puede interrumpir operaciones complejas de varios pasos
+
+La compactación estratégica en límites lógicos:
+- **Tras explorar, antes de ejecutar** — compacta el contexto de investigación, conserva el plan de implementación
+- **Tras completar un hito** — arranque limpio para la siguiente fase
+- **Antes de grandes cambios de contexto** — limpia el contexto de exploración antes de una tarea distinta
+
+## Cómo funciona
+
+El script `suggest-compact.js` se ejecuta en PreToolUse (Edit/Write) y combina dos señales:
+
+1. **Tamaño del contexto (primaria)** — Lee el último registro `usage` de la transcripción de la sesión (`transcript_path` en el payload del hook) y suma `input_tokens + cache_read_input_tokens + cache_creation_input_tokens` (el tamaño real del contexto del turno). Sugiere `/compact` en un umbral escalado por ventana — 160k tokens en una ventana de 200k, 250k en una de 1M (detectada por un marcador de modelo `[1m]`, o inferida cuando los tokens observados ya superan 200k) — y vuelve a recordarlo por cada 60k tokens adicionales de crecimiento del contexto
+2. **Conteo de llamadas a herramientas (secundaria)** — Cuenta las invocaciones de herramientas de la sesión; sugiere al alcanzar un umbral configurable (por defecto: 50 llamadas), y luego cada 25 llamadas
+
+El conteo de herramientas por sí solo es un proxy débil de la presión de la ventana: unas pocas lecturas de archivos grandes o respuestas MCP pueden llenar la ventana en muy pocas llamadas, mientras que muchas llamadas pequeñas pueden cruzar las 50 con la ventana casi vacía. La señal de tamaño de contexto se dispara cuando realmente importa.
+
+## Configuración del hook
+
+El plugin ya registra `suggest-compact.js` en su `hooks/hooks.json` (id de hook `pre-edit-write-suggest-compact`, activo en los perfiles `standard` y `strict`). No necesitas configurar nada. Para desactivarlo puntualmente, usa `THEUS_DISABLED_HOOKS=pre-edit-write-suggest-compact` o cambia de perfil con `THEUS_HOOK_PROFILE=minimal`. No dupliques el registro en tu configuración personal: un hook registrado dos veces se ejecuta dos veces.
+
+## Configuración
+
+Variables de entorno:
+- `COMPACT_THRESHOLD` — llamadas a herramientas antes de la primera sugerencia (por defecto: 50)
+- `COMPACT_CONTEXT_THRESHOLD` — tokens de contexto antes de la sugerencia por tamaño (por defecto: 160000 en ventana de 200k, 250000 en ventana de 1M; `0` desactiva esta señal)
+- `COMPACT_CONTEXT_INTERVAL` — tokens de contexto adicionales antes de repetir la sugerencia (por defecto: 60000)
+- `COMPACT_STATE_TTL_DAYS` — días antes de barrer los archivos de estado por sesión obsoletos del directorio temporal (por defecto: 14)
+
+## Guía de decisión de compactación
+
+Usa esta tabla para decidir cuándo compactar:
+
+| Transición de fase | ¿Compactar? | Por qué |
+|--------------------|-------------|---------|
+| Investigación → Planificación | Sí | El contexto de investigación es voluminoso; el plan es el destilado |
+| Planificación → Implementación | Sí | El plan vive en la lista de tareas o en un archivo; libera contexto para el código |
+| Implementación → Pruebas | Quizás | Consérvalo si las pruebas referencian código reciente; compacta si cambias de foco |
+| Depuración → Siguiente funcionalidad | Sí | Las trazas de depuración contaminan el contexto del trabajo no relacionado |
+| A mitad de implementación | No | Perder nombres de variables, rutas de archivos y estado parcial sale caro |
+| Tras un enfoque fallido | Sí | Limpia el razonamiento del callejón sin salida antes de intentar otro enfoque |
+
+## Qué sobrevive a la compactación
+
+Entender qué persiste te permite compactar con confianza:
+
+| Persiste | Se pierde |
+|----------|-----------|
+| Instrucciones de AGENTS.md | Razonamiento y análisis intermedios |
+| Lista de tareas (TodoWrite) | Contenido de archivos leídos previamente |
+| Archivos de memoria (`~/.theus/arsenal/`) | Contexto conversacional de varios pasos |
+| Estado de git (commits, ramas) | Historial y conteos de llamadas a herramientas |
+| Archivos en disco | Preferencias matizadas expresadas verbalmente por el usuario |
+
+## Buenas prácticas
+
+1. **Compacta después de planificar** — con el plan cerrado en la lista de tareas, compacta para empezar limpio
+2. **Compacta después de depurar** — limpia el contexto de resolución de errores antes de continuar
+3. **No compactes a mitad de implementación** — preserva el contexto para los cambios relacionados
+4. **Lee la sugerencia** — el hook te dice *cuándo*, tú decides *si*
+5. **Escribe antes de compactar** — guarda el contexto importante en archivos o memoria antes de compactar
+6. **Usa `/compact` con un resumen** — añade un mensaje personalizado: `/compact Céntrate en implementar el middleware de auth`
+
+## Patrones de optimización de tokens
+
+### Carga diferida con tabla de disparadores
+En lugar de cargar el contenido completo de las skills al inicio de la sesión, usa una tabla que mapee palabras clave a rutas de skills. Las skills se cargan solo al dispararse, reduciendo el contexto base en 50 %+:
+
+| Disparador | Skill | Cargar cuando |
+|------------|-------|---------------|
+| "test", "tdd", "cobertura" | flujo-tdd | El usuario menciona pruebas |
+| "seguridad", "auth", "xss" | revision-seguridad | Trabajo relacionado con seguridad |
+| "deploy", "ci/cd" | patrones-despliegue | Contexto de despliegue |
+
+### Conciencia de la composición del contexto
+Monitorea qué consume tu ventana de contexto:
+- **Archivos AGENTS.md** — siempre cargados, mantenlos ligeros
+- **Skills cargadas** — cada skill añade 1-5K tokens
+- **Historial de conversación** — crece con cada intercambio
+- **Resultados de herramientas** — lecturas de archivos y búsquedas añaden volumen
+
+### Detección de instrucciones duplicadas
+Fuentes comunes de contexto duplicado:
+- Las mismas reglas en la configuración global (`~/.theus/rules/`) y en la del proyecto (`.theus/rules/`)
+- Skills que repiten las instrucciones de AGENTS.md
+- Varias skills que cubren dominios solapados
+
+Revisa periódicamente y deja cada instrucción en un solo lugar.
+
+## Relacionado
+
+- Hooks de persistencia de memoria — para estado que sobrevive a la compactación
+- Skill `aprendizaje-continuo-v2` — extrae patrones antes de que termine la sesión
+- Skill `presupuesto-contexto` — gestión proactiva del presupuesto de contexto