theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/optimizacion-costos-llm/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: optimizacion-costos-llm
+description: Patrones de optimización de costos para el uso de APIs de LLM — enrutamiento de modelos
+  según complejidad de la tarea, control de presupuesto, lógica de reintentos y caché de prompts.
+---
+
+# Pipeline de LLM consciente de costos
+
+Patrones para controlar el costo de las APIs de LLM sin sacrificar calidad. Combina enrutamiento de modelos, seguimiento de presupuesto, lógica de reintentos y caché de prompts en un pipeline componible.
+
+## Cuándo activarla
+
+- Al construir aplicaciones que llaman a APIs de LLM.
+- Al procesar lotes de ítems con complejidad variable.
+- Cuando hay que mantenerse dentro de un presupuesto de gasto en API.
+- Al optimizar costo sin sacrificar calidad en las tareas complejas.
+
+## Conceptos clave
+
+### 1. Enrutamiento de modelos por complejidad de la tarea
+
+Selecciona automáticamente modelos más baratos para tareas simples y reserva los modelos caros para las complejas. Usa constantes o configuración para los identificadores de modelo — nunca los codifiques dispersos por el código.
+
+```python
+# Identificadores según el catálogo de modelos contratado (config, no hardcodeo).
+MODELO_AVANZADO = config.modelo_avanzado   # nivel frontier: tareas complejas
+MODELO_RAPIDO = config.modelo_rapido       # nivel rápido: 3-4x más barato
+
+_UMBRAL_TEXTO_AVANZADO = 10_000  # caracteres
+_UMBRAL_ITEMS_AVANZADO = 30      # ítems
+
+def seleccionar_modelo(
+    longitud_texto: int,
+    cantidad_items: int,
+    modelo_forzado: str | None = None,
+) -> str:
+    """Selecciona el modelo según la complejidad de la tarea."""
+    if modelo_forzado is not None:
+        return modelo_forzado
+    if longitud_texto >= _UMBRAL_TEXTO_AVANZADO or cantidad_items >= _UMBRAL_ITEMS_AVANZADO:
+        return MODELO_AVANZADO  # tarea compleja
+    return MODELO_RAPIDO  # tarea simple (3-4x más barata)
+```
+
+### 2. Seguimiento de costos inmutable
+
+Registra el gasto acumulado con dataclasses congeladas. Cada llamada a la API devuelve un tracker nuevo — nunca muta el estado.
+
+```python
+from dataclasses import dataclass
+
+@dataclass(frozen=True, slots=True)
+class RegistroCosto:
+    model: str
+    input_tokens: int
+    output_tokens: int
+    cost_usd: float
+
+@dataclass(frozen=True, slots=True)
+class CostTracker:
+    budget_limit: float = 1.00
+    records: tuple[RegistroCosto, ...] = ()
+
+    def add(self, record: RegistroCosto) -> "CostTracker":
+        """Devuelve un tracker nuevo con el registro añadido (nunca muta self)."""
+        return CostTracker(
+            budget_limit=self.budget_limit,
+            records=(*self.records, record),
+        )
+
+    @property
+    def total_cost(self) -> float:
+        return sum(r.cost_usd for r in self.records)
+
+    @property
+    def over_budget(self) -> bool:
+        return self.total_cost > self.budget_limit
+```
+
+### 3. Reintentos acotados
+
+Reintenta solo ante errores transitorios. Falla rápido ante errores de autenticación o de petición inválida.
+
+```python
+# Ajusta la tupla a las excepciones del SDK de tu proveedor:
+# errores de conexión, límite de tasa y errores 5xx del servidor.
+_ERRORES_REINTENTABLES = (APIConnectionError, RateLimitError, InternalServerError)
+_MAX_REINTENTOS = 3
+
+def llamar_con_reintento(func, *, max_reintentos: int = _MAX_REINTENTOS):
+    """Reintenta solo ante errores transitorios; falla rápido ante el resto."""
+    for intento in range(max_reintentos):
+        try:
+            return func()
+        except _ERRORES_REINTENTABLES:
+            if intento == max_reintentos - 1:
+                raise
+            time.sleep(2 ** intento)  # backoff exponencial
+    # Errores de autenticación, petición inválida, etc. → propagar de inmediato
+```
+
+### 4. Caché de prompts
+
+Cachea los prompts de sistema largos para no reenviarlos en cada petición. La sintaxis exacta depende del proveedor; muchos aceptan marcar bloques cacheables en el mensaje:
+
+```python
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "text",
+                "text": system_prompt,
+                "cache_control": {"type": "ephemeral"},  # cachear este bloque
+            },
+            {
+                "type": "text",
+                "text": user_input,  # la parte variable
+            },
+        ],
+    }
+]
+```
+
+## Composición
+
+Combina las cuatro técnicas en una sola función de pipeline:
+
+```python
+def procesar(text: str, config: Config, tracker: CostTracker) -> tuple[Result, CostTracker]:
+    # 1. Enrutar modelo
+    model = seleccionar_modelo(len(text), items_estimados, config.modelo_forzado)
+
+    # 2. Verificar presupuesto
+    if tracker.over_budget:
+        raise BudgetExceededError(tracker.total_cost, tracker.budget_limit)
+
+    # 3. Llamar con reintentos + caché
+    response = llamar_con_reintento(lambda: client.messages.create(
+        model=model,
+        messages=construir_mensajes_cacheados(system_prompt, text),
+    ))
+
+    # 4. Registrar costo (inmutable)
+    record = RegistroCosto(model=model, input_tokens=..., output_tokens=..., cost_usd=...)
+    tracker = tracker.add(record)
+
+    return parsear_resultado(response), tracker
+```
+
+## Referencia de precios por nivel
+
+Los precios absolutos cambian con frecuencia — consulta siempre la tarifa vigente del proveedor o del catálogo de modelos contratado. Lo estable es la relación entre niveles:
+
+| Nivel de modelo | Uso típico | Costo relativo |
+|-----------------|------------|----------------|
+| Rápido | Clasificación, extracción, tareas simples en lote | 1x |
+| Equilibrado | Redacción, análisis, la mayoría de tareas | ~4x |
+| Frontier | Razonamiento complejo, tareas críticas | ~15-20x |
+
+## Buenas prácticas
+
+- **Empieza con el modelo más barato** y enruta al caro solo cuando se cumplan los umbrales de complejidad.
+- **Define límites de presupuesto explícitos** antes de procesar lotes — falla temprano en vez de sobregastar.
+- **Registra las decisiones de selección de modelo** para calibrar los umbrales con datos reales.
+- **Usa caché de prompts** para prompts de sistema de más de ~1024 tokens — ahorra costo y latencia.
+- **Nunca reintentes ante errores de autenticación o validación** — solo fallos transitorios (red, límite de tasa, error de servidor).
+
+## Antipatrones a evitar
+
+- Usar el modelo más caro para todas las peticiones sin importar la complejidad.
+- Reintentar ante todos los errores (desperdicia presupuesto en fallos permanentes).
+- Mutar el estado del seguimiento de costos (dificulta la depuración y la auditoría).
+- Codificar nombres de modelo dispersos por el código (usa constantes o configuración).
+- Ignorar el caché de prompts cuando los prompts de sistema son repetitivos.
+
+## Cuándo usarla
+
+- Cualquier aplicación que llame a APIs de LLM.
+- Pipelines de procesamiento por lotes donde el costo se acumula rápido.
+- Arquitecturas multimodelo que necesitan enrutamiento inteligente.
+- Sistemas en producción que necesitan barandillas de presupuesto.

package/vendor/theus-arsenal/skills/optimizador-conexiones/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: optimizador-conexiones
+description: Reorganiza la red del usuario en X y LinkedIn con poda revisada primero, recomendaciones
+  de seguimiento y borradores de contacto cálido por canal escritos con la voz real del usuario.
+  Úsala para limpiar listas de seguidos, crecer hacia las prioridades actuales o reequilibrar
+  un grafo social alrededor de relaciones de mayor señal.
+---
+
+# Optimizador de conexiones
+
+Reorganiza la red del usuario en lugar de tratar el contacto saliente como una lista de prospección de un solo sentido.
+
+Esta skill cubre:
+
+- Limpieza y expansión de la lista de seguidos en X
+- Análisis de seguimientos y conexiones en LinkedIn
+- Colas de poda con revisión previa obligatoria
+- Recomendaciones de a quién añadir o seguir
+- Identificación de rutas cálidas (warm paths)
+- Generación de borradores para correo (Apple Mail), DM de X y mensajes de LinkedIn con la voz real del usuario
+
+## Cuándo activarla
+
+- El usuario quiere podar a quién sigue en X
+- El usuario quiere reequilibrar a quién sigue o con quién mantiene conexión
+- El usuario dice "limpia mi red", "¿a quién debería dejar de seguir?", "¿a quién debería seguir?", "¿con quién debería reconectar?"
+- La calidad del contacto saliente depende de la estructura de la red, no solo de generar listas frías
+
+## Entradas requeridas
+
+Recopila o infiere:
+
+- Prioridades actuales y trabajo activo
+- Roles, industrias, geografías o ecosistemas objetivo
+- Selección de plataforma: X, LinkedIn o ambas
+- Lista de intocables (do-not-touch)
+- Modo: `pasada-ligera`, `estandar` o `agresivo`
+
+Si el usuario no especifica modo, usa `estandar`.
+
+## Requisitos de herramientas
+
+### Preferidas
+
+- `api-x` para inspeccionar el grafo de X y la actividad reciente
+- `inteligencia-leads` para el descubrimiento de objetivos y el ranking de rutas cálidas
+- `ranking-grafo-social` cuando el usuario quiere puntuar el valor de puente de forma independiente del flujo de leads
+- `busqueda-exa` o `investigacion-profunda` para enriquecer datos de personas y empresas
+- `voz-de-marca` antes de redactar cualquier contacto saliente
+
+### Alternativas
+
+- Control del navegador para el análisis y la redacción en LinkedIn
+- Control del navegador para X si la cobertura de la API es limitada
+- Borradores en Apple Mail / Mail.app vía automatización de escritorio (solo macOS) cuando el correo es el canal correcto
+
+## Salvaguardas por defecto
+
+- El comportamiento por defecto es revisión primero; nunca poda automática a ciegas
+- X: poda solo cuentas que el usuario sigue, nunca seguidores
+- LinkedIn: la eliminación de conexiones de 1.er grado siempre pasa por revisión manual primero
+- No envíes automáticamente DMs, invitaciones ni correos
+- Emite un plan de acción priorizado y los borradores antes de cualquier paso de aplicación
+
+## Reglas por plataforma
+
+### X
+
+- Los mutuos son más valiosos que los seguimientos de un solo sentido
+- Las cuentas que no devuelven el seguimiento pueden podarse con más agresividad
+- Las cuentas muy inactivas o desaparecidas deben aflorar rápido
+- El engagement, la calidad de la señal y el valor de puente pesan más que el número bruto de seguidores
+
+### LinkedIn
+
+- API primero solo si el usuario realmente tiene acceso a la API de LinkedIn
+- El flujo por navegador debe funcionar cuando no hay acceso a la API
+- Distingue seguimientos salientes de conexiones de 1.er grado aceptadas
+- Los seguimientos salientes pueden podarse con más libertad
+- Las conexiones de 1.er grado aceptadas van por defecto a revisión, nunca a eliminación automática
+
+## Modos
+
+### `pasada-ligera`
+
+- Poda solo seguimientos de un solo sentido de bajo valor y alta confianza
+- El resto aflora para revisión
+- Genera una lista pequeña de cuentas a añadir/seguir
+
+### `estandar`
+
+- Cola de poda equilibrada
+- Lista de conservación equilibrada
+- Cola priorizada de cuentas a añadir/seguir
+- Redacta introducciones cálidas o contacto directo donde aporte
+
+### `agresivo`
+
+- Cola de poda más grande
+- Menor tolerancia a seguimientos estancados sin reciprocidad
+- Sigue exigiendo revisión antes de aplicar
+
+## Modelo de puntuación
+
+Señales positivas:
+
+- Reciprocidad
+- Actividad reciente
+- Alineación con las prioridades actuales
+- Valor de puente en la red
+- Relevancia del rol
+- Historial real de engagement
+- Presencia y capacidad de respuesta recientes
+
+Señales negativas:
+
+- Cuenta desaparecida o abandonada
+- Seguimiento de un solo sentido estancado
+- Clúster temático fuera de las prioridades
+- Ruido de bajo valor
+- Falta de respuesta repetida
+- Sin seguimiento de vuelta cuando existen muchos reemplazos mejores
+
+Los mutuos y los puentes cálidos reales deben penalizarse con menos agresividad que los seguimientos de un solo sentido.
+
+## Flujo de trabajo
+
+1. Captura prioridades, restricciones de intocables y plataformas seleccionadas.
+2. Extrae el inventario actual de seguidos / conexiones.
+3. Puntúa las candidatas a poda con razones explícitas.
+4. Puntúa las candidatas a conservar con razones explícitas.
+5. Usa `inteligencia-leads` más las superficies de investigación para priorizar candidatas de expansión.
+6. Asigna el canal adecuado:
+   - DM de X para toques sociales cálidos y rápidos
+   - Mensaje de LinkedIn para adyacencia en el grafo profesional
+   - Borrador de Apple Mail para introducciones o contactos de mayor contexto
+7. Ejecuta `voz-de-marca` antes de redactar mensajes.
+8. Devuelve un paquete de revisión antes de cualquier paso de aplicación.
+
+## Formato del paquete de revisión
+
+```text
+INFORME DEL OPTIMIZADOR DE CONEXIONES
+=====================================
+
+Modo:
+Plataformas:
+Conjunto de prioridades:
+
+Cola de poda
+- usuario / perfil
+  razón:
+  confianza:
+  acción:
+
+Cola de revisión
+- usuario / perfil
+  razón:
+  riesgo:
+
+Conservar / proteger
+- usuario / perfil
+  valor de puente:
+
+Objetivos a añadir / seguir
+- persona
+  por qué ahora:
+  ruta cálida:
+  canal preferido:
+
+Borradores
+- DM de X:
+- LinkedIn:
+- Apple Mail:
+```
+
+## Reglas de contacto saliente
+
+- La ruta de correo por defecto es la creación de borradores en Apple Mail / Mail.app.
+- No envíes nada automáticamente.
+- Elige el canal según la calidez, la relevancia y la profundidad de contexto.
+- No fuerces un DM cuando un correo — o no contactar — es la jugada correcta.
+- Los borradores deben sonar al usuario, no a copy de ventas automatizado.
+
+## Skills relacionadas
+
+- `voz-de-marca` para el perfil de voz reutilizable
+- `ranking-grafo-social` para la puntuación de puentes y la matemática de rutas cálidas de forma independiente
+- `inteligencia-leads` para el descubrimiento ponderado de objetivos y rutas cálidas
+- `api-x` para el acceso al grafo de X, la redacción y los flujos de aplicación opcionales
+- `motor-de-contenido` cuando el usuario también quiere contenido público de lanzamiento alrededor de los movimientos de red

package/vendor/theus-arsenal/skills/optimizador-paralelismo/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: optimizador-paralelismo
+description: Úsala cuando el usuario quiera terminar una tarea mucho más rápido mediante trabajo en paralelo, agentes concurrentes, llamadas a herramientas en lote, worktrees aislados o muchos carriles de verificación independientes sin perder corrección.
+tools: Read, Write, Edit, Bash, Grep, Glob
+---
+
+# Optimizador de ejecución paralela
+
+Usa esta skill cuando la velocidad venga de hacer trabajo independiente al mismo
+tiempo: inspección del repositorio, lecturas de archivos, verificaciones de API,
+comprobaciones en el navegador, carriles de build/test, lecturas de verificación
+tras un deploy o pasadas de implementación en múltiples worktrees.
+
+## Patrón central
+
+Convierte la urgencia en un grafo de dependencias antes de actuar.
+
+1. Define el objetivo y la señal de "terminado".
+2. Divide el trabajo en carriles.
+3. Marca cada carril como paralelo, secuencial o condicionado (gated).
+4. Ejecuta juntas las lecturas/verificaciones independientes.
+5. Mantén las escrituras aisladas por archivo, worktree, branch, servicio o dataset.
+6. Fusiona solo cuando la evidencia demuestre que los carriles son compatibles.
+7. Termina con una tabla de verificación, no con una afirmación vaga de velocidad.
+
+## Matriz de carriles
+
+Antes de un empujón grande, escribe una matriz compacta:
+
+```text
+Carril | ¿Puede ir en paralelo? | Superficie de escritura | Riesgo | Verificación
+Escaneo del repo | sí | ninguna | bajo | salidas de rg/git status
+Parche de backend | quizá | src/api | medio | tests unitarios
+Parche de frontend | quizá | app/components | medio | captura del navegador
+Lectura post-deploy | tras el build | servicio remoto | alto | URL en vivo + logs
+```
+
+Ejecuta carriles en paralelo solo cuando sus superficies de escritura no
+colisionen.
+
+## Reglas de ejecución
+
+- Agrupa en lote lecturas de archivos, búsquedas, verificaciones de estado y
+  consultas de metadatos.
+- Usa worktrees aislados para carriles de implementación grandes y no
+  relacionados.
+- Lanza tests, builds, backfills y deploys de larga duración en sesiones
+  separadas, y luego sondéalos deliberadamente.
+- Si un carril descubre un bloqueador que cambia el plan, pausa los carriles
+  dependientes y actualiza la matriz.
+- Nunca dejes que un proceso en segundo plano sobreviva al turno salvo que el
+  usuario haya pedido explícitamente un servicio continuo.
+- No paralelices comandos destructivos, migraciones, escrituras a la misma tabla
+  ni deploys en vivo con impacto en clientes sin una compuerta explícita.
+
+## Forma de la salida
+
+Usa esto al reportar:
+
+```text
+Resultado de ejecución paralela:
+- Carriles ejecutados: 5
+- Carriles completados: 4
+- Carril bloqueado: lectura post-deploy, esperando propagación de DNS
+- Ruta rápida encontrada: escaneo del repo en lote + tests enfocados
+- Verificación: lint OK, unitarios OK, smoke en vivo OK
+```
+
+## Modos de fallo
+
+- Más concurrencia que genera ediciones en conflicto.
+- Medir la herramienta en vez de la tarea.
+- Tratar "rápido" como terminado antes de probar la corrección.
+- Olvidar sondear las sesiones en ejecución.
+- Ocultar verificaciones omitidas detrás de un resumen de éxito.