theus-cli 0.2.83 → 0.2.85

package/vendor/theus-arsenal/skills/recuperacion-iterativa/SKILL.md

@@ -1,236 +0,0 @@
----
-name: recuperacion-iterativa
-description: Patrón para refinar progresivamente la recuperación de contexto y resolver el problema de contexto de los subagentes
----
-
-# Patrón de recuperación iterativa
-
-Resuelve el "problema de contexto" en flujos multiagente, donde los subagentes no saben qué contexto necesitan hasta que empiezan a trabajar.
-
-## Cuándo activarla
-
-- Al lanzar subagentes que necesitan contexto del código base que no pueden predecir de antemano
-- Al construir flujos multiagente donde el contexto se refina progresivamente
-- Al encontrar fallos de "contexto demasiado grande" o "falta contexto" en tareas de agentes
-- Al diseñar pipelines de recuperación tipo RAG para explorar código
-- Al optimizar el uso de tokens en la orquestación de agentes
-
-## El problema
-
-Los subagentes se lanzan con contexto limitado. No saben:
-- Qué archivos contienen el código relevante
-- Qué patrones existen en el código base
-- Qué terminología usa el proyecto
-
-Los enfoques estándar fallan:
-- **Enviarlo todo**: excede los límites de contexto
-- **No enviar nada**: el agente carece de información crítica
-- **Adivinar lo necesario**: suele salir mal
-
-## La solución: recuperación iterativa
-
-Un bucle de 4 fases que refina el contexto progresivamente:
-
-```
-┌─────────────────────────────────────────────┐
-│                                             │
-│   ┌──────────┐      ┌──────────┐            │
-│   │ DESPACHO │─────│ EVALUAR  │            │
-│   └──────────┘      └──────────┘            │
-│        ▲                  │                 │
-│        │                  ▼                 │
-│   ┌──────────┐      ┌──────────┐            │
-│   │  BUCLE   │─────│ REFINAR  │            │
-│   └──────────┘      └──────────┘            │
-│                                             │
-│     Máximo 3 ciclos, luego continuar        │
-└─────────────────────────────────────────────┘
-```
-
-## Primera vía: Ñaupa (grafo de conocimiento)
-
-Antes de recurrir a búsquedas de texto (grep), usa el MCP `theus-naupa`. Ñaupa ya indexó el código base como un grafo de símbolos, por lo que una sola consulta semántica suele reemplazar varios ciclos de búsqueda a ciegas:
-
-- **`search_graph`**: búsqueda semántica/estructural de símbolos, funciones y conceptos. Es el mejor punto de partida del DESPACHO: en lugar de adivinar palabras clave, pregunta por la intención ("autenticación de sesiones", "expiración de tokens").
-- **`trace_path`**: traza las rutas de llamadas y dependencias entre dos símbolos. Úsalo en la fase de EVALUAR/REFINAR para descubrir los archivos intermedios que conectan lo que ya encontraste con lo que falta.
-- **`get_code_snippet`**: recupera el cuerpo exacto de un símbolo sin leer el archivo completo. Úsalo para confirmar relevancia gastando el mínimo de tokens.
-
-Orden recomendado de recuperación:
-
-1. `search_graph` con la intención de la tarea → candidatos de alta precisión
-2. `trace_path` entre los candidatos confirmados → contexto de conexión (llamadores, dependencias)
-3. `get_code_snippet` sobre los símbolos prometedores → verificación barata de relevancia
-4. **Solo después**, grep/glob para lo que el grafo no cubre (configs, docs, cadenas literales, archivos no indexados)
-
-Los ciclos de las fases siguientes aplican igual: si Ñaupa devuelve poco o el proyecto no está indexado, degrada a grep con las mismas reglas de refinamiento.
-
-### Fase 1: DESPACHO
-
-Consulta inicial amplia para reunir archivos candidatos:
-
-```javascript
-// Empieza con la intención de alto nivel
-const initialQuery = {
-  patterns: ['src/**/*.ts', 'lib/**/*.ts'],
-  keywords: ['authentication', 'user', 'session'],
-  excludes: ['*.test.ts', '*.spec.ts']
-};
-
-// Despacha al agente de recuperación
-// (primera vía: search_graph de Ñaupa con las keywords como intención;
-//  segunda vía: grep sobre los patterns)
-const candidates = await retrieveFiles(initialQuery);
-```
-
-### Fase 2: EVALUAR
-
-Valora la relevancia del contenido recuperado:
-
-```javascript
-function evaluateRelevance(files, task) {
-  return files.map(file => ({
-    path: file.path,
-    relevance: scoreRelevance(file.content, task),
-    reason: explainRelevance(file.content, task),
-    missingContext: identifyGaps(file.content, task)
-  }));
-}
-```
-
-Criterios de puntuación:
-- **Alta (0.8-1.0)**: implementa directamente la funcionalidad objetivo
-- **Media (0.5-0.7)**: contiene patrones o tipos relacionados
-- **Baja (0.2-0.4)**: relación tangencial
-- **Nula (0-0.2)**: no es relevante, excluir
-
-### Fase 3: REFINAR
-
-Actualiza los criterios de búsqueda según la evaluación:
-
-```javascript
-function refineQuery(evaluation, previousQuery) {
-  return {
-    // Añade patrones nuevos descubiertos en archivos de alta relevancia
-    patterns: [...previousQuery.patterns, ...extractPatterns(evaluation)],
-
-    // Añade la terminología encontrada en el código base
-    keywords: [...previousQuery.keywords, ...extractKeywords(evaluation)],
-
-    // Excluye rutas confirmadas como irrelevantes
-    excludes: [...previousQuery.excludes, ...evaluation
-      .filter(e => e.relevance < 0.2)
-      .map(e => e.path)
-    ],
-
-    // Apunta a las lagunas concretas
-    focusAreas: evaluation
-      .flatMap(e => e.missingContext)
-      .filter(unique)
-  };
-}
-```
-
-En esta fase, `trace_path` de Ñaupa es especialmente útil: si ya tienes dos símbolos de alta relevancia pero falta el "pegamento" entre ellos, trazar la ruta entre ambos revela los archivos intermedios sin otro ciclo de búsqueda.
-
-### Fase 4: BUCLE
-
-Repite con los criterios refinados (máximo 3 ciclos):
-
-```javascript
-async function iterativeRetrieve(task, maxCycles = 3) {
-  let query = createInitialQuery(task);
-  let bestContext = [];
-
-  for (let cycle = 0; cycle < maxCycles; cycle++) {
-    const candidates = await retrieveFiles(query);
-    const evaluation = evaluateRelevance(candidates, task);
-
-    // Comprueba si el contexto ya es suficiente
-    const highRelevance = evaluation.filter(e => e.relevance >= 0.7);
-    if (highRelevance.length >= 3 && !hasCriticalGaps(evaluation)) {
-      return highRelevance;
-    }
-
-    // Refina y continúa
-    query = refineQuery(evaluation, query);
-    bestContext = mergeContext(bestContext, highRelevance);
-  }
-
-  return bestContext;
-}
-```
-
-## Ejemplos prácticos
-
-### Ejemplo 1: contexto para corregir un bug
-
-```
-Tarea: "Corregir el bug de expiración del token de autenticación"
-
-Ciclo 1:
-  DESPACHO: search_graph("expiración de token de autenticación");
-            respaldo grep de "token", "auth", "expiry" en src/**
-  EVALUAR: encontrados auth.ts (0.9), tokens.ts (0.8), user.ts (0.3)
-  REFINAR: añadir keywords "refresh", "jwt"; excluir user.ts;
-           trace_path entre auth.ts y tokens.ts para hallar el conector
-
-Ciclo 2:
-  DESPACHO: buscar los términos refinados
-  EVALUAR: encontrados session-manager.ts (0.95), jwt-utils.ts (0.85)
-  REFINAR: contexto suficiente (2 archivos de alta relevancia)
-
-Resultado: auth.ts, tokens.ts, session-manager.ts, jwt-utils.ts
-```
-
-### Ejemplo 2: implementar una funcionalidad
-
-```
-Tarea: "Añadir rate limiting a los endpoints de la API"
-
-Ciclo 1:
-  DESPACHO: search_graph("rate limiting de API");
-            respaldo grep de "rate", "limit", "api" en routes/**
-  EVALUAR: sin coincidencias — el código base usa la terminología "throttle"
-  REFINAR: añadir keywords "throttle", "middleware"
-
-Ciclo 2:
-  DESPACHO: buscar los términos refinados
-  EVALUAR: encontrados throttle.ts (0.9), middleware/index.ts (0.7)
-  REFINAR: faltan los patrones del router
-
-Ciclo 3:
-  DESPACHO: buscar patrones "router", "express";
-            get_code_snippet sobre los símbolos del middleware
-  EVALUAR: encontrado router-setup.ts (0.8)
-  REFINAR: contexto suficiente
-
-Resultado: throttle.ts, middleware/index.ts, router-setup.ts
-```
-
-## Integración con agentes
-
-Úsalo en los prompts de los agentes:
-
-```markdown
-Al recuperar contexto para esta tarea:
-1. Empieza con search_graph de Ñaupa usando la intención de la tarea;
-   si el proyecto no está indexado, usa una búsqueda amplia por palabras clave
-2. Evalúa la relevancia de cada archivo (escala 0-1)
-3. Identifica qué contexto sigue faltando (trace_path ayuda a hallar conectores)
-4. Refina los criterios de búsqueda y repite (máximo 3 ciclos)
-5. Devuelve los archivos con relevancia >= 0.7
-```
-
-## Buenas prácticas
-
-1. **Empieza amplio y estrecha progresivamente** — no sobreespecifiques las consultas iniciales
-2. **Aprende la terminología del código base** — el primer ciclo suele revelar las convenciones de nombres
-3. **Registra lo que falta** — identificar las lagunas explícitamente es lo que guía el refinamiento
-4. **Detente en "suficientemente bueno"** — 3 archivos de alta relevancia valen más que 10 mediocres
-5. **Excluye con confianza** — los archivos de baja relevancia no se volverán relevantes
-6. **Grafo antes que texto** — una consulta a Ñaupa bien formulada ahorra ciclos enteros de grep
-
-## Relacionado
-
-- Skill `presupuesto-contexto` — para gestionar el presupuesto de tokens en la orquestación
-- Los agentes del arsenal de Theus (`agents/`) pueden incorporar este patrón en sus prompts

package/vendor/theus-arsenal/skills/redaccion-articulos/SKILL.md

@@ -1,81 +0,0 @@
----
-name: redaccion-articulos
-description: Escribe artículos, guías, posts de blog, tutoriales, ediciones de newsletter y otro
-  contenido largo con una voz distintiva derivada de ejemplos provistos o de la guía de marca. Úsala
-  cuando el usuario quiera contenido pulido de más de un párrafo, sobre todo si importan la
-  consistencia de voz, la estructura y la credibilidad.
----
-
-# Redacción de artículos
-
-Escribe contenido largo que suene a una persona real con punto de vista, no a un modelo alisándose a sí mismo hasta convertirse en pasta.
-
-## Cuándo activarla
-
-- Redactar posts de blog, ensayos, posts de lanzamiento, guías, tutoriales o ediciones de newsletter
-- Convertir notas, transcripciones o investigación en artículos pulidos
-- Imitar la voz existente de un fundador, operador o marca a partir de ejemplos
-- Ajustar estructura, ritmo y evidencia en textos largos ya escritos
-
-## Reglas centrales
-
-1. Abre con lo concreto: artefacto, ejemplo, resultado, anécdota, cifra, captura o código.
-2. Explica después del ejemplo, no antes.
-3. Mantén las frases apretadas salvo que la voz de origen sea intencionalmente expansiva.
-4. Usa pruebas en lugar de adjetivos.
-5. Nunca inventes hechos, credibilidad ni evidencia de clientes.
-
-## Manejo de la voz
-
-Si el usuario quiere una voz específica, ejecuta primero `voz-de-marca` y reutiliza su `PERFIL DE VOZ`.
-No dupliques aquí un segundo pase de análisis de estilo salvo que el usuario lo pida explícitamente.
-
-Si no hay referencias de voz, usa por defecto una voz de operador afilada: concreta, sin sentimentalismo, útil.
-
-## Patrones prohibidos
-
-Elimina y reescribe cualquiera de estos:
-- "En el panorama actual en rápida evolución"
-- "revolucionario", "de vanguardia", "que cambia las reglas del juego"
-- "por eso esto importa" como puente suelto
-- arcos de vulnerabilidad falsos
-- una pregunta de cierre añadida solo para inflar el engagement
-- relleno biográfico que no avanza el argumento
-- carraspeo genérico de IA que retrasa el punto
-
-## Proceso de escritura
-
-1. Aclara la audiencia y el propósito.
-2. Construye un esquema duro con un trabajo por sección.
-3. Empieza las secciones con prueba, artefacto, conflicto o ejemplo.
-4. Expande solo donde la siguiente frase se gane el espacio.
-5. Corta todo lo que suene a plantilla, sobreexplicado o autocomplaciente.
-
-## Guía de estructura
-
-### Guías técnicas
-
-- abre con lo que el lector obtiene
-- usa código, comandos, capturas o resultados concretos en las secciones principales
-- cierra con acciones concretas, no con un resumen blando
-
-### Ensayos / opinión
-
-- empieza con tensión, contradicción o una observación específica
-- mantén un hilo argumental por sección
-- haz que las opiniones respondan a la evidencia
-
-### Newsletters
-
-- haz que la primera pantalla trabaje de verdad
-- no antepongas relleno de diario personal
-- usa etiquetas de sección solo cuando mejoren el escaneo
-
-## Puerta de calidad
-
-Antes de entregar:
-- las afirmaciones factuales están respaldadas por las fuentes provistas
-- las transiciones genéricas de IA desaparecieron
-- la voz coincide con los ejemplos provistos o con el `PERFIL DE VOZ` acordado
-- cada sección aporta algo nuevo
-- el formato coincide con el medio de destino

package/vendor/theus-arsenal/skills/regex-vs-llm/SKILL.md

@@ -1,221 +0,0 @@
----
-name: regex-vs-llm
-description: >
-  Marco de decisión para elegir entre regex y LLM al parsear texto estructurado —
-  empieza con regex y añade el LLM solo para los casos límite de baja confianza.
----
-
-# Regex vs LLM para parsear texto estructurado
-
-Un marco de decisión práctico para parsear texto estructurado (cuestionarios, formularios, facturas, documentos). La idea clave: el regex resuelve el 95-98 % de los casos de forma barata y determinista. Reserva las llamadas costosas al LLM para los casos límite restantes.
-
-## Cuándo activarla
-
-- Al parsear texto estructurado con patrones repetitivos (preguntas, formularios, tablas)
-- Al decidir entre regex y LLM para extraer texto
-- Al construir pipelines híbridos que combinan ambos enfoques
-- Al optimizar el balance costo/precisión en el procesamiento de texto
-
-## Marco de decisión
-
-```
-¿El formato del texto es consistente y repetitivo?
-├── Sí (>90 % sigue un patrón) → Empieza con regex
-│   ├── El regex resuelve ≥95 % → Listo, no hace falta LLM
-│   └── El regex resuelve <95 % → Añade LLM solo para los casos límite
-└── No (texto libre, muy variable) → Usa el LLM directamente
-```
-
-## Patrón de arquitectura
-
-```
-Texto fuente
-    │
-    ▼
-[Parser regex] ─── Extrae la estructura (95-98 % de precisión)
-    │
-    ▼
-[Limpiador de texto] ─── Elimina ruido (marcadores, números de página, artefactos)
-    │
-    ▼
-[Puntuador de confianza] ─── Marca las extracciones de baja confianza
-    │
-    ├── Confianza alta (≥0.95) → Salida directa
-    │
-    └── Confianza baja (<0.95) → [Validador LLM] → Salida
-```
-
-## Implementación
-
-### 1. Parser regex (resuelve la mayoría)
-
-```python
-import re
-from dataclasses import dataclass
-
-@dataclass(frozen=True)
-class ParsedItem:
-    id: str
-    text: str
-    choices: tuple[str, ...]
-    answer: str
-    confidence: float = 1.0
-
-def parse_structured_text(content: str) -> list[ParsedItem]:
-    """Parsea texto estructurado con patrones regex."""
-    pattern = re.compile(
-        r"(?P<id>\d+)\.\s*(?P<text>.+?)\n"
-        r"(?P<choices>(?:[A-D]\..+?\n)+)"
-        r"Answer:\s*(?P<answer>[A-D])",
-        re.MULTILINE | re.DOTALL,
-    )
-    items = []
-    for match in pattern.finditer(content):
-        choices = tuple(
-            c.strip() for c in re.findall(r"[A-D]\.\s*(.+)", match.group("choices"))
-        )
-        items.append(ParsedItem(
-            id=match.group("id"),
-            text=match.group("text").strip(),
-            choices=choices,
-            answer=match.group("answer"),
-        ))
-    return items
-```
-
-### 2. Puntuación de confianza
-
-Marca los ítems que podrían necesitar revisión por LLM:
-
-```python
-@dataclass(frozen=True)
-class ConfidenceFlag:
-    item_id: str
-    score: float
-    reasons: tuple[str, ...]
-
-def score_confidence(item: ParsedItem) -> ConfidenceFlag:
-    """Puntúa la confianza de la extracción y marca problemas."""
-    reasons = []
-    score = 1.0
-
-    if len(item.choices) < 3:
-        reasons.append("few_choices")
-        score -= 0.3
-
-    if not item.answer:
-        reasons.append("missing_answer")
-        score -= 0.5
-
-    if len(item.text) < 10:
-        reasons.append("short_text")
-        score -= 0.2
-
-    return ConfidenceFlag(
-        item_id=item.id,
-        score=max(0.0, score),
-        reasons=tuple(reasons),
-    )
-
-def identify_low_confidence(
-    items: list[ParsedItem],
-    threshold: float = 0.95,
-) -> list[ConfidenceFlag]:
-    """Devuelve los ítems por debajo del umbral de confianza."""
-    flags = [score_confidence(item) for item in items]
-    return [f for f in flags if f.score < threshold]
-```
-
-### 3. Validador LLM (solo casos límite)
-
-```python
-def validate_with_llm(
-    item: ParsedItem,
-    original_text: str,
-    client,
-) -> ParsedItem:
-    """Usa el LLM para corregir extracciones de baja confianza."""
-    response = client.messages.create(
-        model=MODELO_ECONOMICO,  # Modelo económico del catálogo Theus: suficiente para validar
-        max_tokens=500,
-        messages=[{
-            "role": "user",
-            "content": (
-                f"Extrae la pregunta, las opciones y la respuesta de este texto.\n\n"
-                f"Texto: {original_text}\n\n"
-                f"Extracción actual: {item}\n\n"
-                f"Devuelve el JSON corregido si hace falta, o 'CORRECT' si es exacta."
-            ),
-        }],
-    )
-    # Parsear la respuesta del LLM y devolver el ítem corregido...
-    return corrected_item
-```
-
-### 4. Pipeline híbrido
-
-```python
-def process_document(
-    content: str,
-    *,
-    llm_client=None,
-    confidence_threshold: float = 0.95,
-) -> list[ParsedItem]:
-    """Pipeline completo: regex -> chequeo de confianza -> LLM para casos límite."""
-    # Paso 1: extracción con regex (resuelve el 95-98 %)
-    items = parse_structured_text(content)
-
-    # Paso 2: puntuación de confianza
-    low_confidence = identify_low_confidence(items, confidence_threshold)
-
-    if not low_confidence or llm_client is None:
-        return items
-
-    # Paso 3: validación con LLM (solo para los ítems marcados)
-    low_conf_ids = {f.item_id for f in low_confidence}
-    result = []
-    for item in items:
-        if item.id in low_conf_ids:
-            result.append(validate_with_llm(item, content, llm_client))
-        else:
-            result.append(item)
-
-    return result
-```
-
-## Métricas del mundo real
-
-De un pipeline de parseo de cuestionarios en producción (410 ítems):
-
-| Métrica | Valor |
-|---------|-------|
-| Tasa de éxito del regex | 98.0 % |
-| Ítems de baja confianza | 8 (2.0 %) |
-| Llamadas al LLM necesarias | ~5 |
-| Ahorro de costo vs todo-LLM | ~95 % |
-| Cobertura de tests | 93 % |
-
-## Buenas prácticas
-
-- **Empieza con regex** — incluso un regex imperfecto te da una línea base que mejorar
-- **Usa puntuación de confianza** para identificar programáticamente qué necesita ayuda del LLM
-- **Usa el LLM más barato** para validar (un modelo económico del catálogo Theus es suficiente)
-- **Nunca mutes** los ítems parseados — devuelve instancias nuevas en los pasos de limpieza/validación
-- **El TDD funciona muy bien** para parsers — escribe primero tests para los patrones conocidos y luego para los casos límite
-- **Registra métricas** (tasa de éxito del regex, cantidad de llamadas al LLM) para monitorear la salud del pipeline
-
-## Antipatrones a evitar
-
-- Enviar todo el texto a un LLM cuando el regex resuelve ≥95 % de los casos (caro y lento)
-- Usar regex para texto libre y muy variable (ahí el LLM es mejor)
-- Saltarse la puntuación de confianza y esperar que el regex "simplemente funcione"
-- Mutar los objetos parseados durante los pasos de limpieza/validación
-- No probar los casos límite (entrada malformada, campos faltantes, problemas de codificación)
-
-## Cuándo usarla
-
-- Parseo de preguntas de cuestionarios/exámenes
-- Extracción de datos de formularios
-- Procesamiento de facturas/recibos
-- Parseo de estructura de documentos (encabezados, secciones, tablas)
-- Cualquier texto estructurado con patrones repetitivos donde el costo importa