Cism-Ch/product-intelligence

SKILL: Product Intelligence — Recherche & Generierung von JSON-Produktblättern

Dieses Skill definiert die operative Vorgehensweise zur Recherche, Strukturierung und Validierung von Tech- und Appliance-Produktdaten als standardisierte JSON-Dateien. Es dient als exklusive Ausführungsengine für den Workflow /generate-product-data.

[!CAUTION] Zwingende Richtlinie: Dieses Skill unterliegt der VERIFICATION_IMPERATIVE.md. KEINE technischen Daten dürfen aus dem internen Speicher der KI stammen. Die Trainingsdaten sind für Produktspezifikationen, SKUs und Preise systematisch veraltet, unvollständig oder fehlerhaft. Jedes technische Feld MUSS auf Basis von Echtzeit-Websuchergebnissen ausgefüllt werden.

⚠️ GOLDENE REGEL: Dieser Workflow ist eine Wahrheitsquelle für Produktdaten. Er generiert weder HTML noch CSV. Er erzeugt JSON-Referenzdateien, die zur Überprüfung anderer Workflows oder als Produktdatenbank verwendet werden können.

---

Grundlegende Richtlinien

0. Identität & Workflow-Bindung

• Dieses Skill ist streng dem Workflow /generate-product-data zugeordnet.
• NICHT verwechseln mit den Workflows production-industrielle-v3 oder produce-appliance, die HTML/CSV generieren.
• NICHT die JSON-Schemata dieses Workflows mit vorhandenen Template_Pack_v3_*.json vermischen.
• Die generierten Dateien werden in product-data/ gespeichert (getrennt von products/ und products-appliance/).

1. Absolute Genauigkeit der Modellnummern (KRITISCH)

• Die Modellnummer (Hersteller-SKU) ist das wichtigste Feld der JSON-Datei.
• VERBOTEN: Eine SKU erfinden, erraten oder von einem ähnlichen Modell ableiten.
• VERPFLICHTEND: Die SKU auf der offiziellen Website des Herstellers oder auf 2+ vertrauenswürdigen Quellen überprüfen.
• BEISPIELE für häufige Verwechslungen (internationale SKUs, Stand Mai 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)
  • ⚠️ ACHTUNG: Diese Beispiele können veralten. IMMER über eine Websuche neu überprüfen.
• Das Feld disambiguation_notes ist immer dann auszufüllen, wenn ein Verwechslungsrisiko besteht.

2. Überprüfte Recherche & Quellen — WEBSUCHE PFLICHT

[!WARNING] NIE den KI-Speicher als Quelle für technische Daten verwenden. KI-Modelle haben Trainingsdaten mit einem Zeitversatz von mehreren Monaten bis Jahren. Produkte können umbenannt, SKUs neu zugewiesen, Spezifikationen seit dem Cutoff-Datum geändert worden sein.

• Quellenhierarchie (in der Reihenfolge der Priorität):

  1. 🥇 Offizielle Website des Herstellers (samsung.com, apple.com, xiaomi.com...) — Zwingend zuerst zu konsultieren
  2. 🥈 Technische Datenbanken (GSMArena, DeviceSpecifications, NotebookCheck, Kimovil)
  3. 🥉 Lokale Verkaufsseiten (Jumia CI, westafrikanische Märkte)
  4. 4️⃣ Internationale Händler (Amazon, AliExpress, B&H Photo)
  5. 5️⃣ Hersteller-PDF-Kataloge / Unterhändler

• Mindestens 2 verschiedene Webquellen zur Bestätigung einer kritischen technischen Angabe.

• Der KI-Speicher zählt NICHT als Quelle — nur Echtzeit-Websuchen sind gültig.

• VERBOTEN: Leak-Seiten, Gerüchte, ungeprüfte Daten, nicht moderierte Foren, Daten aus dem KI-Speicher.

• WENN eine Angabe nicht gefunden werden kann: Das Feld leer lassen, anstatt einen Wert zu erfinden.

3. Lokale Preisgestaltung (Markt Elfenbeinküste)

• Hauptquelle: Jumia CI (jumia.ci), dann andere westafrikanische Marktplätze.
• Format: Preisspanne in FCFA (market_price_range_fcfa.min / max).
• Mehrere Varianten → Mehrere Preise (eine pro RAM-/Speicherkonfiguration).
• Preis nicht verfügbar: "price_source": "Non disponible localement" eintragen, anstatt stilles null.
• Preisdatum: Immer price_date im Format YYYY-MM angeben.

4. Variantenverwaltung (Resilienz)

• Wenn der Benutzer eine Serie erwähnt (z. B. "Samsung Galaxy S25"), MUSS der Workflow:
  1. ALLE bekannten Varianten der Serie auflisten
  2. Die Liste mit dem Benutzer bestätigen (oder alle im Batch verarbeiten)
  3. EINE JSON-Datei PRO Variante generieren
• Jede Variante hat ihre eigenen: SKU, Konfigurationen, Preise, Farbvarianten.
• VERBOTEN: Spezifikationen von einem Modell auf ein anderes derselben Serie kopieren.

5. Null Platzhalter, Null Halluzination

• Kein Wert "", "N/A", "TBD", "TODO", "???" ist in Pflichtfeldern erlaubt.
• Wenn eine Information nicht gefunden wird und optional ist: das Feld aus dem JSON entfernen.
• Wenn eine Information nicht gefunden wird und sie obligatorisch ist: das Fehlen in generation_metadata.notes dokumentieren.

---

Operative Vorgehensweise (Pipeline)

Stufe 1: Produktidentifikation

Ziel: Die Benutzeranfrage in eine präzise Liste der zu verarbeitenden Produkte umwandeln.

1. Anfrage parsen:

   • "Samsung Galaxy S25" → Serie S25 identifizieren
   • "iPhone 16 Pro" → Ein bestimmtes Modell identifizieren
   • "Hisense Kühlschränke" → Eine Markenkategorie identifizieren

2. Varianten auflisten:

   • Auf der Hersteller-Website alle Varianten der Serie suchen
   • Offizielle Modellnummern für jede Variante notieren
   • Wichtige Unterschiede zwischen Varianten dokumentieren

3. Umfang bestätigen (Batch-Modus):

   • Die vollständige Liste dem Benutzer präsentieren
   • Beispiel: "Ich habe 4 Varianten identifiziert: S25 (SM-S931B), S25+ (SM-S936B), S25 Ultra (SM-S938B), S25 FE (SM-S72xB). Soll ich mit allen 4 fortfahren?"

4. Erwartete Ausgabe: Strukturierte Liste [{name, sku, category, sub_category}]

Stufe 2: Vertiefte Recherche

Ziel: Überprüfte Daten für jedes identifizierte Produkt sammeln.

1. Systematische Websuche (für JEDES Produkt in der Liste):

   • "[Exakter Produktname] specifications" → Hersteller-Website + GSMArena
   • "[SKU] fiche technique" → Bestätigung der SKU
   • "[Produktname] prix Jumia Côte d'Ivoire" → Lokaler Preis in FCFA
   • "[Produktname] coloris disponibles" → Farbpalette

2. Datenextraktion:

   • Vollständige technische Spezifikationen
   • Verfügbare Konfigurationen (RAM × Speicher für Tech, Kapazität × Leistung für Appliance)
   • Standard- und exklusive Farbvarianten
   • Preis pro Konfiguration und pro Quelle
   • Regionale Modellnummern, falls relevant

3. Kreuzvalidierung:

   • Jede kritische technische Angabe muss in 2+ Quellen erscheinen
   • Wenn eine Angabe nicht bestätigt werden kann, "confidence_level": "low" in den Metadaten hinzufügen
   • Preise zwischen Quellen vergleichen, um eine realistische Spanne zu ermitteln

4. Erwartete Ausgabe: Rohe Recherchenotizen (gedanklich, keine Zwischendatei)

Stufe 3: JSON-Zusammenstellung

Ziel: Die Daten in das standardisierte JSON-Schema strukturieren.

1. Das richtige Template laden, je nach Produkttyp:

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

2. Abschnitte in der Reihenfolge ausfüllen:

   • product_identity → Handelsbezeichnung und Kategorisierung
   • model_numbers → Primäre SKU, regionale Varianten, Disambiguierung
   • variants → Ein Eintrag pro Konfiguration (RAM/Speicher oder Kapazität)
   • colors → Standard, exklusiv, Standardfarbe
   • key_specifications → Überprüfte technische Daten
   • sources → Alle konsultierten Quellen mit URLs und Daten

3. Metadaten ausfüllen:

   • generation_metadata.generated_date → Aktuelles Datum (YYYY-MM-DD)
   • generation_metadata.confidence_level → "high", "medium" oder "low"
   • generation_metadata.batch_id → Batch-Identifikator, falls zutreffend

4. Im entsprechenden Verzeichnis speichern:

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

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

Stufe 4: Automatische Validierung

Ziel: Die Konformität des JSON über das Validierungsskript prüfen.

1. Skript ausführen:

   # Einzelvalidierung
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[brand]/[series]/product-data-[model].json"
   
   # Batch-Validierung (gesamte Serie)
   python scripts/tools/product_data/validate_product_data.py \
     --input "product-data/[brand]/[series]/" --batch
   

2. Ergebnisse interpretieren:

   • 🔴 FATAL: Sofort korrigieren und erneut validieren
   • 🟡 WARNING: Nach Möglichkeit korrigieren, andernfalls dokumentieren

3. Korrektur-Loop:

   • Maximal 3 Korrekturversuche
   • Bei Fehlschlag nach 3 Versuchen: an den Benutzer eskalieren
   • Nach jeder Korrektur erneut validieren

Stufe 5: Produktionsbericht

Ziel: Den Benutzer über das Endergebnis informieren.

1. Zusammenfassung pro Produkt:

   Produkt	SKU	Datei	Status	Vertrauen
   Galaxy S25+	SM-S936B	product-data-s25-plus.json	✅	high

2. Generierte Dateien: Vollständige Pfade auflisten

3. Verbleibende Warnungen: Nicht gelöste Warnungen auflisten

4. Nächster Schritt: Angeben, dass die Dateien zur manuellen Überprüfung oder als Referenzquelle bereit sind

---

Kategorien-Mapping

Die Datei category_specs_map.json definiert:

• Obligatorische und optionale Spezifikationsfelder pro Kategorie
• realistische Preisspannen in FCFA pro Kategorie
• Regex-Muster für Modellnummern pro Hersteller

Unterstützte Tech-Kategorien

Kategorie	Template	Beispiele
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-Stick SanDisk
printer	tech	HP LaserJet, Epson EcoTank, Canon PIXMA
peripheral	tech	Logitech-Tastatur, Razer-Maus, Webcam

Unterstützte Appliance-Kategorien

Kategorie	Template	Beispiele
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

---

Qualitätsprüfungs-Checkliste

• SKU Verifiziert: Die Modellnummer stimmt exakt mit der des offiziellen Herstellers überein
• Keine Verwechslung: Die Spezifikationen dieses Produkts sind NICHT die eines benachbarten Modells
• Varianten Vollständig: Jede Konfiguration (RAM/Speicher oder Kapazität) hat ihren eigenen Eintrag
• Preise Dokumentiert: Mindestens eine Preisquelle pro Variante angegeben
• Farben Aufgelistet: Standard- und exklusive Farbvarianten identifiziert
• 2+ Quellen: Mindestens 2 getrennte Quellen mit gültigen URLs
• Kein Platzhalter: Kein Pflichtfeld mit leerem Wert oder "N/A"
• Datum Ausgefüllt: generated_date und price_date ausgefüllt
• Validierungsskript: validate_product_data.py gibt Exit-Code 0 zurück

---

Werkzeuge und Ressourcen

Werkzeug	Pfad	Verwendung
Tech-Template	Templates/Template_ProductData_tech.json	Schema für Tech-Produkte
Appliance-Template	Templates/Template_ProductData_appliance.json	Schema für Haushaltsgeräte
Kategorien-Map	scripts/tools/product_data/category_specs_map.json	Spezifikations-Mapping pro Kategorie
Validierungsskript	scripts/tools/product_data/validate_product_data.py	Automatische JSON-Validierung
Orchestrator	.agents/skill/orchestrateur_production/orchestrateur.md	Eskalation bei Blockaden

---

Version: 1.0 Letzte Aktualisierung: 09. Mai 2026 Bindung: Ausschließlich Workflow /generate-product-data