Recommendation interaction, adaptation, and control contract

DEC-0045 - Recommendation interaction, adaptation, and control contract

Context

DEC-0042 locked habit-first baseline, but runtime interaction semantics (ignore, feedback, adaptation order, and control behavior) remained under-defined.

Decision

Recommendation execution is finalized as:

• Ignore definition includes:
  • no click, and
  • click then leave without a submission.
• Ignore streak is evaluated at end-of-session (30m idle or explicit session exit).
• If ignore streak threshold is hit, adaptation order is:
  • difficulty -> format -> skill.
• Feedback model is like/dislike at recommendation-cluster level.
• Cluster dislike persists for next clusters.
• Feedback interaction does not reset ignore streak.
• Dislike + leave without attempt still increments ignore by 1.
• Default recommendation count: 5.
• Low-inventory behavior: shrink to minimum 3.
• Default structure for 5 items:
  • 2 habit,
  • 2 target,
  • 1 explore.
• Manual controls (skill, difficulty, duration):
  • soft-priority ranking (not hard strict filter by default),
  • no-match uses nearest-ladder relaxation with short notice,
  • scope persists across pages in same session.

Decision Value

• Makes recommendation behavior predictable for users and measurable for product.
• Prevents silent ambiguity around ignore/feedback signals.
• Preserves personalization quality while avoiding empty-state dead ends.

Rationale

Behavioral adaptation should be transparent and lightweight. This contract keeps logic simple enough to scale while retaining enough signal fidelity to improve relevance.