comparison-shopping

name	comparison-shopping
description	Advanced product comparison skill with spec fetching, unit normalization, and comparison matrix generation
version	1.0
authors	["Commerce Team"]
tags	["comparison","shopping","matrix","specs","analysis","decision"]
inputs	[{"name":"product_ids","type":"array","description":"List of product IDs to compare","required":true},{"name":"criteria","type":"array","description":"Comparison criteria/attributes to evaluate","required":false},{"name":"weights","type":"object","description":"Optional weights for each criterion (0-1)","required":false}]
outputs	[{"name":"comparison_matrix","type":"object","description":"Structured comparison data with normalized values"},{"name":"recommendations","type":"array","description":"Ranked recommendations based on criteria"},{"name":"winner","type":"object","description":"Best product based on weighted analysis"}]

Comparison Shopping Skill

Advanced intelligent product comparison that fetches specifications, normalizes units across products, and generates comprehensive comparison matrices for informed decision-making.

Overview

This skill enables agents to perform sophisticated product comparisons by:

1. Fetching complete specifications for each product
2. Normalizing disparate units to common measurements
3. Building structured comparison matrices
4. Scoring and ranking products based on weighted criteria
5. Providing clear winner recommendations

Workflow

┌─────────────────────────────────────────────────────────────────────────┐
│                     COMPARISON SHOPPING WORKFLOW                        │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  Input: product_ids[], criteria[]?, weights{}?                          │
│                                                                         │
│  Step 1: SPEC FETCHING                                                  │
│  ┌────────────────────────────────────────────────────────────────┐     │
│  │  For each product_id:                                          │     │
│  │    → Fetch product details from catalog                        │     │
│  │    → Extract all specifications                                │     │
│  │    → Identify comparable attributes                            │     │
│  └────────────────────────────────────────────────────────────────┘     │
│                           │                                             │
│                           ▼                                             │
│  Step 2: UNIT NORMALIZATION                                             │
│  ┌────────────────────────────────────────────────────────────────┐     │
│  │  Normalize units to common base:                               │     │
│  │    → Weight: convert to grams                                  │     │
│  │    → Dimensions: convert to millimeters                        │     │
│  │    → Storage: convert to gigabytes                             │     │
│  │    → Battery: convert to milliamp-hours                        │     │
│  │    → Price: normalize to base currency                         │     │
│  └────────────────────────────────────────────────────────────────┘     │
│                           │                                             │
│                           ▼                                             │
│  Step 3: MATRIX GENERATION                                              │
│  ┌────────────────────────────────────────────────────────────────┐     │
│  │  Build comparison matrix:                                      │     │
│  │    → Rows: products                                            │     │
│  │    → Columns: criteria/attributes                              │     │
│  │    → Cells: normalized values + original values                │     │
│  │    → Indicators: better/worse/equal markers                    │     │
│  └────────────────────────────────────────────────────────────────┘     │
│                           │                                             │
│                           ▼                                             │
│  Step 4: SCORING & RANKING                                              │
│  ┌────────────────────────────────────────────────────────────────┐     │
│  │  Calculate scores:                                             │     │
│  │    → Apply weights to each criterion                           │     │
│  │    → Normalize scores to 0-100 scale                           │     │
│  │    → Compute weighted total score                              │     │
│  │    → Rank products by total score                              │     │
│  └────────────────────────────────────────────────────────────────┘     │
│                           │                                             │
│                           ▼                                             │
│  Output: comparison_matrix, recommendations[], winner                   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Spec Fetching Rules

Product Data Extraction

fetch_strategy:
  primary_source: product_catalog
  fallback_sources:
    - product_details_api
    - cached_specifications

  required_fields:
    - id
    - name
    - price
    - specifications

  optional_fields:
    - ratings
    - reviews_count
    - availability
    - brand
    - category

Specification Categories

Category	Common Specs	Priority
Physical	weight, dimensions, color	high
Performance	speed, capacity, power	high
Display	size, resolution, type	medium
Battery	capacity, life, charging	medium
Storage	capacity, type, speed	medium
Connectivity	wifi, bluetooth, ports	low
Warranty	duration, coverage	low

Unit Normalization Rules

Weight Conversions

weight_normalization:
  base_unit: grams
  conversions:
    kg: multiply_by_1000
    lb: multiply_by_453.592
    lbs: multiply_by_453.592
    oz: multiply_by_28.3495
    mg: divide_by_1000

  patterns:
    - regex: "(\d+(?:\.\d+)?)\s*(kg|g|lb|lbs|oz|mg)"
      capture_groups: [value, unit]

Dimension Conversions

dimension_normalization:
  base_unit: millimeters
  conversions:
    m: multiply_by_1000
    cm: multiply_by_10
    in: multiply_by_25.4
    inch: multiply_by_25.4
    inches: multiply_by_25.4
    ft: multiply_by_304.8

  patterns:
    - regex: "(\d+(?:\.\d+)?)\s*[xX×]\s*(\d+(?:\.\d+)?)\s*[xX×]\s*(\d+(?:\.\d+)?)\s*(mm|cm|in|inch)"
      format: "LxWxH"

Storage Conversions

storage_normalization:
  base_unit: gigabytes
  conversions:
    TB: multiply_by_1000
    tb: multiply_by_1000
    GB: multiply_by_1
    gb: multiply_by_1
    MB: divide_by_1000
    mb: divide_by_1000
    KB: divide_by_1000000
    kb: divide_by_1000000

  patterns:
    - regex: "(\d+(?:\.\d+)?)\s*(TB|GB|MB|KB|tb|gb|mb|kb)"

Battery Conversions

battery_normalization:
  base_unit: milliamp_hours
  conversions:
    Ah: multiply_by_1000
    ah: multiply_by_1000
    mAh: multiply_by_1
    wh: requires_voltage_context

  patterns:
    - regex: "(\d+(?:\.\d+)?)\s*(mAh|Ah|Wh)"

Price Normalization

price_normalization:
  base_currency: USD
  strategies:
    - use_provided_exchange_rates
    - fetch_current_rates
    - assume_same_currency

  formatting:
    remove_symbols: ["$", "€", "£", "¥"]
    remove_separators: [","]
    decimal_point: "."

Comparison Matrix Structure

Matrix Format

interface ComparisonMatrix {
  products: ProductRow[];
  criteria: CriterionColumn[];
  cells: MatrixCell[][];
  metadata: MatrixMetadata;
}

interface ProductRow {
  product_id: string;
  name: string;
  total_score: number;
  rank: number;
}

interface CriterionColumn {
  name: string;
  category: string;
  unit: string;
  weight: number;
  higher_is_better: boolean;
}

interface MatrixCell {
  raw_value: string | number;
  normalized_value: number;
  display_value: string;
  score: number;          // 0-100
  indicator: "best" | "good" | "average" | "below_average" | "worst";
}

Indicator Assignment

indicator_rules:
  best:
    condition: "score >= 90 AND rank == 1"
    symbol: "★"
  good:
    condition: "score >= 70"
    symbol: "●"
  average:
    condition: "score >= 40"
    symbol: "○"
  below_average:
    condition: "score >= 20"
    symbol: "△"
  worst:
    condition: "score < 20"
    symbol: "▽"

Scoring Algorithm

Score Calculation

For each criterion c in criteria:
  For each product p in products:

    IF c.higher_is_better:
      raw_score = (p.value[c] - min_value[c]) / (max_value[c] - min_value[c])
    ELSE:
      raw_score = (max_value[c] - p.value[c]) / (max_value[c] - min_value[c])

    normalized_score = raw_score * 100
    weighted_score = normalized_score * c.weight

Total Score = SUM(weighted_scores) / SUM(weights)

Default Weights

default_weights:
  price: 0.25           # Lower is better
  performance: 0.20     # Higher is better
  quality: 0.15         # Higher is better
  features: 0.15        # Higher is better
  reviews: 0.10         # Higher is better
  warranty: 0.10        # Higher is better
  availability: 0.05    # Boolean

Higher/Lower Preferences

criterion_preferences:
  higher_is_better:
    - performance
    - battery_life
    - storage_capacity
    - screen_size
    - resolution
    - rating
    - reviews_count
    - warranty_months
    - ram
    - processor_speed

  lower_is_better:
    - price
    - weight
    - response_time
    - noise_level
    - power_consumption

Recommendation Generation

Recommendation Rules

recommendation_types:
  best_overall:
    criteria: highest_total_score
    label: "Best Overall Choice"

  best_value:
    criteria: highest_score_per_dollar
    calculation: "total_score / price"
    label: "Best Value"

  best_in_category:
    criteria: highest_score_for_criterion
    for_each: primary_criteria
    label: "Best for {criterion}"

  budget_pick:
    criteria: "price <= budget AND acceptable_score"
    threshold: score >= 60
    label: "Budget-Friendly Option"

  premium_pick:
    criteria: highest_quality_score
    quality_criteria: [build, warranty, brand_reputation]
    label: "Premium Choice"

Output Format

interface Recommendation {
  product_id: string;
  product_name: string;
  type: "best_overall" | "best_value" | "best_in_category" | "budget_pick" | "premium_pick";
  label: string;
  score: number;
  highlights: string[];       // Key advantages
  considerations: string[];   // Potential drawbacks
}

Usage Examples

Basic Comparison

Input:
  product_ids: ["laptop-001", "laptop-002", "laptop-003"]

Output:
  comparison_matrix: {
    products: [...],
    criteria: [price, performance, display, battery, weight],
    cells: [...]
  }
  recommendations: [
    { type: "best_overall", product_id: "laptop-002", score: 87 }
  ]
  winner: { id: "laptop-002", name: "ProBook X5", score: 87 }

Weighted Comparison

Input:
  product_ids: ["phone-a", "phone-b", "phone-c"]
  criteria: ["price", "camera", "battery", "display"]
  weights: {
    price: 0.4,      # User prioritizes budget
    camera: 0.3,     # Camera important
    battery: 0.2,    # Battery secondary
    display: 0.1     # Display least important
  }

Output:
  winner: { id: "phone-a", name: "Budget Pro", score: 82 }
  recommendations: [
    { type: "best_overall", product_id: "phone-a" },
    { type: "best_value", product_id: "phone-a" },
    { type: "best_in_category", product_id: "phone-c", category: "camera" }
  ]

Specific Criteria Comparison

Input:
  product_ids: ["tv-55-a", "tv-55-b", "tv-65-c"]
  criteria: ["picture_quality", "smart_features", "price", "reviews"]

Output:
  comparison_matrix: {
    criteria: [
      { name: "picture_quality", weight: 0.3, higher_is_better: true },
      { name: "smart_features", weight: 0.25, higher_is_better: true },
      { name: "price", weight: 0.3, higher_is_better: false },
      { name: "reviews", weight: 0.15, higher_is_better: true }
    ],
    ...
  }

Edge Cases

Missing Data Handling

missing_data_strategies:
  criterion_missing_for_product:
    action: exclude_from_criterion_scoring
    note: "N/A in matrix"

  criterion_missing_for_all:
    action: remove_criterion
    warning: "Criterion '{name}' removed - no data available"

  product_missing_critical_specs:
    action: flag_incomplete
    threshold: "> 50% criteria missing"
    warning: "Incomplete data for {product}"

Incomparable Products

incompatible_detection:
  different_categories:
    check: products have same category
    action: warn_user
    message: "Comparing products from different categories may yield misleading results"

  vastly_different_price:
    check: max_price / min_price > 3
    action: segment_comparison
    message: "Large price variance detected. Consider comparing within price tiers."

Integration Notes

• Works with product-catalog skill for fetching product data
• Complements smart-search skill for finding products to compare
• Can be chained with checkout skill after winner selection
• Supports both real-time and cached comparison modes