Recommendation confidence and primary-reason priority policy

DEC-0078 - Recommendation confidence and primary-reason priority policy

Context

Recommendation reason labels exist, but confidence signaling and reason precedence are not fully deterministic. This can make recommendation feel inconsistent across sessions.

Decision

Add a deterministic confidence + explanation layer:

• Confidence levels:
  • high, medium, low.
• Confidence baseline rules:
  • high: strong contextual match and availability-now,
  • medium: partial match with controlled fallback,
  • low: broad fallback/trending with weak context fit.
• Reason label policy:
  • show exactly 1 primary reason per item.
  • reason priority order:
    1. recovery_critical,
    2. goal_aligned,
    3. habit_continuity,
    4. freshness,
    5. trending_fallback.
• Low-confidence guardrail:
  • max 1 low-confidence item per set when inventory is sufficient,
  • low-confidence item should be placed near end of set.
• Seed/rescue integrity:
  • reactivation seed and rescue-pack suggestions should prefer high/medium confidence,
  • if only low-confidence options exist, fallback is allowed with short notice.

Decision Value

• Increases trust in recommendation explanation.
• Keeps ranking deterministic and debuggable.
• Improves consistency without introducing heavy ML complexity.

Rationale

User acceptance depends on understandable reasons and stable behavior. A simple confidence layer is enough to align UX clarity with engine logic.

Implications

• Product/UX impact:
  • clearer “why this item” communication and less perceived randomness.
• Data/logic impact:
  • recommendation payload includes confidence_level and primary_reason_code.
• Operational impact:
  • no extra operations process; fully rule-based.

Alternatives considered

• Option A: keep reason labels without confidence tiering.
• Option B: expose multi-reason stack per item (higher complexity).

Open follow-ups

• No blocker for baseline lock.