algo-ecom-ranking

name	"algo-ecom-ranking"
description	"Design multi-objective e-commerce product ranking combining relevance, conversion, and business metrics. Use this skill when the user needs to build a product ranking system beyond text relevance, balance relevance with commercial objectives, or implement learning-to-rank — even if they say 'product sorting', 'search result ranking', or 'how to rank products'.".
allowed-tools	Read, Glob, Grep

E-Commerce Product Ranking

Overview

E-commerce ranking combines text relevance (BM25) with commercial signals (CTR, conversion rate, revenue, margin) into a unified ranking score. Uses learning-to-rank (LTR) models trained on click and conversion data to optimize for business-relevant outcomes.

When to Use

Trigger conditions:

• Building a product search/browse ranking beyond pure text relevance
• Incorporating business metrics (margin, inventory) into ranking
• Implementing a learning-to-rank pipeline

When NOT to use:

• For pure text search relevance only (use BM25)
• When no click/conversion data exists (start with rule-based ranking)

Algorithm

IRON LAW: Relevance Is Necessary But NOT Sufficient for E-Commerce Ranking
A result that is textually relevant but has zero sales history, no
reviews, and is out of stock serves no one. E-commerce ranking must
balance: relevance (does it match the query?), quality (is it a good
product?), and commercial value (does it generate revenue?).

Phase 1: Input Validation

Collect features per product-query pair: text relevance score (BM25), historical CTR, conversion rate, average rating, review count, price competitiveness, inventory level, margin. Gate: Minimum features available, click data from 30+ days.

Phase 2: Core Algorithm

Rule-based baseline: Score = w₁×relevance + w₂×popularity + w₃×rating + w₄×recency. Manually tune weights.

LTR approach:

1. Generate training data from click logs (clicked = positive, skipped = negative, with position debiasing)
2. Features: text match, behavioral (CTR, add-to-cart rate), product quality (rating, reviews), freshness, price
3. Train: LambdaMART or gradient-boosted ranking model optimizing NDCG
4. Blend: final_score = α × LTR_score + (1-α) × business_boost

Phase 3: Verification

Evaluate offline: NDCG@10, MRR. A/B test online: revenue per search, click-through rate, conversion rate. Gate: NDCG improves over baseline, A/B test positive on primary metric.

Phase 4: Output

Return ranked product list with score decomposition.

Output Format

{
  "results": [{"product_id": "P123", "rank": 1, "final_score": 0.92, "components": {"relevance": 0.85, "popularity": 0.95, "quality": 0.90}}],
  "metadata": {"query": "wireless earbuds", "model": "lambdamart", "ndcg_at_10": 0.72}
}

Examples

Sample I/O

Input: Query "laptop", 500 matching products Expected: Top results balance text match + high conversion + good ratings, not just keyword relevance.

Edge Cases

Input	Expected	Why
New product, no history	Rely on text relevance + category avg	Cold start — no behavioral signal
Out of stock item	Demote or remove	Showing unavailable products frustrates users
Sponsored product	Blend ad rank with organic	Separate sponsored from organic clearly

Gotchas

• Position bias in training data: Higher-ranked items get more clicks regardless of quality. Debias training data using inverse propensity weighting or randomization experiments.
• Popularity bias: Without diversity controls, popular items dominate rankings. New or niche products get no exposure. Add exploration bonus.
• Revenue optimization ≠ user satisfaction: Ranking by margin pushes expensive products up. Users lose trust if results feel commercially manipulated.
• Feature freshness: Click signals change daily. Retrain or update features frequently. Stale features degrade ranking quality.
• Category-specific models: A single ranking model may not work across all categories. Electronics ranking differs from fashion ranking.

References

• For LambdaMART implementation, see references/lambdamart.md
• For position debiasing techniques, see references/position-debiasing.md