Similar items, cold start, explainable results, A/B tested.
Spec — Recommendations
Status: draft · Created: 2026-11-10
1. Context and goal
Users discover items they are likely to want, with a reason they can understand, and the team proves with experiments that recommendations help.
2. Functional requirements (EARS)
- FR-1: WHEN a user views an item, THE SYSTEM SHALL show up to 10 similar items, excluding the item itself and items out of stock.
- FR-2: THE SYSTEM SHALL return recommendations within 150 ms at the 95th percentile.
- FR-3: WHILE a user has fewer than 5 interactions, THE SYSTEM SHALL recommend popular items from the categories they viewed, or overall bestsellers.
- FR-4: WHEN a new item has no interactions yet, THE SYSTEM SHALL recommend it based on its attributes within 1 hour of publishing.
- FR-5: THE SYSTEM SHALL show with each recommendation a short reason, such as the item it is similar to.
- FR-6: THE SYSTEM SHALL not recommend an item the user bought or dismissed in the last 30 days.
- FR-7: THE SYSTEM SHALL assign users to experiment variants consistently and record impressions and clicks per variant.
- FR-8: WHEN an experiment ends, THE SYSTEM SHALL report click-through and conversion per variant with a 95% confidence interval.
3. Out of scope
- Personalized emails.
- Real-time retraining of models.