---
name: shopify-comprados-juntos
description: "Analiza tu historial de pedidos para encontrar los pares y tríos de productos que más se compran juntos y propone ventas cruzadas y kits. Úsala cuando quieras armar combos o configurar recomendaciones de productos. Solo lee, no cambia nada."
---

## Propósito
Analiza el historial de pedidos para descubrir qué productos se compran juntos con frecuencia. Calcula la frecuencia con que aparecen juntos (coocurrencia), el lift y la confianza para generar recomendaciones de venta cruzada y candidatos a kit basados en datos. Solo lectura: no ejecuta mutaciones.

## Requisitos
- Sesión autenticada de Shopify CLI: `shopify store auth --store <tu-tienda>.myshopify.com --scopes read_orders,read_products`
- Las consultas se ejecutan con `shopify store execute`.
- Permisos (scopes) de API: `read_orders`, `read_products`

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda |
| days_back | integer | no | 180 | Ventana de días de pedidos a analizar |
| min_support | integer | no | 3 | Mínimo de pedidos en que deben aparecer juntos para reportar un par |
| max_results | integer | no | 25 | Máximo de pares de productos a devolver |
| group_size | integer | no | 2 | Tamaño del grupo: `2` para pares, `3` para tríos |
| collection_filter | string | no | — | Limita el análisis a los productos de una colección específica |
| format | string | no | human | Formato de salida: `human` o `json` |

## Seguridad

> ℹ️ Skill de solo lectura: no ejecuta mutaciones. Puedes ejecutarla en cualquier momento sin riesgo.

## Pasos

1. **OPERACIÓN:** `orders` — consulta
   **Entradas:** `query: "created_at:>='<NOW - days_back days>'"`, `first: 250`, selecciona `lineItems { product { id, title } }` y el cursor de paginación
   **Resultado esperado:** Todos los pedidos con sus artículos a nivel de producto

2. Para cada pedido con 2 o más productos distintos, genera todas las combinaciones posibles de pares de productos

3. Arma la matriz de coocurrencia:
   - **Soporte** = número de pedidos que contienen ambos productos
   - **Confianza(A→B)** = P(B|A) = soporte(A,B) / soporte(A)
   - **Lift** = confianza(A→B) / P(B); un lift > 1.0 significa una asociación positiva

4. **OPERACIÓN:** `products` — consulta (enriquecimiento)
   **Entradas:** Los ID de producto de los mejores pares, para traer títulos, imágenes y precios
   **Resultado esperado:** Los detalles de producto para mostrar

5. Ordena los pares por lift (de mayor a menor) y filtra por min_support

## Operaciones GraphQL

```graphql
# orders:query — validado con api_version 2025-01
query OrderLineItems($query: String!, $after: String) {
  orders(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        lineItems(first: 50) {
          edges {
            node {
              product { id title }
              quantity
            }
          }
        }
      }
    }
    pageInfo { hasNextPage endCursor }
  }
}
```

```graphql
# products:query — validado con api_version 2025-01
query ProductDetails($ids: [ID!]!) {
  nodes(ids: $ids) {
    ... on Product {
      id
      title
      vendor
      productType
      priceRangeV2 {
        minVariantPrice { amount currencyCode }
        maxVariantPrice { amount currencyCode }
      }
      totalInventory
      status
    }
  }
}
```

## Seguimiento de la sesión

**Claude DEBE mostrar lo siguiente en cada etapa. Es obligatorio.**

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════╗
║  SKILL: Productos que se compran juntos      ║
║  Tienda: <dominio de la tienda>              ║
║  Inicio: <AAAA-MM-DD HH:MM UTC>              ║
╚══════════════════════════════════════════════╝
```

**Después de cada paso**, muestra:
```
[N/TOTAL] <CONSULTA|MUTACIÓN>  <OperationName>
          → Parámetros: <resumen breve de las entradas clave>
          → Resultado: <cantidad o desenlace>
```

**Al terminar**, muestra:

Para `format: human` (predeterminado):
```
══════════════════════════════════════════════
PRODUCTOS QUE SE COMPRAN JUNTOS  (<days_back> días, <n> pedidos analizados)
  Pares de productos únicos encontrados: <n>
  Pares que cumplen min_support:         <n>

  MEJORES PARES POR LIFT:
  #1  "<producto A>" + "<producto B>"
      Soporte: <n> pedidos  Lift: <n>x  Confianza: <pct>%

  #2  "<producto A>" + "<producto B>"
      Soporte: <n> pedidos  Lift: <n>x  Confianza: <pct>%

  CANDIDATOS A KIT (soporte alto + lift alto):
    "<producto A>" + "<producto B>"  →  Precio sugerido del kit: <n> <moneda>

  Archivo: fbt_pairs_<fecha>.csv
══════════════════════════════════════════════
```

## Formato de salida
Archivo CSV `fbt_pairs_<AAAA-MM-DD>.csv` con las columnas:
`product_a_id`, `product_a_title`, `product_b_id`, `product_b_title`, `support`, `confidence_a_to_b`, `confidence_b_to_a`, `lift`, `combined_avg_price`

## Manejo de errores
| Error | Causa | Solución |
|-------|-------|----------|
| `THROTTLED` | Se superó el límite de solicitudes de la API | Espera 2 segundos y reintenta hasta 3 veces |
| Solo pedidos de un artículo | La tienda no tiene pedidos con varios artículos | Reporta el resultado vacío y sugiere una ventana de días más larga |
| Demasiados productos | Explosión combinatoria | Limita el análisis a los 500 productos con más pedidos |

## Buenas prácticas
- Usa `days_back: 180` o `365` para tener una muestra suficiente.
- Los pares con lift > 2.0 son fuertes candidatos a kit.
- Usa los resultados para crear kits de productos a mano o para configurar apps de upsell.
- Crúzalos con `shopify-productos-mas-vendidos` para asegurarte de que los productos del par tengan buen desempeño.
- Los productos con confianza alta de A→B pero baja de B→A sugieren upsells en una sola dirección (muestra B cuando A está en el carrito).