VOCV2 Product Spec Hardening v1.0

1. Purpose

Tài liệu này là Source of Truth (SoT) cho các rule vận hành Vocab V2 trong giai đoạn hardening.

Mục tiêu:

• Chuẩn hóa logic để Engineering/QA/Content triển khai nhất quán.
• Loại bỏ các mâu thuẫn giữa các tài liệu cũ (batching, mixing, tier, difficulty, time-unit).
• Thêm guardrails để giảm burnout, doom loop, và lỗi vận hành content.

2. Scope

Trong scope:

• Session lifecycle, queue/tier logic, mixing, exercise selection, guardrails, cryo comeback, recap loop.
• Remote config contract và acceptance criteria.

Ngoài scope:

• Không thay đổi prototype HTML.
• Không thay đổi định hướng nền tảng (Lobby/Gym, SRS F/D, next_review_at).
• Không mở rộng sang gamification/leaderboard.

3. Source-of-Truth Rule

Nếu tài liệu khác mâu thuẫn với tài liệu này, ưu tiên tài liệu này.

4. Core Data Contracts

4.1 ItemLearner (per user x item)

Trường cốt lõi:

• itemId, userId, skill
• F, D, successCount, failCount
• lastReviewedAt, next_review_at
• max_stage, F_peak

4.2 Unified Units

• F trong [0,100].
• D dùng đơn vị fluency per minute.
• Δt dùng phút.
• K mặc định 2400 phút.

4.3 Threshold by skill

• Speaking: 80
• Writing: 75
• Reading: 70
• Listening: 70 (nếu áp dụng)

5. Remote Config Contract

Group	Key	Default	Note
Session	MICRO_BATCH_SIZE	5	Selection logic luôn chạy theo batch 5
Buffer	INITIAL_BUFFER_WEB	10	Web preload 2 micro-batches
Buffer	INITIAL_BUFFER_MOBILE	5	Mobile preload 1 micro-batch
Prefetch	PREFETCH_AT_PROGRESS	0.6	Prefetch tại item 3/5
Mixing	NEW_RATIO_TARGET	0.30	Stable target
Debt	NEW_BLOCK_DEBT_THRESHOLD	20	Nợ cao thì chặn từ mới
Guardrail	MAX_RETRY_PER_ITEM_PER_SESSION	3	Mercy rule
Guardrail	URGENT_SOFT_OVERRIDE_RATIO	0.5	>50% tier1 thì oxygen rule
Cryo	CRYO_INACTIVITY_DAYS	30	Kích hoạt cryo
SRS	penaltyFail	0.20	Phạt fail mặc định
Maintenance	MAINTENANCE_INTAKE_CAP	0.05	Tier7 tối đa 5%
Learn Ratio	DIFF_RATIO_WINDOW_SIZE	20	Window theo dõi ratio difficulty
Learn Ratio	SKILL_RATIO_WINDOW_SIZE	20	Window theo dõi ratio skill
Learn Ratio	RATIO_DEVIATION_TOLERANCE	0.10	Độ lệch cho phép (+/-10pp)
Learn Ratio	MAX_MISMATCH_URGENT_RATIO	0.10	Tier1/2 giới hạn cross-skill
Learn Ratio	FORCE_EASY_AFTER_FAIL_STREAK	2	Fail streak kích hoạt override
Learn Ratio	FORCE_EASY_DURATION_TOUCHES	2	Số touch bị force sau fail streak
Learn Ratio	DIFF_TARGET_LEVEL_0	1.00,0.00,0.00	EASY,MEDIUM,HARD
Learn Ratio	DIFF_TARGET_LEVEL_1	0.90,0.10,0.00	EASY,MEDIUM,HARD
Learn Ratio	DIFF_TARGET_LEVEL_2	0.75,0.25,0.00	EASY,MEDIUM,HARD
Learn Ratio	DIFF_TARGET_LEVEL_3	0.45,0.40,0.15	EASY,MEDIUM,HARD
Learn Ratio	DIFF_TARGET_LEVEL_4	0.25,0.45,0.30	EASY,MEDIUM,HARD
Learn Ratio	DIFF_TARGET_LEVEL_5	0.15,0.35,0.50	EASY,MEDIUM,HARD
Learn Ratio	SKILL_PROFILE_CORE	0.75,0.20,0.05	PRIMARY,ADJACENT,CROSS
Learn Ratio	SKILL_PROFILE_NEW_RAMP	0.90,0.10,0.00	PRIMARY,ADJACENT,CROSS
Learn Ratio	SKILL_PROFILE_URGENT_REPAIR	0.95,0.05,0.00	PRIMARY,ADJACENT,CROSS
Learn Ratio	SKILL_PROFILE_MASTERY_EXPAND	0.60,0.25,0.15	PRIMARY,ADJACENT,CROSS

6. Priority Queue Contract (8 tiers, float-safe)

Tier #1 Critical Urgent

• Điều kiện: failCount >= 3.0 AND F_now <= Threshold(skill)
• Hành động: ưu tiên cao nhất + remedial sequence.

Tier #2 Urgent

• Điều kiện: 1.0 <= failCount < 3.0 AND F_now <= Threshold(skill)

Tier #3 Normal Review

• Điều kiện: failCount < 1.0 AND F_now <= Threshold(skill)

Tier #4 New Items

• Điều kiện: unseen (chưa có ItemLearner record)
• Lưu ý: không dùng F=0 để định nghĩa New.

Tier #5 Reinforce Low

• Điều kiện: successCount < 3.0 AND F_now >= Threshold(skill)

Tier #6 Reinforce High

• Điều kiện: successCount >= 3.0 AND F_now >= Threshold(skill)

Tier #7 Mastery

• Điều kiện: successCount >= 5.0 AND F_now >= MasteryThreshold(skill)
• Mastery threshold mặc định: Threshold + 10.

Tier #8 Just Seen

• Điều kiện: item vừa xuất hiện ở lượt trước.
• Mục đích: tránh lặp gần, trừ retry buffer hoặc tier #1.

Tie-break bắt buộc

1. F_now thấp hơn đi trước.
2. Skill rotation (ưu tiên đổi skill khi cùng tier).
3. Có thể ưu tiên coherence theo mental model nếu không tăng rủi ro nợ urgent.

7. Session Lifecycle Contract

7.1 Initialization

1. Cryo check (days_since_last_active > CRYO_INACTIVITY_DAYS).
2. Tính trạng thái realtime:
   • F_now = max(0, F - D*Δt) khi cần.
   • Có thể query due bằng next_review_at <= now.
3. Init buffer:
   • Web preload 10, Mobile preload 5.
   • Selection vẫn theo micro-batch 5.
   • Micro-batch 5 là planning window, không phải checklist 5 item cố định.
4. Timer default 10 phút (timed), cho phép untimed.
   • Timed: timer về 0 thì hoàn thành item hiện tại, không nạp batch mới.
   • Untimed: tiếp tục theo queue cuốn chiếu cho đến khi user dừng; nếu pool chính cạn có thể chuyển sang Deep Review.

7.2 Loop

1. Pick Next Item:
   • Ưu tiên RetryBuffer, sau đó tier 1->7, hạn chế tier8.
2. Presentation:
   • Tier1-2: bắt buộc Learning Card -> Active Exercise.
   • Tier4 (new): Learning Card + Quick Check EASY trong <=2 lượt kế.
3. Exercise selection:
   • Difficulty filter (level-first) -> Skill Controller (độc lập) -> Final Selection.
4. Update:
   • Cập nhật F, D, successCount, failCount, lastReviewedAt.
   • Tính và lưu next_review_at.
5. Reinsertion:
   • Fail: vào retry buffer, hỏi lại sau 1-2 item.
6. Prefetch:
   • Trigger tại progress 3/5.
   • Batch kế tiếp luôn được sinh từ trạng thái mới nhất của queue sau các lượt vừa xảy ra.
7. End:
   • Timer=0: hoàn thành item hiện tại, không nạp batch mới.

8. Mixing Contract (single truth)

8.1 Debt definitions

• debt_total = count(tier in {1,2,3})
• debt_critical = count(tier=1)

8.2 States

State A - Hard Debt

• Điều kiện: debt_total >= NEW_BLOCK_DEBT_THRESHOLD
• Rule: 100% review (không new).

State B - Soft Emergency (oxygen)

• Điều kiện: không ở A, nhưng tier1_share_next_batch > URGENT_SOFT_OVERRIDE_RATIO
• Rule: batch 5 = 4 review + 1 new.
• Nếu hết new: slot new chuyển reinforce low.

State C - Stable

• Điều kiện: không thuộc A/B.
• Target: 30% new / 70% review.
• Biểu diễn với batch=5 bằng mix cycle 10 items:
  • Batch odd: 3 review + 2 new
  • Batch even: 4 review + 1 new

8.3 Review slot fill order

Tier1 -> Tier2 -> Tier3 -> Tier5, cùng tier thì F thấp trước.

9. Exercise Selection Contract

9.1 Difficulty Controller (Level-first)

• Difficulty target đi thẳng theo max_stage:
  • Level 0: 100/0/0
  • Level 1: 90/10/0
  • Level 2: 75/25/0
  • Level 3: 45/40/15
  • Level 4: 25/45/30
  • Level 5: 15/35/50
• Safety override tối thiểu:
  • Nếu failCount >= 1 OR F_now = 0 -> force EASY trong 2 touches (repair mode).

9.2 Skill Boost

Trong candidate set:

• Base 1.0
• Skill match bonus +2.0
• Variety bonus +0.5 nếu chưa dùng trong 3 lượt gần nhất

9.3 Writing Catalog Constraint (HARD-only)

Catalog hiện tại:

• Writing chỉ có bài HARD (typing full, dictation).

Quy tắc vận hành:

• Level 0-2 hoặc repair mode: ưu tiên Reading/Speaking/Listening EASY/MEDIUM làm lớp đệm để user vào nhịp.
• Level 3+: tăng dần tần suất Writing HARD để quay về đúng mục tiêu skill viết.
• Mapping f_difficulty vẫn giữ: EASY 0.4, MEDIUM 0.7, HARD 1.0.

9.4 Flexible grading

• Meaning-focused typing: accepted variations có thể chấm đúng.
• Audio dictation: nếu đúng nghĩa nhưng lệch âm thì soft warning/partial, không phạt cực đoan.

9.5 Learn Question Rules (bắt buộc)

• Bổ sung contract định lượng cho tỷ lệ hiển thị exercise theo Difficulty + Skill trong LEARN flow.
• Quy tắc kiến trúc:
  • Difficulty Controller và Skill Controller hoạt động độc lập.
  • Skill ratio không phụ thuộc trực tiếp vào độ khó.
  • Hai controller chỉ liên hệ gián tiếp qua candidate pool sau difficulty filter.
• Đồng bộ với level thành thạo:
  • Level thành thạo của mỗi từ là thang 0-5 lưu ở max_stage:
    • 0 Seed, 1 Sprout, 2 Seedling, 3 Sapling, 4 Mature, 5 Flowering.
  • max_stage (từ F_peak/successCount) phản ánh đỉnh đã đạt và không downgrade theo F hiện tại.
  • Difficulty dùng trực tiếp max_stage; F_now/failCount chỉ dùng cho repair override.
• Difficulty target (level-based):
  • L0 100/0/0, L1 90/10/0, L2 75/25/0, L3 45/40/15, L4 25/45/30, L5 15/35/50.
• Skill target (profile-based):
  • Core 75/20/5, New Ramp 90/10/0, Urgent Repair 95/5/0, Mastery Expand 60/25/15.
• Guardrail Writing:
  • Item skill=Writing, level 0-2: không ép liên tục Writing HARD; dùng Reading/Speaking/Listening EASY-MEDIUM làm lớp đệm.
  • Item skill=Writing, level 3+: tăng dần tỷ lệ Writing HARD.
• Availability guarantee:
  • Nếu bucket không có bài khả dụng, fallback theo ladder PRIMARY -> ADJACENT -> CROSS -> difficulty gần nhất an toàn -> Learning Card.
  • Áp dụng primary floor theo cửa sổ 10 lượt (chi tiết ở VOCV2_LEARN_Question_Rules.md) để tránh lệch skill dài hạn.
• Nếu fail streak >=2: force Difficulty=EASY, profile URGENT_REPAIR trong 2 touches.
• Chi tiết glossary state/thuật toán/fallback/telemetry xem:
  • VOCV2_LEARN_Question_Rules.md

9.6 Card Practice Contract (ngoài LEARN)

• Trên từng thẻ từ có 3 action:
  • Practice Speaking -> map Speaking EASY
  • Practice Writing -> map Writing HARD
  • Practice Matching (ghép thẻ) -> mỗi ghép đúng 1 thẻ/pair map tương đương Reading EASY
• Điểm thành thạo dùng cùng cơ chế hiện có của engine (không tách công thức riêng).
• Gate chống cày bắt buộc (rule 2 + 3) cho Practice Speaking/Practice Writing:
  • Mỗi từ chỉ tối đa 2 lượt liên tiếp được tính credit từ Card Practice.
  • Lượt liên tiếp thứ 3 trở đi: vẫn cho luyện nhưng không cộng điểm thành thạo.
  • Mở lại cộng điểm cho từ bị khóa sau khi hoàn thành 3 lượt có credit ở các từ khác.
• Ngoại lệ:
  • Practice Matching không áp dụng gate 2 + 3 vì bài ghép thẻ được làm mới liên tục.
• UX bắt buộc:
  • Hiển thị thông báo khi bị chặn credit để user hiểu lý do và cách mở lại.

9.7 Favorite Signal & Manual Scope Contract

• Yêu thích là personal signal ở cấp item; không phải mastery, không phải urgent review, và không phải hidden.
• favorite=true không làm thay đổi F, D, successCount, failCount, next_review_at, hay thứ tự của global review queue.
• LEARN vẫn giữ một flow duy nhất; không tạo mini learn hoặc flow phụ riêng cho favorite words.
• Session input cho manual scope:
  • scope = current home/set/list
  • favorite_only = true (optional)
• Khi favorite_only=true, candidate pool = scope hiện tại ∩ favorite=true.
• Engine vẫn xếp item trong pool theo tier/level/repair logic hiện hành; user chỉ chọn phạm vi item, không chọn thứ tự item.
• Không auto thêm non-favorite items chỉ để đủ MICRO_BATCH_SIZE.
• Nếu candidate pool nhỏ hơn batch size, batch/buffer/preload phải degrade gracefully theo pool thực tế.
• Candidate pool 1-2 item vẫn hợp lệ:
  • không chặn start,
  • không sinh flow mới,
  • planner tiếp tục dùng exercise rotation bình thường theo stage hiện tại của chính các item đó.
• Nếu favorite pool rỗng, launcher phải disable CTA hoặc fallback rõ về Ôn theo hệ thống.
• Canon chi tiết xem thêm: ../../VOC_Favorite_Words_Review_Contract.md

10. Cryo-Stasis Comeback Contract

• Inactive >30 ngày: freeze logic như cơ chế cũ.
• Bổ sung bắt buộc trong phiên comeback đầu:
  • 50% momentum (new/light)
  • 50% diagnostic review (EASY/MEDIUM trên item cũ)
• Mục tiêu: recalibrate F/D, tránh ảo tưởng mastery.

11. Guardrails (bắt buộc)

1. Mercy rule:
   • Fail cùng item quá 3 lần/session -> đưa cuối queue hoặc index=2 batch kế.
2. Urgent dominance cap:
   • Tier1 >50% batch -> soft emergency 4:1.
3. Fail escalation:
   • Fail 2 lần liên tiếp -> lượt kế bắt buộc Learning Card + EASY.

12. Content Ops Contract

1. CMS flow: AI generate -> human review -> publish.
2. Content completeness theo exercise:
   • Listening/Speaking: cần distractor + audio distractor.
   • Reading/Writing: cần distractor semantic + accepted variations.
3. Fallback bắt buộc:
   • Thiếu dữ liệu thì downgrade sang exercise an toàn.
   • Không generate distractor realtime chưa QA.

13. Recap Contract

• Vẫn giữ no-shame, không ép fail tab mặc định.
• Bắt buộc thêm CTA:
  • “Sửa nhanh 3 từ cần chăm sóc (2 phút)”
  • Mở mini-session Needs Care với EASY/MEDIUM + learning card.
• Nếu save lỗi: hiển thị Retry Save + local cache.

14. Minimum Event & Metrics

14.1 Event

• session_start
• micro_batch_generated
• item_presented
• answer_submitted
• item_updated
• retry_scheduled
• session_end
• recap_cta_clicked

14.2 Metrics

• D1/D7 retention của nhóm debt cao
• urgent dominance rate
• doom loop rate
• skill alignment rate
• completion rate phiên 10 phút
• time-to-recover Needs Care -> Healthy

15. QA Acceptance Checklist

1. Micro-batch selection luôn 5; preload web/mobile không đổi logic selection.
2. Stable mixing dùng cycle 10 items đạt 30% new.
3. debt_total >= 20 thì không có new.
4. Tier float-safe:
   • failCount=0.5 -> tier3 (nếu due)
   • failCount=1.5 -> tier2
   • failCount=3.0 -> tier1
5. Writing level thấp vẫn có EASY/MEDIUM qua lớp đệm Reading/Speaking/Listening; Writing HARD tăng từ level 3+.
6. Không còn ambiguity D/K hoặc ví dụ legacy gây lệch đơn vị.
7. Cryo comeback có diagnostic 50/50.
8. Recap có quick-fix CTA.
9. Thiếu content thì fallback, không crash.

16. Change log

• 2026-02-09: Initial SoT hardening v1.0.