VOCV2 Learn Question Rules

DomainsDOL EnglishUX2.022 words10 min read

active

1) Mục tiêu

Tài liệu này mô tả cách hệ thống chọn câu hỏi trong flow LEARN ở mức product logic, để team hiểu cách vận hành thống nhất.

Tài liệu này không đi vào chi tiết implementation như remote config keys, event logging schema, scoring tuning chi tiết.

2) Phân vai với tài liệu Exercise Types

File này: định nghĩa logic chọn bucket (độ khó + skill) cho mỗi lượt hiển thị.
VOCV2_Exercise_Types.md: định nghĩa catalog dạng bài và tag của từng dạng bài.

3) Nguyên tắc lõi

Difficulty đi theo level thành thạo của từ (max_stage 0-5).
Skill đi theo profile skill (PRIMARY/ADJACENT/CROSS).
Difficulty và Skill là 2 nhánh độc lập, chỉ liên hệ gián tiếp qua candidate pool.
Có repair override để cứu user khi fail, tránh sốc độ khó.

Bốn nguyên tắc vận hành lõi của động cơ LEARN (../Assets/Images/Question selection/logic core question.jpg)

3.1) Thuật ngữ nhanh (đọc trước khi áp rule)

tier: mức độ ưu tiên của item trong Priority Queue.
- Hiểu nhanh: Tier 1 là ưu tiên cao nhất (cần cứu ngay), Tier 8 là ưu tiên thấp nhất (vừa mới gặp, tránh lặp lại quá sát).
- Tier 1/2 thường được gọi là nhóm urgent.
touch: số lần item xuất hiện trong LEARN kể từ khi bắt đầu học item đó trong session/chu kỳ hiện tại.
- touch 1: lần gặp đầu (Learning Card).
- touch 2-4: lượt xuất hiện #2 đến #4 của cùng item.
- Ví dụ: từ ubiquitous vừa vào phiên -> xem card = touch 1; câu hỏi kế tiếp về chính từ đó = touch 2.
fail streak: số lần sai liên tiếp của cùng item trong cùng session.
Tier 1/2: nhóm item urgent theo Priority Queue (cần cứu trước).
level thành thạo: max_stage 0-5 của item (Seed -> Flowering), dùng để chọn tỷ lệ difficulty.
F_now: độ nhớ hiện tại tại thời điểm hỏi; dùng cho repair/urgent logic.

Từ điển thuật ngữ kỹ thuật của hệ thống (../Assets/Images/Question selection/system term.jpg)

4) Level thành thạo và Difficulty

Level thành thạo của mỗi từ là max_stage:

0 Seed, 1 Sprout, 2 Seedling, 3 Sapling, 4 Mature, 5 Flowering.
max_stage chỉ tăng theo tiến bộ, không downgrade theo F_now.

Target difficulty theo level:

Level	EASY	MEDIUM	HARD
0 Seed	100%	0%	0%
1 Sprout	90%	10%	0%
2 Seedling	75%	25%	0%
3 Sapling	45%	40%	15%
4 Mature	25%	45%	30%
5 Flowering	15%	35%	50%

Biểu đồ phân bổ độ khó theo Max Stage 0–5 (../Assets/Images/Question selection/max stage distrubute.jpg)

Repair override:

Nếu failCount >= 1 hoặc F_now = 0 thì force EASY trong 2 touches kế tiếp.
Hết 2 touches quay về ratio theo level.

Cơ chế Repair Override – Phanh khẩn cấp (../Assets/Images/Question selection/prepair override.jpg)

5) Skill profile và tỉ lệ gợi ý

Định nghĩa:

PRIMARY: đúng skill gốc của từ (item.skill).
ADJACENT: skill liền kề hỗ trợ trực tiếp.
CROSS: skill còn lại.

Skill profile:

Profile	PRIMARY	ADJACENT	CROSS	Khi dùng
CORE	75%	20%	5%	Mặc định
NEW_RAMP	90%	10%	0%	Từ mới (lượt #2-#4)
URGENT_REPAIR	95%	5%	0%	Tier 1/2 hoặc fail streak
MASTERY_EXPAND	60%	25%	15%	Từ đã rất chắc (mở rộng)

Điều kiện kích hoạt chi tiết:

URGENT_REPAIR: bật nếu Tier in {1,2} hoặc fail streak >= 2.
NEW_RAMP: bật nếu item đang ở giai đoạn mới và touch in [2..4].
MASTERY_EXPAND: bật nếu item rất chắc, đề xuất dùng điều kiện: successCount >= 5 AND failCount < 1 AND F_now >= Threshold(skill) + 10.
CORE: dùng khi không rơi vào 3 điều kiện trên.

Thứ tự ưu tiên khi nhiều điều kiện cùng đúng:

URGENT_REPAIR
NEW_RAMP
MASTERY_EXPAND
CORE

4 Profile định tuyến kỹ năng học tập (../Assets/Images/Question selection/vocab profile.jpg)

Ý nghĩa ngắn gọn:

CORE: học mặc định, giữ trọng tâm skill chính + một phần nhỏ liên-skill.
NEW_RAMP: onboarding từ mới, giữ trải nghiệm dễ và đúng mục tiêu skill.
URGENT_REPAIR: chế độ cứu, giảm sốc và phục hồi item đang yếu.
MASTERY_EXPAND: mở rộng linh hoạt khi item đã vững.

Ràng buộc catalog hiện tại (quan trọng):

Writing: hiện chỉ có bài HARD.
Reading: có nhiều bài EASY nhất.
Speaking/Listening: có cả EASY và MEDIUM.

Coverage map theo catalog hiện tại:

Skill	EASY	MEDIUM	HARD
Reading	Nhiều	Có	Có (ít hơn)
Listening	Có	Có	Có (ít hơn)
Speaking	Có	Có	Có
Writing	Không có	Không có	Có

Hệ quả vận hành:

Với item skill=Writing ở level thấp (0-2), engine sẽ dùng Reading/Speaking/Listening (adjacent/cross) để vào nhịp.
Khi lên level cao hơn (3+), engine tăng dần tỷ lệ Writing HARD để luyện đúng mục tiêu viết.

Skill adjacency map:

Item Skill	Primary	Adjacent	Cross
Speaking	Speaking	Listening, Reading	Writing
Listening	Listening	Speaking, Reading	Writing
Reading	Reading	Writing, Listening	Speaking
Writing	Writing	Reading, Listening	Speaking

6) Availability Guarantee (không dead-end)

Mục tiêu: mỗi lượt LEARN luôn chọn được câu hỏi phù hợp, không bị kẹt vì catalog thiếu bucket.

Ladder fallback (theo thứ tự):

PRIMARY + target difficulty
ADJACENT + target difficulty
CROSS + target difficulty
PRIMARY/ADJACENT + difficulty gần nhất an toàn
Learning Card / bài nhận biết an toàn

Đảm bảo Khả dụng – Ladder Fallback 5 bước (../Assets/Images/Question selection/Ladder fallback.jpg)

Rule đặc biệt cho item skill=Writing:

Level 0-1: không ép Writing HARD.
Level 2: cho xuất hiện Writing HARD rất ít để làm cầu nối.
Level 3+: tăng dần tỷ lệ Writing HARD theo level.

Quota tối thiểu Primary theo cửa sổ 10 lượt (để không lệch skill):

Item skill	L0-1	L2	L3	L4	L5
Reading (PRIMARY=Reading)	7	7	6	6	5
Listening (PRIMARY=Listening)	6	6	6	6	5
Speaking (PRIMARY=Speaking)	6	6	6	6	5
Writing (PRIMARY=Writing HARD)	0	1	3	5	7

Hạn mức kỹ năng tối thiểu theo cửa sổ 10 lượt học (../Assets/Images/Question selection/Flor easy hard.jpg)

Ghi chú:

Đây là floor bảo vệ chất lượng, không thay thế skill profile.
Nếu profile yêu cầu PRIMARY cao hơn floor thì vẫn ưu tiên theo profile.

7) New item ramp (onboarding từ mới)

Touch	Rule
1	Learning Card
2	Quick Check EASY + profile `NEW_RAMP`
3-4	Difficulty theo Level 1 (90/10/0) + profile `NEW_RAMP`
>=5	Difficulty theo `max_stage` + profile phù hợp

Lộ trình Onboarding một từ vựng mới – New Item Ramp (../Assets/Images/Question selection/Item ramp.jpg)

8) Luồng chọn câu hỏi (idea flow)

Lấy item từ queue của session.
Chọn target difficulty theo max_stage.
Nếu đang ở repair override thì chỉ giữ EASY.
Chọn target skill theo profile hiện tại.
Lấy exercise cụ thể từ catalog (xem VOCV2_Exercise_Types.md) theo bucket còn thiếu + có variety.
Nếu bucket đang chọn không có bài khả dụng thì chạy Availability Ladder (mục 6).
Nếu vẫn thiếu thì fallback sang dạng bài an toàn hơn.

Luồng Quyết định Chọn Câu hỏi – Idea Flow (../Assets/Images/Question selection/Idea Flow.jpg)

9) Guardrails tối thiểu

Fail streak >= 2: force EASY + profile URGENT_REPAIR trong 2 touches.
Tier 1/2: giới hạn CROSS rất thấp, ưu tiên PRIMARY/ADJACENT.
Không trừng phạt bằng cách tăng khó ngay sau fail.
Writing safeguard (phù hợp catalog hiện tại):
- Level 0-2: không ép Writing HARD liên tục; ưu tiên Reading/S/L EASY-MEDIUM để xây nền.
- Level 3+: tăng dần tần suất Writing HARD để đảm bảo vẫn luyện đúng skill viết.

Hàng rào Bảo vệ Trải nghiệm – System Guardrails (../Assets/Images/Question selection/System Gruardrails.jpg)

10) Card Practice ngoài LEARN

Mỗi thẻ từ có 3 action riêng:

Practice Speaking: map vào bài Speaking EASY.
Practice Writing: map vào bài Writing HARD.
Practice Matching (trò chơi ghép thẻ): mỗi lần ghép đúng 1 thẻ/pair được tính tương đương hoàn thành Reading EASY.

Nguyên tắc điểm:

Dùng cùng cơ chế điểm hiện có như flow LEARN.
Nếu lượt luyện được tính credit thì điểm thành thạo tăng/giảm theo rule hiện có của bài đó.

Gate chống cày (rule 2 + 3) áp dụng cho Practice Speaking và Practice Writing:

Mỗi từ chỉ có 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 trên cùng từ: vẫn cho luyện nhưng không cộng điểm thành thạo.
Muốn mở lại cộng điểm cho từ đó: user phải hoàn thành 3 lượt có credit ở các từ khác (itemId khác từ đang bị khóa).

Riêng Practice Matching:

Không áp dụng gate chống cày 2 + 3.
Lý do sản phẩm: mỗi bài ghép thẻ được làm mới liên tục, không lặp nguyên trạng.

Thông báo khi bị chặn credit:

“Bạn đã nhận điểm 2 lượt liên tiếp cho từ này. Hãy luyện 3 từ khác để mở lại cộng điểm.”

11) Kỳ vọng hành vi

Từ level thấp: EASY xuất hiện nhiều hơn MEDIUM/HARD.
Từ level cao: MEDIUM/HARD tăng dần, EASY giảm.
Từ skill Reading: PRIMARY (Reading) xuất hiện nhiều hơn Writing/Listening/Speaking.
Khi user sai liên tiếp: hệ thống tự hạ difficulty để cứu nhịp học.
Từ skill Writing ở level thấp vẫn học được bằng lớp đệm Reading/S/L; lên level cao mới tăng Writing HARD.
Mỗi lượt đều có đường chọn hợp lệ nhờ ladder fallback, không bị dead-end vì thiếu exercise bucket.
Card Practice Speaking/Writing có gate chống cày; Practice Matching không chặn theo gate 2 + 3.

Kỳ vọng Hành vi của Hệ thống (../Assets/Images/Question selection/Question Summary.jpg)

12) References

13) Change Log

2026-03-02: Rút gọn thành bản concept-first, bỏ phần kỹ thuật triển khai chi tiết.
2026-03-02: Bổ sung Availability Guarantee + quota Primary theo skill/level để luôn có câu hỏi phù hợp.
2026-03-03: Bổ sung contract Practice Speaking / Practice Writing ngoài LEARN và gate chống cày 2 + 3.
2026-03-04: Bổ sung Practice Matching (mỗi ghép đúng = Reading EASY) và ngoại lệ không áp dụng gate 2 + 3.