Problem statement

The Retailer IQ recommender work spans architecture, a search-enrichment-hosted recommendation-agent capability, live/demo notebooks, and the root executive UI. It should not remain attached to the documentation-review issue because it changes runtime behavior, API surface, tests, and the primary UI experience.

Acceptance criteria checklist

• Define Product IQ, Customer IQ, RecommenderIQ, and Retailer IQ boundaries in the roadmap documentation.
• Implement recommendation-agent capability in search-enrichment-agent with candidate, rank, compose, explain, feedback, and model-status surfaces.
• Expose recommendation-agent REST and MCP entry points without moving experimental logic into shared lib prematurely.
• Add focused Python tests for recommendation candidate generation, ranking, composition, REST, and MCP behavior.
• Add Retailer IQ recommender notebooks for live validation and executive demo storytelling.
• Update the root UI into an executive Retailer IQ cockpit with explicit recommendation proof controls.
• Improve root UI responsiveness by avoiding blocking intro animation, forced snap scrolling, automatic first-load streaming, and eager lower-section API calls.
• Validate TypeScript and focused root page rendering.

Risks and dependencies

• Depends on search-enrichment-agent remaining the host for the recommendation-agent capability until a dedicated service boundary is justified.
• Root UI changes touch first-viewport user experience and must avoid regressing existing drill-down routes.
• The recommendation model is a deterministic/classical baseline and should remain replaceable by future managed model lifecycle work.
• Live notebook endpoints depend on deployed development environment availability.

Evidence links

• docs/roadmap/015-retailer-iq-recommender-system-plan.md
• apps/search-enrichment-agent/src/search_enrichment_agent/recommendations.py
• apps/search-enrichment-agent/src/search_enrichment_agent/recommender_standard.py
• apps/search-enrichment-agent/tests/test_recommendations.py
• apps/ui/components/demo/ExecutiveDemoPage.tsx
• docs/demos/agent-playgrounds/retailer_iq_recommender_system_demo.ipynb
• docs/demos/agent-playgrounds/retailer_iq_recommender_system_live.ipynb

ADR impact

Impacted ADRs: ADR-018 for branch naming and PR traceability. Architecture boundaries may require a follow-up ADR if RecommenderIQ graduates from an app-local capability to a dedicated service or shared library contract. No existing ADR is updated in this save-progress commit.

BPMN process section

%%{init: {'theme':'base', 'themeVariables': {
  'primaryColor':'#FFB3BA',
  'primaryTextColor':'#000',
  'primaryBorderColor':'#FF8B94',
  'lineColor':'#BAE1FF',
  'secondaryColor':'#BAE1FF',
  'tertiaryColor':'#FFFFFF'
}}}%%
flowchart LR
  A[Analyze Current Code] --> B[Design Change]
  B --> C[Implement on Issue Branch]
  C --> D[Open PR]
  D --> E[Validation and Fixes]
  E --> F[Merge to Main]
  F --> G[Monitor Workflows]
  G --> H[Close Issue and Cleanup]