marketplace-personalisation

What this skill does

# Marketplace Engineering Two-Sided Personalisation Best Practices

Comprehensive guide for designing, building and improving personalisation and recommendation
systems in two-sided trust marketplaces on AWS Personalize. Contains 49 rules across 9
categories, ordered by cascade impact on the personalisation lifecycle, plus two playbooks
for planning a new system from scratch and diagnosing an existing one.

## When to Apply

Reference this skill when:

- Designing the event schema and tracking for a new recommender system
- Choosing an AWS Personalize recipe (USER_PERSONALIZATION_v2, SIMS, PERSONALIZED_RANKING_v2)
- Writing or reviewing candidate-generation and re-ranking code for marketplace search or homefeed
- Handling cold start for new providers, new seekers, or new catalog regions
- Diagnosing a live system that "mostly works but feels stale, unfair, or unpersonalised"
- Planning the next experiment, baseline comparison, or A/B test for the recommender
- Investigating concentration, coverage collapse, death spirals, or training-serving skew
- Adding observability dashboards, drift detection, or online metric slicing

## Setup

This skill has no user-specific configuration — it is self-contained. References are live
URLs to official AWS Personalize documentation, academic papers on bias and exposure, and
engineering blogs from Airbnb and DoorDash.

## Rule Categories

Categories are ordered by cascade impact: earlier stages poison everything downstream.

| # | Category | Prefix | Impact |
|---|----------|--------|--------|
| 1 | Event Tracking and Capture | `track-` | CRITICAL |
| 2 | Dataset and Schema Design | `schema-` | CRITICAL |
| 3 | Two-Sided Matching Patterns | `match-` | CRITICAL |
| 4 | Simple Baselines and Theory of Constraints | `simple-` | HIGH |
| 5 | Feedback Loops and Bias Control | `loop-` | HIGH |
| 6 | Cold Start and Coverage | `cold-` | HIGH |
| 7 | Recipe and Pipeline Selection | `recipe-` | MEDIUM-HIGH |
| 8 | Inference, Filters and Re-ranking | `infer-` | MEDIUM-HIGH |
| 9 | Observability and Online Metrics | `obs-` | MEDIUM-HIGH |

## Quick Reference

### 1. Event Tracking and Capture (CRITICAL)

- [`track-log-impressions-alongside-clicks`](references/track-log-impressions-alongside-clicks.md) — the denominator that turns clicks into a rate and unlocks unbiased training
- [`track-use-stable-opaque-item-ids`](references/track-use-stable-opaque-item-ids.md) — prevents history loss when listings rename or move
- [`track-stamp-events-with-request-id`](references/track-stamp-events-with-request-id.md) — the join key that enables impression-to-outcome attribution
- [`track-stream-events-via-putevents`](references/track-stream-events-via-putevents.md) — real-time adaptation versus end-of-day bulk import
- [`track-capture-negative-signals`](references/track-capture-negative-signals.md) — dismissal is information, silence is not
- [`track-measure-outcomes-not-clicks`](references/track-measure-outcomes-not-clicks.md) — reward the completed booking, not the clickbait

### 2. Dataset and Schema Design (CRITICAL)

- [`schema-design-conservatively`](references/schema-design-conservatively.md) — Interactions schemas are immutable, Users/Items are painful to change
- [`schema-keep-user-item-thin`](references/schema-keep-user-item-thin.md) — volatile fields belong in events
- [`schema-enforce-metadata-freshness`](references/schema-enforce-metadata-freshness.md) — PutItems on every metadata change
- [`schema-prefer-categorical-fields`](references/schema-prefer-categorical-fields.md) — unlock per-value features
- [`schema-weight-event-value`](references/schema-weight-event-value.md) — align the model with the business outcome
- [`schema-include-context-everywhere`](references/schema-include-context-everywhere.md) — train-serve feature parity
- [`schema-meet-minimum-dataset-sizes`](references/schema-meet-minimum-dataset-sizes.md) — 50 users / 50 items / 1000 interactions before training

### 3. Two-Sided Matching Patterns (CRITICAL)

- [`match-rank-mutual-fit`](references/match-rank-mutual-fit.md) — rank by mutual accept probability
- [`match-hard-filter-before-ranking`](references/match-hard-filter-before-ranking.md) — retrieval enforces feasibility
- [`match-cap-provider-exposure`](references/match-cap-provider-exposure.md) — diversity as a fairness constraint
- [`match-model-capacity-constraints`](references/match-model-capacity-constraints.md) — capacity-discounted scoring
- [`match-balance-supply-demand`](references/match-balance-supply-demand.md) — per-segment strategy routing

### 4. Simple Baselines and Theory of Constraints (HIGH)

- [`simple-ship-popularity-baseline`](references/simple-ship-popularity-baseline.md) — a reference point that every ML model must beat
- [`simple-find-bottleneck-first`](references/simple-find-bottleneck-first.md) — diagnostic before optimisation
- [`simple-heuristic-rerank-cold-cohorts`](references/simple-heuristic-rerank-cold-cohorts.md) — trust × recency × proximity
- [`simple-budget-complexity`](references/simple-budget-complexity.md) — ship or kill criterion before running
- [`simple-audit-before-build`](references/simple-audit-before-build.md) — telemetry audit gates model work
- [`simple-measure-gap-to-baseline`](references/simple-measure-gap-to-baseline.md) — baseline retained as permanent minority bucket

### 5. Feedback Loops and Bias Control (HIGH)

- [`loop-log-ranking-slot`](references/loop-log-ranking-slot.md) — slot data for position-bias correction
- [`loop-reserve-random-exploration`](references/loop-reserve-random-exploration.md) — unbiased training data
- [`loop-optimize-completed-outcome`](references/loop-optimize-completed-outcome.md) — reward the goal, not the proxy
- [`loop-decay-event-weights`](references/loop-decay-event-weights.md) — old preferences fade
- [`loop-detect-death-spirals`](references/loop-detect-death-spirals.md) — exposure Gini as a leading indicator

### 6. Cold Start and Coverage (HIGH)

- [`cold-use-v2-recipe-with-metadata`](references/cold-use-v2-recipe-with-metadata.md) — metadata extrapolates to new listings
- [`cold-best-of-segment-popularity`](references/cold-best-of-segment-popularity.md) — segmentation beats global top-N
- [`cold-capture-onboarding-intent`](references/cold-capture-onboarding-intent.md) — ask instead of guessing
- [`cold-reserve-exploration-slots`](references/cold-reserve-exploration-slots.md) — promotions filter for fresh inventory
- [`cold-tag-cold-start-recs`](references/cold-tag-cold-start-recs.md) — warm-versus-cold metric slicing

### 7. Recipe and Pipeline Selection (MEDIUM-HIGH)

- [`recipe-default-to-user-personalization-v2`](references/recipe-default-to-user-personalization-v2.md) — discovery default
- [`recipe-sims-for-item-page-only`](references/recipe-sims-for-item-page-only.md) — similar-items is not a homepage recipe
- [`recipe-personalized-ranking-as-reranker`](references/recipe-personalized-ranking-as-reranker.md) — not a candidate generator
- [`recipe-build-candidate-rerank-pipeline`](references/recipe-build-candidate-rerank-pipeline.md) — two layers, two concerns
- [`recipe-defer-hpo-until-baseline-measured`](references/recipe-defer-hpo-until-baseline-measured.md) — prove the model before tuning

### 8. Inference, Filters and Re-ranking (MEDIUM-HIGH)

- [`infer-use-filters-api`](references/infer-use-filters-api.md) — Personalize backfills to numResults
- [`infer-rerank-rules-after-model`](references/infer-rerank-rules-after-model.md) — preserve the model distribution
- [`infer-deduplicate-canonical-entity`](references/infer-deduplicate-canonical-entity.md) — provider-level dedup, not listing-level
- [`infer-enforce-exposure-caps`](references/infer-enforce-exposure-caps.md) — rolling fairness constraints
- [`infer-cache-responses-short-ttl`](references/infer-cache-responses-short-ttl.md) — session continuity and cost control

### 9. Observability and Online Metrics (MEDIUM-HIGH)

- [`obs-always-ab-test`](references/obs