---
name: shopify-auditoria-colecciones
description: "Encuentra los productos que no están en ninguna colección (invisibles en la navegación de tu tienda) y los que están en demasiadas. Úsala cuando quieras ordenar tu catálogo, por ejemplo después de cargar los productos de una temporada. Solo lee, no cambia nada."
---

## Propósito
Identifica los productos que no están en ninguna colección («huérfanos», invisibles en la navegación de la tienda) y los productos que aparecen en un número inusualmente alto de colecciones («en demasiadas colecciones», un posible ruido de merchandising). Solo lectura: no ejecuta mutaciones.

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

## Parámetros

| Parámetro | Tipo | Obligatorio | Predeterminado | Descripción |
|-----------|------|-------------|----------------|-------------|
| store | string | sí | — | Dominio de la tienda (p. ej., tu-tienda.myshopify.com) |
| max_collections | integer | no | 10 | Marca los productos que estén en más colecciones que este número |
| status_filter | string | no | active | Estado de los productos a revisar: `active`, `draft` o `all` |
| 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:** `products` — consulta
   **Entradas:** `query: "status:<status_filter>"`, `first: 250`, selecciona `collections { edges { node { id } } }` y el cursor de paginación
   **Resultado esperado:** Los productos con las colecciones a las que pertenecen; pagina hasta que `hasNextPage: false`

2. Para cada producto: cuenta sus colecciones → márcalo si tiene 0 (huérfano) o más de `max_collections` (en demasiadas colecciones)

3. **OPERACIÓN:** `collections` — consulta (para los nombres de las colecciones)
   **Entradas:** `first: 250`, selecciona `id`, `title`, `productsCount`
   **Resultado esperado:** Los datos de las colecciones para enriquecer el reporte

## Operaciones GraphQL

```graphql
# products:query — validado con api_version 2025-01
query ProductCollectionMembership($query: String!, $after: String) {
  products(first: 250, after: $after, query: $query) {
    edges {
      node {
        id
        title
        handle
        status
        collections(first: 30) {
          edges {
            node {
              id
              title
            }
          }
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

```graphql
# collections:query — validado con api_version 2025-01
query CollectionOverview($after: String) {
  collections(first: 250, after: $after) {
    edges {
      node {
        id
        title
        handle
        productsCount {
          count
        }
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}
```

## Seguimiento de la sesión

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

**Al iniciar**, muestra:
```
╔══════════════════════════════════════════════════════════╗
║  SKILL: Productos huérfanos o en demasiadas colecciones  ║
║  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):
```
══════════════════════════════════════════════
AUDITORÍA DE PERTENENCIA A COLECCIONES
  Productos revisados:                       <n>
  Productos huérfanos (0 colecciones):       <n>
  En demasiadas colecciones (> <max_collections>): <n>

  Productos huérfanos (muestra):
    "<título>" — <estado>
  Archivo: collection_audit_<fecha>.csv
══════════════════════════════════════════════
```

Para `format: json`, muestra:
```json
{
  "skill": "shopify-auditoria-colecciones",
  "store": "<dominio>",
  "products_scanned": 0,
  "orphan_count": 0,
  "over_collected_count": 0,
  "output_file": "collection_audit_<fecha>.csv"
}
```

## Formato de salida
Archivo CSV `collection_audit_<AAAA-MM-DD>.csv` con las columnas:
`product_id`, `title`, `handle`, `status`, `collection_count`, `collections`, `issue`

## 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 |
| No hay huérfanos | Todos los productos están en alguna colección | Termina con ✅ no se encontraron huérfanos |

## Buenas prácticas
- Los productos activos huérfanos son invisibles en la navegación de la tienda: los clientes solo los encuentran con el enlace directo o con el buscador. Dale prioridad a corregirlos.
- Las colecciones automáticas (por reglas) pueden incluir productos según sus etiquetas o condiciones: un producto huérfano en las colecciones manuales igual puede aparecer en las automáticas. Revisa ambas.
- Usa `max_collections: 5` en tiendas con una navegación muy curada; usa umbrales más altos en tiendas tipo marketplace, donde publicar un producto en varias colecciones es intencional.
- Ejecútala después de renovar el catálogo por temporada para asegurarte de que todos los productos nuevos queden en las colecciones correctas.