Cism-Ch/product-intelligence

SKILL: Product Intelligence — Pesquisa & Geração de Fichas de Produtos JSON

Este skill define o procedimento operacional para pesquisar, estruturar e validar dados de produtos Tech e Eletrodomésticos no formato de arquivos JSON padronizados. Ele serve como motor de execução exclusivo para o workflow /generate-product-data.

[!CAUTION] DIRETIVA IMPERATIVA: Este skill está sujeito a VERIFICATION_IMPERATIVE.md. NENHUM dado técnico deve provir da memória interna da IA. Os dados de treinamento estão sistematicamente desatualizados, incompletos ou incorretos para especificações de produtos, SKUs e preços. Cada campo técnico DEVE ser preenchido a partir de resultados de pesquisa web em tempo real.

⚠️ REGRA DE OURO: Este workflow é uma fonte de verdade para os dados dos produtos. Ele não gera HTML nem CSV. Ele produz arquivos JSON de referência que podem ser usados para verificar outros workflows ou como base de dados de produto.

---

Diretivas Fundamentais

0. Identidade & Vinculação do Workflow

• Este skill é estritamente dedicado ao workflow /generate-product-data.
• NÃO confundir com os workflows production-industrielle-v3 ou produce-appliance que geram HTML/CSV.
• NÃO misturar os esquemas JSON deste workflow com os Template_Pack_v3_*.json existentes.
• Os arquivos gerados são armazenados em product-data/ (separado de products/ e products-appliance/).

1. Precisão Absoluta dos Model Numbers (CRÍTICO)

• O model number (SKU do fabricante) é o campo mais importante do arquivo JSON.
• PROIBIDO: Inventar, adivinhar ou extrapolar um SKU a partir de um modelo vizinho.
• OBRIGATÓRIO: Verificar o SKU no site oficial do fabricante ou em 2+ fontes confiáveis.
• EXEMPLOS de confusões frequentes (SKUs Internacionais verificados em Maio de 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)
  • ⚠️ ATENÇÃO: Estes exemplos podem se tornar obsoletos. SEMPRE re-verificar através de pesquisa web.
• Sempre preencher o campo disambiguation_notes quando existir risco de confusão.

2. Pesquisa Verificada & Fontes — PESQUISA WEB OBRIGATÓRIA

[!WARNING] NUNCA usar a memória da IA como fonte de dados técnicos. Os modelos de IA possuem dados de treinamento com um desfasamento de vários meses a anos. Produtos podem ter sido renomeados, SKUs reatribuídos, especificações modificadas desde a data de corte.

• Hierarquia das fontes (por ordem de prioridade):

  1. 🥇 Site oficial do fabricante (samsung.com, apple.com, xiaomi.com...) — OBRIGATÓRIO como primeira opção
  2. 🥈 Bases de dados técnicas (GSMArena, DeviceSpecifications, NotebookCheck, Kimovil)
  3. 🥉 Sites de venda locais (Jumia CI, mercados da África Ocidental)
  4. 4️⃣ Revendedores internacionais (Amazon, AliExpress, B&H Photo)
  5. 5️⃣ Catálogos PDF do fabricante / subdistribuidores

• Mínimo 2 fontes web distintas para confirmar um dado técnico crítico.

• A memória da IA NÃO conta como fonte — apenas pesquisas web em tempo real são válidas.

• PROIBIDO: Sites de leaks, rumores, dados não verificados, fóruns não moderados, dados provenientes da memória da IA.

• SE um dado for impossível de encontrar: Deixar o campo vazio em vez de inventar um valor.

3. Precificação Local (Mercado da Costa do Marfim)

• Fonte principal: Jumia CI (jumia.ci), depois outros marketplaces da África Ocidental.
• Formato: Faixa de preço em FCFA (market_price_range_fcfa.min / max).
• Várias variantes → Vários preços (um por configuração RAM/Armazenamento).
• Preço não encontrado: Preencher "price_source": "Não disponível localmente" em vez de null silencioso.
• Data do preço: Sempre preencher price_date no formato YYYY-MM.

4. Gestão de Variantes (Resiliência)

• Quando o usuário menciona uma série (ex: "Samsung Galaxy S25"), o workflow DEVE:
  1. Enumerar TODAS as variantes conhecidas da série
  2. Confirmar a lista com o usuário (ou processar todas em lote)
  3. Gerar UM arquivo JSON POR variante
• Cada variante possui seus próprios: SKU, configurações, preços, cores.
• PROIBIDO: Copiar e colar as especificações de um modelo para outro modelo da mesma série.

5. Zero Placeholder, Zero Alucinação

• Nenhum valor "", "N/A", "TBD", "TODO", "???" é aceito nos campos obrigatórios.
• Se uma informação não for encontrada e for opcional: remover o campo do JSON.
• Se uma informação não for encontrada e for obrigatória: documentar a ausência em generation_metadata.notes.

---

Procedimento Operacional (Pipeline)

Estágio 1: Identificação dos Produtos

Objetivo: Transformar a solicitação do usuário em uma lista precisa de produtos a processar.

1. Analisar a solicitação:

   • "Samsung Galaxy S25" → Identificar a série S25
   • "iPhone 16 Pro" → Identificar um modelo específico
   • "Hisense refrigeradores" → Identificar uma categoria de marca

2. Enumerar as variantes:

   • Pesquisar no site do fabricante todas as variantes da série
   • Listar os model numbers oficiais para cada variante
   • Documentar as principais diferenças entre variantes

3. Confirmar o escopo (modo lote):

   • Apresentar a lista completa ao usuário
   • Exemplo: "Identifiquei 4 variantes: S25 (SM-S931B), S25+ (SM-S936B), S25 Ultra (SM-S938B), S25 FE (SM-S72xB). Prosseguimos com as 4?"

4. Saída esperada: Lista estruturada [{name, sku, category, sub_category}]

Estágio 2: Pesquisa Aprofundada

Objetivo: Coletar os dados verificados para cada produto identificado.

1. Pesquisa web sistemática (para CADA produto da lista):

   • "[Nome exato do produto] specifications" → Site do fabricante + GSMArena
   • "[SKU] ficha técnica" → Confirmação do SKU
   • "[Nome do produto] preço Jumia Costa do Marfim" → Preço local FCFA
   • "[Nome do produto] cores disponíveis" → Paleta de cores

2. Extração dos dados:

   • Especificações técnicas completas
   • Configurações disponíveis (RAM × Armazenamento para tech, Capacidade × Potência para eletrodomésticos)
   • Cores padrão e exclusivas
   • Preço por configuração e por fonte
   • Model numbers regionais se pertinente

3. Cross-validação:

   • Cada dado técnico crítico deve aparecer em 2+ fontes
   • Se um dado não puder ser confirmado, adicionar "confidence_level": "low" nos metadados
   • Comparar preços entre fontes para estabelecer uma faixa realista

4. Saída esperada: Anotações de pesquisa brutas (mentais, sem arquivo intermediário)

Estágio 3: Montagem do JSON

Objetivo: Estruturar os dados no esquema JSON padronizado.

1. Carregar o template correto conforme o tipo de produto:

   • Tech → Templates/Template_ProductData_tech.json
   • Eletrodoméstico → Templates/Template_ProductData_appliance.json

2. Preencher as seções na ordem:

   • product_identity → Identidade comercial e categorização
   • model_numbers → SKU primário, variantes regionais, desambiguação
   • variants → Uma entrada por configuração (RAM/Armazenamento ou Capacidade)
   • colors → Padrão, exclusivas, padrão
   • key_specifications → Dados técnicos verificados
   • sources → Todas as fontes consultadas com URLs e datas

3. Preencher os metadados:

   • generation_metadata.generated_date → Data atual (YYYY-MM-DD)
   • generation_metadata.confidence_level → "high", "medium" ou "low"
   • generation_metadata.batch_id → Identificador do lote se aplicável

4. Salvar no diretório apropriado:

   product-data/[marca-slug]/[serie-slug]/product-data-[modelo-slug].json
   

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

Estágio 4: Validação Automática

Objetivo: Verificar a conformidade do JSON através do script de validação.

1. Executar o script:

   # Validação unitária
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[marca]/[serie]/product-data-[modelo].json"
   
   # Validação em lote (toda a série)
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[marca]/[serie]/" --batch
   

2. Interpretar os resultados:

   • 🔴 FATAL: Corrigir imediatamente e re-validar
   • 🟡 WARNING: Corrigir se possível, documentar se não

3. Loop de correção:

   • Máximo de 3 tentativas de correção
   • Se falhar após 3 tentativas: escalonar para o usuário
   • Sempre re-validar após cada correção

Estágio 5: Relatório de Produção

Objetivo: Notificar o usuário sobre o resultado final.

1. Resumo por produto:

   Produto	SKU	Arquivo	Status	Confiança
   Galaxy S25+	SM-S936B	product-data-s25-plus.json	✅	high

2. Arquivos gerados: Listar os caminhos completos

3. Avisos residuais: Listar os warnings não resolvidos

4. Próximo passo: Indicar que os arquivos estão prontos para verificação manual ou como fonte de referência

---

Mapeamento das Categorias

O arquivo category_specs_map.json define:

• Os campos de especificações obrigatórios e opcionais por categoria
• As faixas de preço realistas em FCFA por categoria
• Os padrões regex dos model numbers por fabricante

Categorias Tech suportadas

Categoria	Template	Exemplos
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, Pen Drive SanDisk
printer	tech	HP LaserJet, Epson EcoTank, Canon PIXMA
peripheral	tech	Teclado Logitech, Mouse Razer, Webcam

Categorias Eletrodoméstico suportadas

Categoria	Template	Exemplos
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 Mixer
appliance_fan	appliance	Toshiba F-LSD10, Nasco NAS-FD
appliance_water	appliance	Nasco WD-100, Hisense YLR

---

Quality Check Checklist

• SKU Verificado: O model number corresponde exatamente ao do fabricante oficial
• Zero Confusão: As especificações deste produto NÃO são as de um modelo vizinho
• Variantes Completas: Cada configuração (RAM/Armazenamento ou Capacidade) tem sua entrada
• Preços Documentados: Pelo menos uma fonte de preço por variante
• Cores Listadas: Cores padrão e exclusivas identificadas
• 2+ Fontes: Mínimo 2 fontes distintas com URLs válidas
• Sem Placeholder: Nenhum campo obrigatório com valor vazio ou "N/A"
• Data Preenchida: generated_date e price_date preenchidos
• Script de Validação: validate_product_data.py retorna exit code 0

---

Ferramentas e Recursos

Ferramenta	Caminho	Uso
Template Tech	Templates/Template_ProductData_tech.json	Esquema para produtos tech
Template Eletrodoméstico	Templates/Template_ProductData_appliance.json	Esquema para eletrodomésticos
Mapa de Categorias	scripts/tools/product_data/category_specs_map.json	Mapeamento de especificações por categoria
Script de Validação	scripts/tools/product_data/validate_product_data.py	Validação automática JSON
Orquestrador	.agents/skill/orchestrateur_production/orchestrateur.md	Escalonamento em caso de bloqueio

---

Versão: 1.0 Última atualização: 09 de Maio de 2026 Vinculação: Workflow /generate-product-data exclusivamente