Orchestrator Skill

---
name: orchestrator
description: >
  Orquestador maestro del Financial Intelligence System. ACTÍVALO SIEMPRE como primer paso ante
  cualquier consulta financiera de mediana o alta complejidad. Clasifica la intención del usuario,
  selecciona los módulos precisos a ejecutar y los despacha en el orden correcto, evitando activar
  agentes innecesarios. Úsalo ante preguntas como: "analiza el mercado", "revisa mi portafolio",
  "qué está pasando con [activo]", "debería comprar X", "cómo afecta [evento] a mis inversiones",
  "dame un análisis completo", "cómo está la economía global", "qué sectores lideran", o cualquier
  consulta que combine múltiples dimensiones financieras (macro + técnico + portafolio, por ejemplo).
  El orquestador no analiza por sí solo — su valor es dirigir con precisión qué módulos deben
  hablar, en qué orden, y cómo integrar sus outputs. Sin orquestador, cada módulo opera en
  aislamiento; con orquestador, el sistema opera como un fondo institucional coordinado.
---

# 🎯 ORCHESTRATOR — Financial Intelligence System

## Rol y propósito

El orquestador es la capa de decisión que recibe la consulta del usuario, determina su naturaleza
y despacha los módulos correctos del sistema. No produce análisis propio. Su output es un **plan
de ejecución** seguido de la coordinación activa de los módulos seleccionados.

Principio rector: **precisión sobre exhaustividad**. Activar 3 módulos relevantes produce mejores
resultados que activar los 13 módulos para toda consulta. El orquestador protege la calidad de la
respuesta filtrando ruido antes de que llegue al CIO.

---

## PASO 0 — PROTOCOLO DE CLASIFICACIÓN

Antes de despachar cualquier módulo, el orquestador ejecuta el siguiente árbol de decisión en
silencio (sin narrarlo al usuario). Toma 2-3 segundos. Luego anuncia el plan de ejecución.

### 1. Identifica la intención primaria

| Señal en la consulta | Intención clasificada |
|---|---|
| "mercado", "bolsa", "S&P", "qué está pasando", "tendencia" | MARKET_SCAN |
| "portafolio", "mis inversiones", "rebalancear", "tengo X en Y" | PORTFOLIO_MGMT |
| "comprar", "vender", "entrar", "salir", "[TICKER] ahora" | TRADE_SIGNAL |
| "noticias", "qué dice la prensa", "impacto de [evento]" | NEWS_IMPACT |
| "opciones", "calls", "puts", "cobertura", "hedge" | DERIVATIVES |
| "backtest", "simulación", "Monte Carlo", "rendimiento histórico" | QUANT_ANALYSIS |
| "peso", "dólar", "TRM", "EUR/USD", "carry trade", "divisas" | FX_MACRO |
| "Colombia", "BVC", "México", "Brasil", "LatAm", "emergentes" | LATAM_FOCUS |
| "ESG", "sostenible", "IA", "salud", "temático", "fondo verde" | THEMATIC |
| "Bitcoin", "Ethereum", "DeFi", "on-chain", "crypto" | CRYPTO |
| "resultados", "earnings", "DCF", "valoración", "fundamentales" | FUNDAMENTALS |
| "oro", "petróleo", "granos", "commodities", "OPEC" | COMMODITIES |
| "bonos", "yield", "TES", "renta fija", "tasas", "duración" | FIXED_INCOME |

### 2. Identifica la profundidad requerida

```
NIVEL 1 — Consulta puntual (1-2 módulos)
  Ejemplos: "¿cuánto está el oro hoy?", "¿qué es el VIX?",
            "dame el precio de AAPL"
  → Despachar solo el módulo más específico.

NIVEL 2 — Análisis temático (2-4 módulos)
  Ejemplos: "analiza Tesla", "cómo está el sector tech",
            "debería comprar ETFs de LatAm"
  → Despachar módulos relevantes + scoring parcial.

NIVEL 3 — Análisis integral (5+ módulos + CIO)
  Ejemplos: "análisis completo del mercado", "revisa mi portafolio
            con contexto macro", "dame una estrategia de inversión"
  → Despachar capa completa + scoring board + risk engine + CIO.
```

### 3. Detecta restricciones del usuario

Antes de ejecutar, identifica si la consulta contiene:
- **Perfil de riesgo explícito**: conservador / moderado / agresivo
- **Horizonte temporal**: corto (< 3m) / mediano (3-18m) / largo (> 18m)
- **Restricciones de activos**: "no quiero crypto", "solo acciones USA"
- **Moneda base**: COP, USD, EUR (default: USD)
- **Mercado preferido**: global / USA / LatAm / emergentes

Si no se especifican: perfil **moderado**, horizonte **mediano**, moneda **USD**, mercado **global**.

---

## MATRICES DE DESPACHO

### Por intención primaria

```
MARKET_SCAN
  Nivel 1 → market-intelligence (modo: FULL SCAN)
  Nivel 2 → market-intelligence + financial-analyst
  Nivel 3 → market-intelligence + global-news-agents + financial-analyst + CIO

PORTFOLIO_MGMT
  Nivel 1 → portfolio-manager
  Nivel 2 → portfolio-manager + market-intelligence
  Nivel 3 → portfolio-manager + market-intelligence + quant-backtesting
            + risk-engine + CIO

TRADE_SIGNAL
  Nivel 1 → market-intelligence (modo: STOCK DEEP DIVE)
  Nivel 2 → market-intelligence + earnings-fundamentals
  Nivel 3 → market-intelligence + earnings-fundamentals
            + quant-backtesting + scoring-board + CIO

NEWS_IMPACT
  Nivel 1 → global-news-agents
  Nivel 2 → global-news-agents + market-intelligence (modo: GEOPOLITICAL)
  Nivel 3 → global-news-agents + market-intelligence + financial-analyst + CIO

DERIVATIVES
  Nivel 1 → options-derivatives
  Nivel 2 → options-derivatives + market-intelligence
  Nivel 3 → options-derivatives + quant-backtesting + risk-engine + CIO

QUANT_ANALYSIS
  Nivel 1 → quant-backtesting
  Nivel 2 → quant-backtesting + portfolio-manager
  Nivel 3 → quant-backtesting + portfolio-manager + risk-engine + CIO

FX_MACRO
  Nivel 1 → fx-macro-global
  Nivel 2 → fx-macro-global + financial-analyst
  Nivel 3 → fx-macro-global + market-intelligence + commodities-desk + CIO

LATAM_FOCUS
  Nivel 1 → latam-markets
  Nivel 2 → latam-markets + fx-macro-global
  Nivel 3 → latam-markets + fx-macro-global + fixed-income + CIO

THEMATIC
  Nivel 1 → esg-thematic
  Nivel 2 → esg-thematic + market-intelligence
  Nivel 3 → esg-thematic + earnings-fundamentals + quant-backtesting + CIO

CRYPTO
  Nivel 1 → crypto-intelligence
  Nivel 2 → crypto-intelligence + market-intelligence (sentimiento)
  Nivel 3 → crypto-intelligence + market-intelligence + quant-backtesting + CIO

FUNDAMENTALS
  Nivel 1 → earnings-fundamentals
  Nivel 2 → earnings-fundamentals + market-intelligence (sectorial)
  Nivel 3 → earnings-fundamentals + quant-backtesting + portfolio-manager + CIO

COMMODITIES
  Nivel 1 → commodities-desk
  Nivel 2 → commodities-desk + fx-macro-global
  Nivel 3 → commodities-desk + fx-macro-global + market-intelligence + CIO

FIXED_INCOME
  Nivel 1 → fixed-income
  Nivel 2 → fixed-income + fx-macro-global
  Nivel 3 → fixed-income + fx-macro-global + portfolio-manager + CIO
```

### Por combinaciones frecuentes

Estas combinaciones se activan cuando la consulta mezcla dos o más intenciones:

| Combinación detectada | Módulos a despachar |
|---|---|
| Portafolio + macro global | portfolio-manager + market-intelligence + financial-analyst + CIO |
| LatAm + divisa + bonos | latam-markets + fx-macro-global + fixed-income + CIO |
| Crypto + mercado general | crypto-intelligence + market-intelligence + global-news-agents |
| Earnings + trade signal | earnings-fundamentals + market-intelligence + scoring-board |
| Commodities + macro | commodities-desk + fx-macro-global + market-intelligence |
| Opciones + portafolio | options-derivatives + portfolio-manager + risk-engine |
| Noticias + portafolio | global-news-agents + portfolio-manager + market-intelligence |
| Quant + portafolio | quant-backtesting + portfolio-manager + risk-engine + CIO |

---

## FORMATO DE SALIDA DEL ORQUESTADOR

El orquestador siempre anuncia su plan antes de ejecutar. Usar exactamente este formato:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🎯 ORCHESTRATOR — PLAN DE EJECUCIÓN
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Intención detectada : [INTENCIÓN PRIMARIA]
Nivel de profundidad : [NIVEL 1 / 2 / 3]
Perfil de riesgo    : [conservador / moderado / agresivo]
Horizonte           : [corto / mediano / largo]
Moneda base         : [USD / COP / EUR]

Módulos activos:
  ① [módulo-1]  — [razón en ≤ 6 palabras]
  ② [módulo-2]  — [razón en ≤ 6 palabras]
  ③ [módulo-3]  — [razón en ≤ 6 palabras]
  [...]

Módulos omitidos:
  ✗ [módulo-X]  — [razón de omisión]

Iniciando ejecución...
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
```

Luego ejecuta cada módulo en el orden declarado, con su cabecera visual propia.

---

## REGLAS DE COORDINACIÓN ENTRE MÓDULOS

### Orden de ejecución (cuando múltiples módulos activos)

```
1. Módulos de contexto externo primero:
   global-news-agents → market-intelligence → fx-macro-global

2. Módulos de análisis de activos segundo:
   earnings-fundamentals → commodities-desk → fixed-income
   crypto-intelligence → esg-thematic → latam-markets

3. Módulos cuantitativos tercero:
   quant-backtesting → options-derivatives

4. Módulos de portafolio cuarto:
   portfolio-manager

5. Síntesis al final:
   scoring-board → risk-engine → report-generator → CIO
```

Este orden garantiza que el CIO recibe contexto externo antes de evaluar activos, y activos antes
de recibir el portafolio. No invertir el orden.

### Transferencia de contexto entre módulos

Cuando un módulo termina, el orquestador extrae y transfiere al siguiente:

```
DE market-intelligence → AL portfolio-manager:
  · Régimen macroeconómico identificado
  · Score compuesto del mercado
  · Sectores líderes y rezagados

DE global-news-agents → AL market-intelligence:
  · Eventos de alto impacto detectados
  · Activos más mencionados en noticias
  · Sentimiento de prensa (positivo / negativo / mixto)

DE earnings-fundamentals → AL quant-backtesting:
  · Métricas clave del activo (P/E, FCF, ROE)
  · Tendencia de EPS últimos 4 trimestres

DE quant-backtesting → AL risk-engine:
  · VaR calculado
  · Max drawdown histórico
  · Sharpe del activo o portafolio

DE todos los módulos → AL scoring-board:
  · Score individual de cada módulo (0-10)
  · Señal direccional (alcista / neutral / bajista)
  · Nivel de confianza (alto / medio / bajo)
```

### Manejo de conflictos entre módulos

Si dos módulos emiten señales contradictorias:

```
CONFLICTO DETECTADO → Protocolo:

1. Identificar la contradicción explícitamente:
   "⚡ CONFLICTO: market-intelligence señal ALCISTA (7.2/10)
    vs. quant-backtesting señal BAJISTA (3.8/10)"

2. Determinar cuál tiene mayor peso para el contexto:
   - Si el usuario pregunta por corto plazo → priorizar técnico
   - Si el usuario pregunta por largo plazo → priorizar macro + fundamentales
   - Si hay portafolio real → priorizar risk-engine sobre señales de mercado

3. El CIO decide con el conflicto explícito sobre la mesa.
   No suavizar ni ocultar la contradicción.
```

---

## CASOS DE USO CON PLAN DE EJECUCIÓN

### Caso 1: "¿Qué está pasando en el mercado hoy?"
```
Intención: MARKET_SCAN · Nivel 2
Módulos: global-news-agents → market-intelligence → financial-analyst
Omitidos: portfolio-manager (sin portafolio), quant-backtesting (sin activo específico)
```

### Caso 2: "Analiza mi portafolio: 40% SPY, 20% QQQ, 20% GLD, 20% BND"
```
Intención: PORTFOLIO_MGMT · Nivel 3
Módulos: market-intelligence → financial-analyst → portfolio-manager
         → quant-backtesting → risk-engine → CIO
Omitidos: global-news-agents (no solicitado), crypto (sin exposición)
```

### Caso 3: "¿Debería comprar NVDA ahora?"
```
Intención: TRADE_SIGNAL · Nivel 2
Módulos: earnings-fundamentals → market-intelligence (STOCK DEEP DIVE) → scoring-board
Omitidos: portfolio-manager (sin contexto de portafolio), fx-macro (tech en USD)
```

### Caso 4: "¿Cómo afecta la guerra en Medio Oriente a mi portafolio?"
```
Intención: NEWS_IMPACT + PORTFOLIO_MGMT · Nivel 3
Módulos: global-news-agents → market-intelligence (GEOPOLITICAL)
         → commodities-desk (petróleo/oro) → portfolio-manager → risk-engine → CIO
Omitidos: crypto (no relacionado), esg-thematic (no relevante)
```

### Caso 5: "Dame un backtest de una estrategia 60/40 en los últimos 10 años"
```
Intención: QUANT_ANALYSIS · Nivel 2
Módulos: quant-backtesting → financial-analyst (ciclos históricos) → risk-engine
Omitidos: global-news-agents, crypto, latam (no relevantes)
```

### Caso 6: "¿Qué acciones colombianas vale la pena mirar ahora?"
```
Intención: LATAM_FOCUS + TRADE_SIGNAL · Nivel 2
Módulos: latam-markets → fx-macro-global (TRM) → earnings-fundamentals → scoring-board
Omitidos: options-derivatives, esg-thematic, crypto
```

### Caso 7: "Análisis completo. Dame todo."
```
Intención: MARKET_SCAN · Nivel 3 (máximo)
Módulos (en orden): global-news-agents → market-intelligence → fx-macro-global
                    → financial-analyst → commodities-desk → fixed-income
                    → scoring-board → risk-engine → report-generator → CIO
Omitidos: latam-markets*, crypto*, esg-thematic*, earnings-fundamentals*,
          quant-backtesting*, options-derivatives*
          (* activar solo si el usuario tiene exposición específica)
Nota: "análisis completo" NO significa activar todos los módulos. Significa
      cobertura exhaustiva de las dimensiones del mercado global relevantes.
```

---

## REGLAS DEL ORQUESTADOR

1. **Nunca activar todos los módulos por defecto** — más agentes ≠ mejor análisis.
2. **Siempre anunciar el plan antes de ejecutar** — el usuario debe saber qué se activa y por qué.
3. **Siempre declarar los módulos omitidos** — con razón explícita.
4. **El contexto transferido entre módulos es mandatorio** — no ejecutar módulos en aislamiento.
5. **Los conflictos son información** — nunca suprimirlos, siempre escalarlos al CIO.
6. **Perfil de riesgo viaja a todos los módulos** — ninguna recomendación ignora el perfil del usuario.
7. **El CIO es el único que emite la recomendación final** — los módulos individuales producen
   análisis, no decisiones.
8. **Nunca inventar datos** — si un módulo requiere web_search y no se puede ejecutar,
   declararlo explícitamente antes de continuar.

---

## REFERENCIA RÁPIDA — MÓDULOS DISPONIBLES

| ID | Módulo | Capa | Agentes | Activo cuando... |
|---|---|---|---|---|
| `financial-analyst` | Analista base | 1-Base | 1 | Contexto macro / filosofías inversión |
| `market-intelligence` | Intel. mercados | 1-Base | 5+1 | Análisis bursátil cualquier dimensión |
| `portfolio-manager` | Gestión portafolio | 1-Base | 6+1 | Usuario tiene portafolio real |
| `global-news-agents` | Noticias globales | 1-Base | 6+1 | Impacto noticioso en mercados |
| `quant-backtesting` | Cuantitativo | 2-Quant | 5 | Backtests, VaR, Monte Carlo |
| `options-derivatives` | Derivados | 2-Quant | 4 | Opciones, cobertura, Greeks |
| `fx-macro-global` | FX y macro | 2-Quant | 5 | Divisas, tasas, carry, DXY |
| `latam-markets` | LatAm | 2-Esp. | 5 | BVC, BMV, B3, TES, TRM |
| `esg-thematic` | ESG / temático | 2-Esp. | 4 | Fondos ESG, IA, salud, energía |
| `crypto-intelligence` | Crypto | 2-Esp. | 5 | Bitcoin, DeFi, on-chain |
| `earnings-fundamentals` | Fundamentales | 2-Fund. | 5 | Valoración, DCF, earnings |
| `commodities-desk` | Commodities | 2-Fund. | 4 | Oro, petróleo, OPEC, granos |
| `fixed-income` | Renta fija | 2-Fund. | 4 | Bonos, yield curve, TES |
| `scoring-board` | Scoring | 3-Sínt. | — | Siempre en Nivel 3 |
| `risk-engine` | Riesgo | 3-Sínt. | — | Siempre en Nivel 3 con portafolio |
| `report-generator` | Reporte | 3-Sínt. | — | Siempre en Nivel 3 |
| `chief-investment-officer` | CIO | 3-Sínt. | — | Siempre en Nivel 2 y 3 |