theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,236 @@
+---
+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

@@ -0,0 +1,81 @@
+---
+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

@@ -0,0 +1,221 @@
+---
+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