Cism-Ch/product-intelligence

SKILL: Product Intelligence — Búsqueda y Generación de Fichas de Producto JSON

Este skill define el procedimiento operativo para buscar, estructurar y validar datos de productos Tech y Appliance en archivos JSON estandarizados. Sirve como motor de ejecución exclusivo para el flujo de trabajo /generate-product-data.

[!CAUTION] DIRECTIVA IMPERATIVA: Este skill está sujeto a VERIFICATION_IMPERATIVE.md. NINGÚN dato técnico debe provenir de la memoria interna de la IA. Los datos de entrenamiento están sistemáticamente obsoletos, incompletos o erróneos para especificaciones de producto, SKU y precios. Cada campo técnico DEBE completarse a partir de resultados de búsqueda web en tiempo real.

⚠️ REGLA DE ORO: Este flujo de trabajo es una fuente de verdad para los datos de producto. No genera HTML ni CSV. Produce archivos JSON de referencia que pueden usarse para verificar otros flujos de trabajo o como base de datos de productos.

---

Directrices Fundamentales

0. Identidad y Vinculación del Flujo de Trabajo

• Este skill está estrictamente dedicado al flujo de trabajo /generate-product-data.
• NO confundir con los flujos de trabajo production-industrielle-v3 o produce-appliance que generan HTML/CSV.
• NO mezclar los esquemas JSON de este flujo de trabajo con los Template_Pack_v3_*.json existentes.
• Los archivos generados se almacenan en product-data/ (separado de products/ y products-appliance/).

1. Precisión Absoluta de los Números de Modelo (CRÍTICO)

• El número de modelo (SKU del fabricante) es el campo más importante del archivo JSON.
• PROHIBIDO: Inventar, adivinar o extrapolar un SKU a partir de un modelo vecino.
• OBLIGATORIO: Verificar el SKU en el sitio web oficial del fabricante o en 2+ fuentes fiables.
• EJEMPLOS de confusiones frecuentes (SKU Internacionales verificados en Mayo 2026):
  • Samsung Galaxy S24 (SM-S921B) ≠ S24+ (SM-S926B) ≠ S24 Ultra (SM-S928B)
  • iPhone 16 (A3287) ≠ iPhone 16 Plus (A3291) ≠ iPhone 16 Pro (A3294) ≠ iPhone 16 Pro Max (A3296)
  • iPhone 17 (A3520) ≠ iPhone 17 Pro (A3523) ≠ iPhone 17 Pro Max (A3526)
  • Xiaomi Redmi Note 14 (24108RN14G) ≠ Redmi Note 14 Pro (24108RN14PG)
  • ⚠️ ATENCIÓN: Estos ejemplos pueden quedar obsoletos. SIEMPRE volver a verificar mediante búsqueda web.
• Siempre rellenar el campo disambiguation_notes cuando exista riesgo de confusión.

2. Búsqueda Verificada y Fuentes — BÚSQUEDA WEB OBLIGATORIA

[!WARNING] NUNCA usar la memoria de la IA como fuente de datos técnicos. Los modelos de IA tienen datos de entrenamiento con un desfase de meses a años. Los productos pueden haber sido renombrados, los SKU reasignados, las especificaciones modificadas desde la fecha de corte.

• Jerarquía de fuentes (por orden de prioridad):

  1. 🥇 Sitio oficial del fabricante (samsung.com, apple.com, xiaomi.com...) — OBLIGATORIO como primera opción
  2. 🥈 Bases de datos técnicas (GSMArena, DeviceSpecifications, NotebookCheck, Kimovil)
  3. 🥉 Sitios de venta locales (Jumia CI, mercados de África Occidental)
  4. 4️⃣ Revendedores internacionales (Amazon, AliExpress, B&H Photo)
  5. 5️⃣ Catálogos PDF del fabricante / subdistribuidores

• Mínimo 2 fuentes web distintas para confirmar un dato técnico crítico.

• La memoria de la IA NO cuenta como fuente — solo las búsquedas web en tiempo real son válidas.

• PROHIBIDO: Sitios de filtraciones, rumores, datos no verificados, foros no moderados, datos provenientes de la memoria de la IA.

• SI un dato no se encuentra: Dejar el campo vacío en lugar de inventar un valor.

3. Precios Locales (Mercado de Costa de Marfil)

• Fuente principal: Jumia CI (jumia.ci), luego otros marketplaces de África Occidental.
• Formato: Rango de precios en FCFA (market_price_range_fcfa.min / max).
• Varias variantes → Varios precios (uno por configuración RAM/Almacenamiento).
• Precio no encontrado: Rellenar "price_source": "No disponible localmente" en lugar de un null silencioso.
• Fecha del precio: Siempre rellenar price_date en formato YYYY-MM.

4. Gestión de Variantes (Resiliencia)

• Cuando el usuario menciona una serie (ej: "Samsung Galaxy S25"), el flujo de trabajo DEBE:
  1. Enumerar TODAS las variantes conocidas de la serie
  2. Confirmar la lista con el usuario (o procesar todas en lote)
  3. Generar UN archivo JSON POR variante
• Cada variante tiene sus propios: SKU, configuraciones, precios, colores.
• PROHIBIDO: Copiar y pegar las especificaciones de un modelo a otro de la misma serie.

5. Cero Placeholders, Cero Alucinaciones

• Ningún valor "", "N/A", "TBD", "TODO", "???" es aceptado en los campos obligatorios.
• Si una información no se encuentra y es opcional: eliminar el campo del JSON.
• Si una información no se encuentra y es obligatoria: documentar la ausencia en generation_metadata.notes.

---

Procedimiento Operativo (Pipeline)

Etapa 1: Identificación de Productos

Objetivo: Transformar la solicitud del usuario en una lista precisa de productos a procesar.

1. Analizar la solicitud:

   • "Samsung Galaxy S25" → Identificar la serie S25
   • "iPhone 16 Pro" → Identificar un modelo específico
   • "Hisense refrigeradores" → Identificar una categoría de marca

2. Enumerar las variantes:

   • Buscar en el sitio del fabricante todas las variantes de la serie
   • Listar los números de modelo oficiales para cada variante
   • Documentar las diferencias clave entre variantes

3. Confirmar el alcance (modo lote):

   • Presentar la lista completa al usuario
   • Ejemplo: "He identificado 4 variantes: S25 (SM-S931B), S25+ (SM-S936B), S25 Ultra (SM-S938B), S25 FE (SM-S72xB). ¿Procedo con las 4?"

4. Salida esperada: Lista estructurada [{name, sku, category, sub_category}]

Etapa 2: Búsqueda Profunda

Objetivo: Recopilar datos verificados para cada producto identificado.

1. Búsqueda web sistemática (para CADA producto de la lista):

   • "[Nombre exacto del producto] specifications" → Sitio del fabricante + GSMArena
   • "[SKU] ficha técnica" → Confirmación del SKU
   • "[Nombre del producto] precio Jumia Côte d'Ivoire" → Precio local FCFA
   • "[Nombre del producto] colores disponibles" → Paleta de colores

2. Extracción de datos:

   • Especificaciones técnicas completas
   • Configuraciones disponibles (RAM × Almacenamiento para tech, Capacidad × Potencia para appliance)
   • Colores estándar y exclusivos
   • Precio por configuración y por fuente
   • Números de modelo regionales si procede

3. Validación cruzada:

   • Cada dato técnico crítico debe aparecer en 2+ fuentes
   • Si un dato no puede confirmarse, agregar "confidence_level": "low" en los metadatos
   • Comparar precios entre fuentes para establecer un rango realista

4. Salida esperada: Notas de búsqueda brutas (mentales, sin archivo intermedio)

Etapa 3: Ensamblaje del JSON

Objetivo: Estructurar los datos en el esquema JSON estandarizado.

1. Cargar la plantilla correcta según el tipo de producto:

   • Tech → Templates/Template_ProductData_tech.json
   • Appliance → Templates/Template_ProductData_appliance.json

2. Rellenar las secciones en orden:

   • product_identity → Identidad comercial y categorización
   • model_numbers → SKU primario, variantes regionales, disambiguation
   • variants → Una entrada por configuración (RAM/Almacenamiento o Capacidad)
   • colors → Estándar, exclusivos, predeterminado
   • key_specifications → Datos técnicos verificados
   • sources → Todas las fuentes consultadas con URLs y fechas

3. Rellenar los metadatos:

   • generation_metadata.generated_date → Fecha del día (YYYY-MM-DD)
   • generation_metadata.confidence_level → "high", "medium" o "low"
   • generation_metadata.batch_id → Identificador del lote si aplica

4. Guardar en el directorio apropiado:

   product-data/[brand-slug]/[series-slug]/product-data-[model-slug].json
   

   • Ejemplo: product-data/samsung/galaxy-s25/product-data-s25-plus.json

Etapa 4: Validación Automática

Objetivo: Verificar la conformidad del JSON mediante el script de validación.

1. Ejecutar el script:

   # Validación unitaria
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[brand]/[series]/product-data-[model].json"
   
   # Validación por lote (toda la serie)
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[brand]/[series]/" --batch
   

2. Interpretar los resultados:

   • 🔴 FATAL: Corregir inmediatamente y revalidar
   • 🟡 WARNING: Corregir si es posible, documentar si no

3. Bucle de corrección:

   • Máximo 3 intentos de corrección
   • Si falla después de 3 intentos: escalar al usuario
   • Siempre revalidar después de cada corrección

Etapa 5: Informe de Producción

Objetivo: Notificar al usuario del resultado final.

1. Resumen por producto:

   Producto	SKU	Archivo	Estado	Confianza
   Galaxy S25+	SM-S936B	product-data-s25-plus.json	✅	high

2. Archivos generados: Listar las rutas completas

3. Advertencias residuales: Listar los warnings no resueltos

4. Siguiente paso: Indicar que los archivos están listos para verificación manual o como fuente de referencia

---

Mapeo de Categorías

El archivo category_specs_map.json define:

• Los campos de especificaciones obligatorios y opcionales por categoría
• Los rangos de precios realistas en FCFA por categoría
• Los patrones regex de números de modelo por fabricante

Categorías Tech Soportadas

Categoría	Plantilla	Ejemplos
smartphone	tech	iPhone 17, Galaxy S25, Redmi Note 14
tablet	tech	iPad Pro, Galaxy Tab S10, Xiaomi Pad 7
laptop	tech	MacBook Pro, HP Pavilion, ThinkPad
pc_desktop	tech	iMac, HP ProDesk, Dell OptiPlex
audio	tech	AirPods Pro, Sony WH-1000XM5, JBL Flip
wearable	tech	Apple Watch, Galaxy Watch, Xiaomi Band
storage	tech	SSD Samsung 990 Pro, USB SanDisk
printer	tech	HP LaserJet, Epson EcoTank, Canon PIXMA
peripheral	tech	Teclado Logitech, Ratón Razer, Webcam

Categorías Appliance Soportadas

Categoría	Plantilla	Ejemplos
appliance_refrigerator	appliance	Hisense RD-49DC, Beko RDNE
appliance_washer	appliance	Samsung WW80, Beko WTE
appliance_cooker	appliance	Unionaire C6060, Toshiba TS-698
appliance_ac	appliance	Carrier 42KHL, TCL TAC
appliance_tv	appliance	Hisense 43A4K, TCL 55P745
appliance_small	appliance	Philips GC1742, Galaxy Mixeur
appliance_fan	appliance	Toshiba F-LSD10, Nasco NAS-FD
appliance_water	appliance	Nasco WD-100, Hisense YLR

---

Lista de Verificación de Calidad

• SKU Verificado: El número de modelo coincide exactamente con el del fabricante oficial
• Cero Confusión: Las especificaciones de este producto NO son las de un modelo vecino
• Variantes Completas: Cada configuración (RAM/Almacenamiento o Capacidad) tiene su entrada
• Precios Documentados: Al menos una fuente de precio por variante
• Colores Listados: Colores estándar y exclusivos identificados
• 2+ Fuentes: Mínimo 2 fuentes distintas con URLs válidas
• Sin Placeholders: Ningún campo obligatorio con valor vacío o "N/A"
• Fecha Rellenada: generated_date y price_date completados
• Script de Validación: validate_product_data.py devuelve código de salida 0

---

Herramientas y Recursos

Herramienta	Ruta	Uso
Plantilla Tech	Templates/Template_ProductData_tech.json	Esquema para productos tech
Plantilla Appliance	Templates/Template_ProductData_appliance.json	Esquema para electrodomésticos
Mapa de Categorías	scripts/tools/product_data/category_specs_map.json	Mapeo de especificaciones por categoría
Script de Validación	scripts/tools/product_data/validate_product_data.py	Validación automática JSON
Orquestador	.agents/skill/orchestrateur_production/orchestrateur.md	Escalada en caso de bloqueo

---

Versión: 1.0 Última actualización: 09 Mayo 2026 Vinculación: Flujo de trabajo /generate-product-data exclusivamente