STATE - Practice Recommendation

DomainsDOL EnglishProduct1.891 words9 min read

active

Current truth

After submission, users always see result first. Recommendation logic is now habit-first, dynamic in set size, explainable, and adaptive based on user interaction.

Rules

Post-submit route: result page -> optional move to practice management.
Post-submit source:
- result pipeline accepts both normal submit and timed timeout-submit from attempt flow.
Recommendation baseline:
- priority: habit_first.
- dynamic set size: 3..7.
- default set size: 5.
- low-inventory minimum: 3.
- default mix for 5-item set: 2 habit + 2 target + 1 explore.
- one-line reason label per recommendation item.
- reason policy:
  - exactly one primary reason label per item.
  - priority order:
    - recovery_critical
    - goal_aligned
    - habit_continuity
    - freshness
    - trending_fallback
- confidence policy:
  - each recommendation item has confidence_level = high | medium | low.
  - low-confidence items are capped to max 1 per set when inventory allows.
  - low-confidence item is placed near end of set.
- refresh triggers: on_submit and manual_refresh.
- if user ignores recommendations 3 consecutive times, change recommendation strategy.
- ignore definition:
  - no click,
  - click then leave without submission.
- ignore evaluation timing: end-of-session (30m idle or explicit exit).
- adaptation order after ignore threshold:
  - difficulty -> format -> skill.
- feedback model: like/dislike at cluster level.
- cluster dislike persists to next clusters.
- feedback interaction does not reset ignore streak.
- dislike + leave without attempt still increments ignore by 1.
- repetition cap: maximum 3 items from same skill in one set.
- topic repetition cap: maximum 2 items from same topic in one set.
- freshness quota:
  - each set includes at least 1 freshness item when inventory allows.
  - freshness item means:
    - not attempted in last 14 days, or
    - same skill with different format from recent attempts.
- manual-refresh intent adaptation:
  - if user manual-refreshes 2 consecutive times without click/attempt,
  - next set must include at least 1 alternative-skill item.
- if freshness/repetition guardrails cannot be satisfied due to low inventory:
  - relax via nearest-ladder fallback with short notice.
- entitlement-aware composition:
  - prioritize available-now items that user can start immediately under current entitlement.
  - cap locked teaser to maximum 1 item per set when available inventory is sufficient.
  - locked teaser appears at end of set with explicit lock reason and minimum eligible plan badge.
  - when available inventory is low:
    - relax nearest-ladder in same program/assessment-form/skill first,
    - only then allow extra locked items with shortage notice.
- quick manual controls available: skill, difficulty, duration.
- manual-control preference TTL: session only.
- manual-control behavior:
  - soft-priority ranking (not hard strict by default),
  - no-match uses nearest-ladder relaxation + short notice,
  - control scope persists across pages in current session.
Recommendation mix:
- weak result -> easier corresponding item,
- good result -> equivalent + harder item,
- within each bucket keep nearest relevance order (result-matched -> same-topic -> different-skill),
- allow skill-switch options.
Goal-aware fallback when comparison is incompatible/low-confidence:
- if goal_comparison_mode = not_comparable or comparable sample gate fails,
- prioritize recommendation in same canonical assessment_form_id,
- prefer same-skill items first when inventory allows.
Cold-start policy:
- when user has no goal and no history: use trending content from recent 14 days with easy-start bias.
Reactivation-entry handoff:
- if user enters via reactivation notification click, apply one-time seed boost for first recommendation set in session.
- payload keys:
  - reactivation_intent_stage,
  - optional seed_program_id,
  - optional seed_skill_id.
- one-time seed rules:
  - include at least one quick-win aligned item when inventory allows.
  - seeded quick-win must be available-now.
  - seeded quick-win should prefer confidence high | medium.
  - for inactive_1m | inactive_1y | inactive_q3_repeat, also include one trending-new item in program when possible.
- seed boost expires at first attempt-start or session end.
- low inventory fallback: trending_14d + easy_start_bias.
Inventory fallback:
- use nearest-match fallback ladder before broad fallback.
- keep program and skill relevance first.
Repeated suggestion blocking:
- no same-exercise suggestion within 7 days.
Async scoring pending state:
- do not use score before score is ready,
- use level + topic + recent skill intent.
- score-ready notification:
  - notification center is mandatory,
  - optional toast/push is one-shot when user enables channels.
Vocabulary handoff governor:
- valid vocab_suggestion_payload syncs into vocabulary intake lane with dedupe.
- vocabulary Today Focus is capped to 20 items/day surface with 5-item quick-start subset.
- if vocabulary due backlog exceeds 40, new intake is parked in inbox and paused from Today Focus.
- when backlog returns to <=30, intake resumes to Today Focus by priority order.
- unfinished Today Focus has no penalty; next-day rebuild is non-punitive.
Rescue-pack delivery for decline state:
- show 3-bai cuu nhip immediately when decline is detected,
- keep the same pack available in Practice Management.
Rescue-pack composition:
- 1 fixed warm-up exercise,
- 2 personalized exercises.
- rescue items should prefer confidence high | medium; low-confidence allowed only when inventory is limited.
Rescue-pack control:
- user can skip,
- no forced gate.
Rescue-pack re-prompt:
- only when a new decline signal is detected.
Immediate rescue prompt cooldown:
- 7 days between immediate prompts.
During cooldown:
- if decline is detected again, still do not show immediate prompt.
Immediate surface style:
- non-blocking inline card/panel (no blocking modal by default).
Cooldown reset:
- resets when learner completes at least one similar exercise,
- completion does not need to be exactly one of rescue-pack items.
Similar-exercise matching ladder:
- Tier A: same program + same skill + same exercise type + difficulty delta <= 1,
- Tier B: same program + same skill,
- Tier C: same skill,
- engine fallback order: A -> B -> C.
Tier-C guardrails:
- allow tier C only when A/B inventory is below minimum threshold,
- block cross-program fallback even when skill matches.
Recovery quality conditions:
- use practice time and completion ratio per exercise as soft thresholds,
- avoid rigid per-item hard gates by raw time or per-item question count.
Threshold model simplicity:
- practice-time threshold is configured by skill,
- completion-ratio threshold is configured by exercise family (objective vs subjective),
- no per-program/per-level branching in core rule at this stage.
Numeric defaults (V2 baseline):
- practice-time thresholds:
  - Reading: 8 minutes,
  - Listening: 8 minutes,
  - Writing: 12 minutes,
  - Speaking: 12 minutes.
- completion-ratio thresholds:
  - objective: >= 70%,
  - subjective: >= 60%.
- tier-C fallback cutoff:
  - allow only when combined A+B inventory < 3.
Reset evaluation timing:
- evaluate only after result is available,
- async-scored exercises wait for scoring completion.
Transparency:
- show concise user-facing checklist for reset conditions.
Threshold review cadence:
- freeze defaults for first 3 months,
- then review monthly.
Recovery visibility and escalation:
- show provisional recovery status after qualifying result and confirm weekly,
- if no recovery across 2 consecutive cycles, offer AI Tutor personalized 7-day plan.
AI Tutor plan details:
- plan structure: 1 required + 1 optional exercise per day,
- plan regeneration: only after 7-day cycle if high-attention remains active,
- high-attention exits after one official weekly recovery confirmation,
- only one active AI Tutor plan is allowed per account.
AI Tutor plan candidate policy:
- required slot prioritizes weakest skill in current program,
- if inventory is low, reuse fallback ladder A -> B -> C inside current program,
- if user changes program mid-cycle, keep current plan to cycle end and regenerate next cycle by new program,
- if today’s required item is unavailable, auto-replace via A -> B -> C and show short notice.
AI Tutor daily execution policy:
- if user misses a day, do not carry missed required to next day,
- required daily completion is counted on required-exercise submission,
- daily required day attribution uses submit timestamp,
- optional is bonus-only and does not replace required completion,
- optional does not affect high-attention exit condition.
AI Tutor daily reminder policy:
- for required item reminders, use in-app + one web push,
- reminders are scheduled at one fixed daily local-time slot,
- stop same-day reminders once required item is completed.
AI Tutor reminder edge behavior:
- if web push is disabled/unavailable, keep in-app reminder only,
- daily required reminder cap is one reminder/day (no same-day retry),
- if user is not logged in at reminder slot, do not send catch-up reminder later the same day,
- on next login, show current-day required not-completed state only.
AI Tutor reminder consistency behavior:
- day boundary for daily required state is 00:00 at user local timezone,
- if timezone changes, new reminder timezone applies from next day only,
- reminder slot performs required-completion precheck and skips send if already completed,
- reminder eligibility is account-level; completion on one device stops same-day reminder across all devices.
AI Tutor reminder deep-link behavior:
- reminder click opens Practice Management,
- today’s required item is highlighted for direct action.
Async-scored skill rule:
- for Writing/Speaking, cooldown reset applies only after scoring completed.
Course/subscription scope refinement:
- context-bound entitlement is default between course and self-study.
- same-item exception applies for items touched in course context.
- course learner AI usage in course scope can run on course credit without requiring Pro Max.
- course-scope top-up stays course-scope when subscription entitlement is absent.
- Free/Pro Writing-Speaking in self-study keep basic-score visibility; advanced AI detail remains lock-state unless entitlement supports advanced AI.
- reopen of same scored result does not re-consume AI credit (charge-once per scoring job).
- system AI-scoring failure after charge triggers auto-refund.
- if entitlement/credit drops during attempt, submission is still allowed and lock applies at result sections only.
- in result context, tapping locked AI feature opens upgrade popup on every tap (no per-screen suppression).
- locked AI upgrade keeps user in current result context (in-context quick popup by default); pricing page is optional detail route.
- if popup shows both Pro and Pro Max, default preselect is minimum eligible package; user can change before confirm.
- locked-popup reopen cooldown is 1..2s to prevent spam-loop.
- when downgrade keeps remaining credit but blocks usage, show explicit lock-state messaging in Result and Billing/Subscription surfaces.
Objective scoring normalization:
- unanswered objective items count as wrong,
- scaled-test scores normalize to percentage by test max before band mapping.
Reset scope:
- cooldown reset is scoped by skill within program.
Recovery chain:
- one qualifying similar exercise is enough to reset cooldown.

Decision trace

DEC-0003
DEC-0016
DEC-0017
DEC-0018
DEC-0019
DEC-0020
DEC-0021
DEC-0022
DEC-0023
DEC-0024
DEC-0025
DEC-0026
DEC-0027
DEC-0028
DEC-0029
DEC-0030
DEC-0031
DEC-0042
DEC-0045
DEC-0046
DEC-0048
DEC-0051
DEC-0052
DEC-0058
DEC-0060
DEC-0061
DEC-0062
DEC-0067
DEC-0072
DEC-0073
DEC-0068
DEC-0070
DEC-0075
DEC-0076
DEC-0077
DEC-0078