Exercise with AI - Improve a Sentence

Cải thiện một câu (Improve a Sentence)

Purpose

• Vấn đề: Học viên nói được câu cơ bản nhưng không biết nâng cấp bằng kiến thức nào: sửa lỗi, word pattern, idiomatic language, suffixing structure. Ngoài giờ lớp, học viên thiếu một “giáo viên” guide từng bước và bắt luyện nói lại.
• Đối tượng chính: Học viên đã nói được câu đơn giản, cần nâng chất lượng câu theo đúng chương trình Linearthinking.
• Tín hiệu thành công: Học viên tạo được 1 câu gốc, cải thiện câu đó qua các bước phù hợp từ Knowledge Base, nói lại được từng version đã cải thiện, và hiểu vì sao câu mới tốt hơn.

Intent Lock

Improve a Sentence là flow luyện nói dạng hội thoại: AI teacher/narrator dẫn dắt bằng voice và chat, hệ thống đưa ra một chủ đề cho từng round, học viên nói một câu theo chủ đề đó, rồi AI cải thiện câu từng bước theo Linear 7.0S. Sản phẩm phải giữ tối giản: một vùng hội thoại chính, một panel tiến độ cải thiện, và các CTA nói/nghe/lặp lại đúng lúc.

Không biến bài này thành bài chấm điểm tổng quát. Core của dạng bài là micro-improvement trên 1 câu và active production: user phải tự nói câu gốc, tự nói lại câu mẫu, rồi mới được hoàn thành.

Facts / Assumptions / Inferences

Facts

• Knowledge Base hiện dùng cho Improve a Sentence: word patterns, idiomatic language, suffixing structures.
• Overview nhóm Speaking quy định logic cải thiện: sửa lỗi nếu có → word pattern → idiomatic language → suffixing structure, skip step nếu đã đạt.
• Speak a Sentence đã có tiền lệ chọn narrator_language; field này chỉ ảnh hưởng lời dẫn/feedback, không đổi ngôn ngữ câu user cần nói.

Assumptions

• Mỗi round có một assigned_topic được giao sẵn, ví dụ weekend.
• Gợi ý ban đầu chỉ gợi ý câu cơ bản theo assigned_topic, không gợi ý đổi chủ đề.
• Mic check nên reuse theo user_id + exercise_type, giống Linear Tool, để user không phải test lại nhiều lần.

Inferences

• Vì mỗi round có chủ đề được giao, lỗi lạc chủ đề vẫn cần feedback nhẹ nếu câu user không liên quan đến assigned_topic. Các trường hợp cần chặn gồm: không phải câu tiếng Anh, quá ngắn để cải thiện, không nghe được, lạc khỏi chủ đề round, hoặc không nói đúng câu mẫu đang luyện.
• Hệ thống không nên tự xem như hoàn thành khi user nói tiếng Việt/nói khác. Chỉ nên adapt nếu câu user nói khác nhưng vẫn đúng nghĩa và thỏa target knowledge.

Nguồn dữ liệu

• Kho đề/gợi ý: Generate topic cho từng round và câu mẫu cơ bản theo topic đó khi user bí.
• Knowledge base: Linear 7.0S - word patterns, idiomatic language, suffixing structures.
• Speech stack: TTS cho narrator, STT/live transcript cho user, pronunciation/semantic matching cho bước nói lại.
• Demo: https://ias.dol.vn/

Product Model

Field	Mô tả
exercise_type	pra-exai-improve-a-sentence
mic_check_key	Khuyến nghị user_id + exercise_type
mic_check_status	unchecked, passed, skipped, failed
mic_permission_status	unknown, granted, denied
narrator_language	vi hoặc en, dùng cho lời dẫn/feedback/chat của AI teacher
entry_state	mic_check, language_select, opening_prompt, ready_to_speak
conversation_turn	narrator, user, system_analyzing, improvement
spoken_input_state	idle, recording, paused, submitted, analyzing
assigned_topic	Chủ đề bắt buộc của round hiện tại, ví dụ weekend
basic_sentence_suggestion	Câu mẫu cơ bản theo assigned_topic do AI gợi ý khi user bí
user_original_sentence	Câu gốc sau khi STT + user submit
current_sentence	Version mới nhất sau mỗi bước cải thiện thành công
improvement_steps	Danh sách step được chọn từ KB: correction, word_pattern, idiomatic_language, suffixing_structure
current_step_index	Step đang luyện
step_status	pending, explaining, listening, analyzing, passed, retry_needed, skipped
completion_status	not_started, in_progress, target_reached, completed

UI Overview

Khu vực	Nội dung
Top bar	Back, logo, tên bài Improve a sentence, trạng thái mic, menu phụ
Entry	Mic preflight, chọn ngôn ngữ giáo viên (Tiếng Việt / Tiếng Anh)
Main conversation	Bubble của AI teacher và user; narrator nói bằng voice song song với chat bubble
User speaking bubble	Auto mở mic sau khi narrator nói xong; hiển thị transcript live trong bubble của user
Progress panel	Tiến độ cải thiện, câu gốc, các step đã/đang cải thiện, nút nghe lại/giải thích
Bottom controls	Progress dots 1–9 (= 3 sentences × 3 improvement steps), Quay về, Bỏ qua, Tiếp tục khi đạt điều kiện

Ví dụ progress panel

Tiến độ cải thiện

Câu gốc:
"I like to sleep on the weekend"

1. Word pattern
   "I like it when I get to sleep on the weekend"

2. Idiomatic language
   "I like it when I get to sleep on the weekend more than I care to admit"

3. Suffixing structure
   "I like it when I get to sleep on the weekend more than I care to admit even when I am busy"

---

AI Conversation Architecture

Core principle: AI ở Improve a Sentence KHÔNG phải Q&A chatbot. Là giáo viên mentoring dẫn dắt user qua từng bước cải thiện câu. Mỗi turn AI cần rich content + structured visualization + actionable widget, không chỉ plain text. Khác biệt cốt lõi với Speak a Sentence (judge đúng/sai) là: Improve = mentor dạy WHY và HOW.

3 trụ cột song song & integrated

Voice AI (TTS narrator) + Rich text chat (formatted) + Contextual widgets (inline)

Cả 3 layers chạy đồng thời, không sequential. Voice và text bubble cùng xuất hiện 1 lúc; widget là một phần của message trong chat luôn (không separate UI region).

Layer	Vai trò	Đặc điểm
Voice (TTS)	Lời dẫn / câu mẫu / hint chuyển câu	Theo narrator_language. Ngắn, không lặp 100% với text.
Rich text chat	Detail breakdown / lý do cải thiện	Bold cho key terms, bullet cho list, highlight phrase quan trọng. Markdown-style.
Contextual widgets	Action + visualization phù hợp ngữ cảnh	Inline trong chat bubble, không phải separate panel. Composable (nhiều widget trong 1 message).

Phân biệt: Main chat (center) ↔ Progress panel (right)

Khu vực	Vai trò	Lifetime
Main chat (center)	WHY - rationale của mỗi cải thiện. User scroll lại đọc để hiểu kiến thức.	Persistent trong session. Append-only history.
Progress panel (right)	WHAT - versioning timeline của câu qua từng step. Cards click-able để re-explain.	Real-time sync với chat. Mỗi step pass → add card.

Hai khu vực liên kết bidirectional:

• AI introduce improved version trong chat → tự động add card vào panel
• User click record bên panel → scroll chat về moment AI giải thích version đó + flash highlight

Widget catalog (v3 - scope pull-back, 2026-04-28 late session)

Scope clarification: Per user feedback “không cần thiết lắm. Chỉ giữ widget Nói lại câu mẫu + logic + format text trong chat AI”, production scope = minimal:

• ✅ AI bubble với rich text formatting (DS Bubble chat - User + Content/suggestion + Exercise/Text blank variants - bold concept VN, highlight phrase EN qua Type variant)
• ✅ W1 Practice mic (Nói lại câu mẫu) - kept
• ✅ W14 Error widget (Sửa lỗi) - newly designed via DS Type=Red, Case=Highlight Text blank variant
• ❌ W2–W10 (8 widgets dropped from production scope per user feedback). Kept in catalog below as exploration record only. Bring back individually when there’s clear pedagogical evidence one is needed.

Implementation rule: widgets must compose from existing DS components, NOT hand-built primitives. See ai-memory/lessons/dol-ds-text-blank-variants-for-chat-content.md for variant catalog + composition recipe.

Mỗi widget = “AI message với UI riêng” tùy ngữ cảnh. Widget có thể compose - 1 AI turn có thể chứa nhiều widget stacked theo pedagogical order: explain → check → show → practice.

Categorization:

• Proactive widgets (W1-W6): luôn render khi context match, tham gia main flow
• Adaptive widgets (W7, W9, W10, W14): conditional render khi user state hoặc pedagogical moment trigger

ID	Widget	Mode	Trigger context	Purpose	Composes well với
W1	Practice mic (“Nói lại câu mẫu”)	Proactive	Cuối mỗi step practice setup	Active production loop - user phải nói lại câu mẫu mới pass step. Widget có mic input, transcript live, controls Dừng / Nói lại / Xong.	W2, W3, W4
W2	Diff card (trước/sau)	Proactive	Khi AI introduce improved version	Show trước/sau highlighting - phần cũ struck-through, phần mới underlined/highlighted. Visual proof câu được nâng cấp.	W3, W6
W3	Knowledge mini-card	Proactive	Giới thiệu kiến thức mới (word pattern, idiomatic language, suffixing structure)	Definition ngắn + 1-2 ví dụ tham khảo từ KB Linear 7.0S. Có thể expand “Xem thêm ví dụ”.	W2, W4, W7
W4	TTS replay button	Proactive	Sau khi AI nói câu mẫu	Click replay TTS (normal hoặc slow speed). Quan trọng cho luyện phát âm và khi user “Nghe lại”.	W1, W2
W5	Hint pill / suggestion chip	Adaptive	User bí (im quá lâu) hoặc explicit ask gợi ý ở F1	Soft scaffold - 1-2 chip với “Gợi ý câu cơ bản” theo assigned_topic hoặc starter phrase. Click → fill vào input/bubble.	(standalone)
W6	Comparison view	Proactive	Step explanation - giải thích why câu mới hay hơn	Side-by-side card với annotation: “Câu cũ thiếu sắc thái → câu mới có ‘I get to’ = lucky/excited connotation”.	W3
W7	Concept Check Quiz	Adaptive	Sau W3 Knowledge mini-card, TRƯỚC W1 Practice mic. Bridge giữa explain → practice.	Lock comprehension trước active production. 1 question check user hiểu pattern xong rồi mới luyện. Tránh user nhảy vào practice không hiểu pattern → fail không biết tại sao.	W3 (immediately after)
W9	Stuck Rescue / Lifeline	Adaptive	User fail SAME step ≥2 lần liên tiếp (attempt counter trigger)	Adaptive rescue khi user struggle. Cho 4 options: re-explain pattern / slow demo / skip step / retry. Khác W5 Hint pill (W5 = before trying; W9 = recovery sau multiple failures).	Triggers re-render W3/W4 hoặc step skip
W10	Pattern Practice Variation	Adaptive (optional)	Sau user pass W1 step	Reinforce pattern abstraction qua variation. User pass 1 instance = 1 example; W10 = thử pattern với chủ đề khác để generalize. Anti rote-memorization.	Optional after W1 pass; user có thể skip ngay
W14 ✨ production	Error correction (Sửa lỗi)	Adaptive	Khi user output có lỗi rõ (grammar/preposition/vocab/tense)	Bubble với intro + bullet list per error. Phrase sai = Type=Red, Case=Highlight pill (red bg + red text). Phrase đúng = Type=Bold hoặc Type=Green, Case=Highlight. Composes existing DS components (Bubble chat - User + Content/suggestion + Exercise/Text blank variants). Recipe: ai-memory/lessons/dol-ds-text-blank-variants-for-chat-content.md.	(standalone - sau F2 phân tích nếu phát hiện lỗi)

AI message anatomy (2-message pattern explain → check → practice)

Step explanation chia thành 2 messages với W7 concept check ở giữa - tạo natural pause cho user lock comprehension trước practice.

Message 1 - Explain + Check

┌─ AI bubble #1 (explanation) ───────────────────────────┐
│                                                        │
│  Rich text:                                            │
│    "Mình thay **'I like to sleep'** bằng word pattern  │
│     **'I like it when I get to ___'**.                 │
│                                                        │
│     Pattern này giúp câu:                              │
│     • Tự nhiên hơn (native phrasing)                   │
│     • Có sắc thái thích thú (*lucky/excited*)          │
│     • Lead-in tốt cho câu mở rộng"                     │
│                                                        │
│  ┌─ [W3 Knowledge mini-card] ──────────────────┐      │
│  │  Word pattern: "I like it when I get to ___" │      │
│  │  Use: lucky/excited about something          │      │
│  │  Examples:                                   │      │
│  │   • I like it when I get to travel.          │      │
│  │   • I like it when I get to bake.            │      │
│  └──────────────────────────────────────────────┘      │
│                                                        │
│  Voice: "Trước khi luyện, mình hỏi nhanh nhé."         │
│                                                        │
│  ┌─ [W7 Concept Check Quiz] ───────────────────┐      │
│  │  ❓ Pattern này diễn tả cảm xúc gì?          │      │
│  │   ① cảm giác may mắn / được làm điều mình   │      │
│  │      thích                                   │      │
│  │   ② sự ngạc nhiên / bất ngờ                  │      │
│  │   ③ phàn nàn / không hài lòng                │      │
│  └──────────────────────────────────────────────┘      │
└────────────────────────────────────────────────────────┘

(W7 đúng → flow tiếp Message 2; W7 sai → AI explain lại + new W7)

Message 2 - Show + Practice

┌─ AI bubble #2 (practice) ──────────────────────────────┐
│                                                        │
│  Rich text: "Đúng rồi! Giờ áp dụng pattern này nhé."   │
│                                                        │
│  ┌─ [W2 Diff card] ────────────────────────────┐      │
│  │  ~~I like to sleep on the weekend~~          │      │
│  │  →  I like it when I get to sleep on the     │      │
│  │     weekend                                  │      │
│  └──────────────────────────────────────────────┘      │
│                                                        │
│  Voice: "Em thử nói lại câu này nhé."                  │
│                                                        │
│  ┌─ [W4 TTS replay] ───────────────────────────┐      │
│  │  🔊 Nghe lại câu mẫu (normal / slow)         │      │
│  └──────────────────────────────────────────────┘      │
│                                                        │
│  ┌─ [W1 Practice mic] ─────────────────────────┐      │
│  │  🎤 Nói lại câu mẫu:                         │      │
│  │  "I like it when I get to sleep on weekend"  │      │
│  │  [Dừng] [Nói lại] [Xong]                     │      │
│  └──────────────────────────────────────────────┘      │
└────────────────────────────────────────────────────────┘

(Sau pass → optional W10 Pattern Variation; sau ≥2 fails → W9 Stuck Rescue)

2-message rationale: tách explain khỏi practice giúp comprehension được lock trước active production. User không nhảy vội vào W1 mà không hiểu pattern.

Adaptive widgets render (per state)

User state	Adaptive widget rendered
Pass W1 first try	Optional W10 Pattern Variation chip
Fail W1 once	Standard F4 retry feedback (with W2 diff highlighting gap)
Fail W1 ≥2 lần liên tiếp	W9 Stuck Rescue appears với 4 lifeline options
Fail W7 once	AI re-explain pattern + new W7 with rephrased question
Fail W7 ≥2 lần	Triggers W9 Stuck Rescue (escalate from W7 to W9)

Interaction principles

1. Voice ≠ text replication: voice nói lời dẫn ngắn (“Mình thử nâng câu nhé”); text hiện full structured detail. Voice không đọc nguyên text bubble.

2. Widget = inline message, KHÔNG separate UI panel: widget xuất hiện trong chat như bubble đặc biệt. User scroll lên đọc lại history vẫn thấy widget tại đúng chỗ trong context.

3. Chat = scrollable pedagogical record: append-only history. User sau khi pass 1 round có thể scroll lại đọc TẠI SAO mỗi version được cải thiện. Đây là learning value chính của tính năng.

4. No empty/dead text: AI message KHÔNG bao giờ chỉ là “Good!” hoặc “Wrong, try again!”. Mỗi message phải có: (a) structured explanation, hoặc (b) widget action, hoặc (c) cả hai.

5. Pedagogical voice tone Vietnamese-friendly: “em ơi”, “mình thử…”, “nhé”. Không formal/mechanical. Match narrator_language chosen at F0.

6. Widget composability: 1 message có thể chứa Knowledge card + Diff card + Practice mic stacked. Render order = pedagogical order (explain → check → show → practice).

7. Real-time bidirectional sync: chat tạo improvement → panel auto add card. Panel click card → chat scroll + flash highlight.

8. Adaptive vs proactive widget rendering:

   • Proactive (W1-W4, W6): luôn render khi context match (mọi step practice cần W1; mọi knowledge intro cần W3).
   • Adaptive (W5, W7, W9, W10): conditional render:
     • W5 chỉ khi user bí ở F1
     • W7 luôn check sau W3 (lock comprehension trước practice) - adaptive on knowledge complexity
     • W9 chỉ trigger sau ≥2 fail same step (escalation)
     • W10 optional offer sau W1 pass (user-skippable)
   • Adaptive widgets giúp flow không bloat khi user smooth, nhưng có safety net khi struggle.

9. Two-message pacing for explain-vs-practice separation: tách Message 1 (explain + W7 check) khỏi Message 2 (show + W1 practice) tạo natural pause. Forces user lock comprehension trước active production - không nhảy vội vào W1 mà không hiểu pattern.

Anti-patterns AI conversation

❌ Don’t	✅ Do
Plain text “Câu này gần đúng. Em thử lại nhé.”	Rich text với highlighted target phrase + W2 Diff card showing what’s missing
Voice và text bubble nội dung 100% giống nhau	Voice = short lead-in; text = full breakdown
Widget chung 1 separate panel UI bên dưới chat	Widget inline trong chat bubble, scroll-able theo history
AI message chỉ “Tốt rồi!” sau user pass step	Add explanation WHY user pass + W2 Diff card celebrating + W4 TTS replay câu mới
Right panel chỉ display, không actionable	Click record → expand chat moment / replay sample / re-practice
Chatbot Q&A tone “What do you want to know about word pattern?”	Mentor tone “Mình thử thay ‘I like to’ bằng pattern này nhé”
Skip widget vì “user just text-only mode”	Widget vẫn render - active production via W1 Practice mic là core của feature
Knowledge card chỉ definition không ví dụ	KB Linear 7.0S phải có ≥1 example per knowledge - copy-paste dễ hiểu
Skip W7 Concept Check để “tiết kiệm 1 turn”	W7 lock comprehension; user vào W1 không hiểu pattern = retry spiral
Render W9 Stuck Rescue ở fail #1	W9 premature = user cảm giác bị giám sát. Trigger ≥2 fail mới render.
W10 Pattern Variation bắt buộc làm 3+ examples	W10 optional 1 variation. User skip ngay không penalty. Anti-friction.
W7 Concept Check 5+ questions như test mode	W7 = 1 question/widget. Multiple questions = quiz mode (out of scope).

---

Tính năng (Features)

F0 - Entry: Test mic + chọn ngôn ngữ giáo viên

Mic preflight

• Mic check chỉ xuất hiện khi user chưa có reusable mic status cho mic_check_key hiện tại.
• Reusable status gồm passed hoặc skipped; nếu audio thật bị silent nhiều lần, revoke permission, hoặc đổi input device, hệ thống invalidate status và yêu cầu test lại.
• UI test mic tối giản:
  • title: Kiểm tra microphone;
  • hướng dẫn: Hãy nói một câu ngắn bất kỳ để AI kiểm tra âm thanh.;
  • CTA chính: Cho phép Microphone / Bắt đầu kiểm tra;
  • link phụ: Bỏ qua, mic của tôi đã sẵn sàng.

Chọn ngôn ngữ giáo viên

• Sau mic preflight, user chọn Tiếng Việt hoặc Tiếng Anh.
• narrator_language chỉ ảnh hưởng:
  • voice của AI teacher;
  • chat bubble hướng dẫn;
  • feedback/error message.
• Câu user nói và câu cải thiện vẫn là tiếng Anh.

F1 - Mở đầu hội thoại và lấy câu gốc

AI teacher mở bài

• AI teacher nói bằng voice và đồng thời hiện chat bubble:
  • Nói một câu bất kỳ theo chủ đề "{assigned_topic}" nhé. Nếu chưa biết nói gì thì tôi có thể gợi ý cho bạn.
• Sau khi narrator nói xong, hệ thống tự chuyển conversation_turn = user, auto mở mic và hiện user bubble:
  • placeholder: Nói câu của bạn...
  • controls: Dừng, Nói lại, Xong
• AI avatar = Red DOL logo (intro / orchestrator mode) trong toàn bộ F1. Avatar shifts to Blue gem icon (teacher mode) tại first praise sau khi user submit câu gốc - visual signal cho mode change từ welcomer → mentor. Verified Figma frame 2464:32547. Chi tiết §Verified design state §A.

User nói câu gốc

• Trong lúc user nói, STT cập nhật transcript trực tiếp trong bubble.
• User có thể:
  • Dừng: tạm ngưng mic, giữ transcript hiện tại;
  • Nói lại: xóa transcript lần này, mở mic lại;
  • Xong: submit transcript để phân tích.
• Nếu user im lâu hoặc bấm xin gợi ý, không ép lỗi ngay. Hệ thống hiển thị gợi ý nhẹ.

Gợi ý khi user bí

Render qua W5 Hint pill / suggestion chip widget (xem AI Conversation Architecture §Widget catalog).

Loại gợi ý	UI copy	Ví dụ
Gợi ý câu cơ bản	Gợi ý một câu cơ bản	topic weekend → "I love cooking for my family on weekends"
Gợi ý mở đầu	Thử mở đầu bằng câu này nhé	"I like to sleep on the weekend"

• Gợi ý phải đơn giản, không quá hay ngay từ đầu, để user còn thấy rõ tiến trình cải thiện.
• Gợi ý phải bám assigned_topic; không hiển thị action đổi/gợi ý chủ đề khác.
• Nếu user dùng câu mẫu, vẫn xem đó là user_original_sentence; không skip flow cải thiện.
• Click chip → fill vào user input bubble, không auto-submit (user vẫn phải bấm Xong).

F2 - Phân tích câu user vừa nói

Sau khi user bấm Xong, chuyển spoken_input_state = analyzing và hiện message: Đang phân tích...

AI phân tích các lớp sau:

Lớp phân tích	Mục đích
Audio/STT confidence	Có nghe rõ không, transcript có đáng tin không
English sentence validity	Có phải câu tiếng Anh có thể cải thiện không
Topic relevance	Câu có bám assigned_topic không
Base meaning	User muốn nói ý gì trong phạm vi topic
Error state	Có lỗi grammar/vocab cơ bản cần sửa trước không
KB fit	Step nào trong Linear 7.0S có ích nhất cho câu này
Target path	Chọn danh sách step đủ dùng, không ép đủ tất cả nếu câu đã đạt

Case phân tích và phản hồi

Case	Hành vi	UI message thân thiện
Không nghe thấy tiếng	Không submit, mở lại mic	AI chưa nghe thấy câu của bạn. Kiểm tra mic rồi nói lại nhé.
Transcript quá ngắn/không thành câu	Yêu cầu nói lại hoặc dùng câu mẫu	Câu này còn hơi ngắn. Thử nói thành một câu đầy đủ hơn nhé.
User nói tiếng Việt	Gợi ý chuyển sang câu tiếng Anh đơn giản	Mình hiểu ý rồi. Giờ thử nói ý đó bằng một câu tiếng Anh ngắn nhé.
Câu lạc khỏi chủ đề	Nhắc quay lại topic hiện tại	Câu này chưa đúng chủ đề "{assigned_topic}". Thử nói một câu ngắn về chủ đề này nhé.
Câu không rõ nghĩa	Hỏi lại bằng prompt ngắn	Ý này chưa rõ để cải thiện. Bạn nói lại đơn giản hơn một chút nhé.
Câu có lỗi grammar/vocab	Thêm step correction trước	Mình sửa nhẹ câu trước, rồi mình sẽ nâng câu lên hay hơn nhé.
Câu đúng nhưng cơ bản	Bắt đầu từ word_pattern	Câu này dùng được rồi. Giờ mình nâng câu từng bước nhé.
Câu đã khá nâng cao	Chọn step nâng cao còn thiếu hoặc rút ngắn path	Câu này đã khá tốt. Mình chỉ thêm một điểm nhỏ để câu tự nhiên hơn nhé.

F3 - Cải thiện từng bước theo Knowledge Base

Logic step

Step	Tên	Khi nào dùng	Output
2a	Correction	Có lỗi grammar/vocab làm câu chưa đúng	Câu đúng cơ bản
2b	Word pattern	Câu còn diễn đạt trực tiếp, chưa có pattern	Câu dùng word pattern từ KB
2c	Idiomatic language	Câu đúng và có thể thêm sắc thái tự nhiên	Câu có idiomatic phrase phù hợp
2d	Suffixing structure	Cần thêm mệnh đề phụ để tăng grammar range	Câu có phần đuôi rõ nghĩa

Branching logic

Trường hợp	Đường đi khuyến nghị
Có lỗi sai rõ	2a → 2b → 2d; thêm 2c nếu câu vẫn hợp và không quá nặng
Không lỗi, câu cơ bản	2b → 2c → 2d
Câu đã có word pattern	2c → 2d hoặc chỉ 2d
Câu đã khá nâng cao	1 step có giá trị nhất → target reached
Không tìm được KB fit tốt	Chỉ sửa để câu đúng + cho user nói lại, không bịa kiến thức

Mỗi step cải thiện - 2-message widget composition

Mỗi step = 2 AI messages với widget stacks theo pedagogical order explain → check → show → practice:

Message 1 - Explain + Check (lock comprehension trước practice):

1. AI teacher giải thích một điểm kiến thức ngắn theo narrator_language (voice).
2. Chat bubble hiện rich text rationale.
3. W3 Knowledge mini-card với definition + 1-2 ví dụ từ KB Linear 7.0S.
4. W6 Comparison view (optional, khi cần giải thích sâu why câu mới hay hơn).
5. W7 Concept Check Quiz - 1 question kiểm comprehension trước khi sang practice.
   • Đúng → flow tiếp Message 2.
   • Sai (lần 1) → AI re-explain với rephrasing + new W7.
   • Sai ≥2 lần → escalate to W9 Stuck Rescue (lifeline options).

Message 2 - Show + Practice (active production): 6. Progress panel thêm/activate card step tương ứng - sync real-time với chat. 7. W2 Diff card show câu cũ → câu mẫu cải thiện với highlight phần áp dụng pattern. 8. W4 TTS replay button (normal + slow speed) kèm câu mẫu để user nghe trước khi luyện. 9. W1 Practice mic với câu mẫu hiển thị → auto mở mic → user nói lại với transcript live → controls Dừng / Nói lại / Xong. 10. Sau user submit từ W1: hệ thống phân tích pronunciation + semantic match + target knowledge.

Sau Message 2 pass/fail: 11. Nếu đạt (W1 first try): mark step passed, update current_sentence, panel card flip success state. - Optional: render W10 Pattern Variation chip - user có thể skip ngay hoặc thử pattern với chủ đề khác để generalize. - Sau (W10 hoặc skip) → next step Message 1 mới. 12. Nếu chưa đạt (fail 1×): AI message mới với feedback + retry widgets (xem §F4 cho widget mapping per case). 13. Nếu fail ≥2 lần liên tiếp: render W9 Stuck Rescue với 4 lifeline options: - Re-explain pattern → re-render Message 1 với new W3 framing - Slow demo câu mẫu → W4 slow replay - Skip step → mark skipped, next step - Continue retry → close W9, back to Message 2

Progress panel behavior

• Card đầu tiên luôn giữ Câu gốc.
• Mỗi step có label đúng tên KB: CORRECTION, WORD PATTERN, IDIOMATIC LANGUAGE, SUFFIXING STRUCTURE.
• Step đang chạy có loading: Đang hoàn thiện...
• Step đã pass có:
  • câu cải thiện;
  • Nghe lại;
  • Giải thích;
  • icon audio nếu có TTS mẫu.
• Nếu step lỗi do user nói sai, panel chuyển trạng thái attention nhưng không xóa progress đã đạt trước đó.
• 3 visual states của panel (verified Figma - chi tiết §Verified design state §B):
  • Default: title ✨ Tiến độ cải thiện, border subtle, active card có pattern badge (WORD PATTERN / IDIOMATIC LANGUAGE / SUFFIXING STRUCTURE).
  • Error (khi Sửa lỗi flow active): title chuyển thành ❗ Cải thiện câu (different copy!), red border, active card có badge SỬA LỖI (red).
  • Complete (all steps passed): title ✓ Tổng N bước cải thiện, có inline HOÀN THÀNH! green banner cuối panel.

F4 - AI feedback đa kịch bản khi user luyện nói lại

Mỗi case = 1 AI message mới (append vào chat) với widget composition phù hợp ngữ cảnh.

Sửa lỗi visual đã có sẵn trong Figma frame 2278:14948 (Nói Sai). Composition: Bubble chat - User (Blue gem) + Content/suggestion (Content=Feedback) + header tag 🔴 SỬA LỖI + bullet list with Type=Red, Case=Highlight Text blank cho phrase lỗi + Type=Bold cho phrase đúng. Right panel đồng thời shift sang Error state (xem §Verified design state §B). Recipe: ai-memory/lessons/dol-ds-text-blank-variants-for-chat-content.md.

Adaptive escalation rule: nếu cùng step fail ≥2 lần liên tiếp (cộng dồn từ tất cả case), append W9 Stuck Rescue sau retry widget thông thường để cho user lifeline options. W9 có thể trigger từ bất kỳ case nào dưới đây nếu attempt counter ≥2.

Case	Hành vi	UI message thân thiện	Widgets render (1st fail)	Widgets render (≥2nd fail same step)
Nói đúng câu mẫu	Pass step	Tốt rồi. Em áp dụng đúng phần này rồi nhé.	W2 Diff card (celebration mode - all green) + W4 TTS replay câu pass + optional W10 Pattern Variation	(n/a - pass không escalate)
Gần đúng, thiếu target pattern	Retry cùng step	Gần đúng rồi. Em nhớ thêm phần **"{target_phrase}"** vào câu nhé.	W2 Diff card (highlight phần thiếu in red) + W1 Practice mic retry	+ W9 Stuck Rescue lifeline
Nói lại câu cũ, chưa dùng cải thiện	Retry	Em đang nói lại câu cũ. Thử dùng câu mới mình vừa luyện nhé.	W2 Diff card (current vs target) + W4 TTS replay + W1 Practice mic retry	+ W9 Stuck Rescue lifeline
Sai cấu trúc chính	Giải thích ngắn + replay mẫu	Cấu trúc này cần đi theo mẫu **"{pattern}"**. Nghe lại rồi thử nói lại nhé.	W3 Knowledge mini-card (recap pattern) + W4 TTS replay + W1 Practice mic	+ W9 Stuck Rescue lifeline
Thêm nội dung không liên quan	Nhắc bám câu mẫu	Ý thêm này chưa cần ở bước này. Mình tập đúng câu mẫu trước nhé.	W2 Diff card (extra content highlighted as “skip later”) + W1 Practice mic	+ W9 Stuck Rescue lifeline
Phát âm/STT không chắc	Cho retry, không tính sai nặng	AI nghe chưa rõ đoạn này. Em nói chậm hơn một chút nhé.	W4 TTS replay (slow mode) + W1 Practice mic retry	(không escalate W9 - là STT issue, không phải user struggle)
Nói tiếng Việt	Không pass, chuyển hướng	Mình cần em nói câu này bằng tiếng Anh để luyện phát âm và cấu trúc nhé.	W4 TTS replay câu mẫu + W1 Practice mic (no diff card)	+ W9 Stuck Rescue lifeline
User nói câu khác nhưng đúng nghĩa + có target knowledge	Accept nếu semantic match đủ cao	Cách nói này vẫn đúng ý. Mình lưu version này nhé.	W2 Diff card (alternate version - both valid) - panel add card với note “alternate” + optional W10 Pattern Variation	(n/a - accept = pass)

F5 - Hoàn thành và chuyển câu tiếp theo

User được hoàn thành khi:

• có user_original_sentence hợp lệ;
• hoàn thành các step bắt buộc theo target_path, hoặc AI đánh dấu target_reached;
• câu cải thiện cuối cùng đã được user nói lại thành công ít nhất 1 lần.

Khi đạt (verified Figma frame 2359:46013):

• Chat bubble (Blue gem AI, green-border bubble): Câu đã được phát triển tốt theo yêu cầu. + 2 inline action chips Câu mới → và Xem lại ↻.
• Progress panel: title chuyển sang ✓ Tổng N bước cải thiện + inline HOÀN THÀNH! green banner cuối panel với copy “Câu của bạn đã được triển khai tốt và đạt yêu cầu. Bạn có thể qua câu tiếp theo hoặc xem lại những gì đã cải thiện nhé.”
• Bottom CTA: chuyển từ Bỏ qua → (secondary) sang Tiếp tục → (primary red filled) - visual upgrade signaling completion (xem §Verified design state §C).

Không cần ép đủ 3 bước nếu câu đã đạt mục tiêu sớm. Ngược lại, không cho hoàn thành nếu user chỉ đọc/xem mà chưa nói lại version cuối.

F6 - Review Mode

Tự kích hoạt khi hoàn thành, hoặc khi user bấm vào một record cải thiện.

Khi bấm vào record cải thiện

1. Chat scroll về moment AI đã giải thích version đó + flash highlight để user dễ orient.
2. Render W2 Diff card expanded mode: câu trước cải thiện + câu sau, highlight phần kiến thức đã áp dụng.
3. Render 3 action buttons inline trong chat bubble (pedagogical action widgets):

Button	Hành vi	Widget render
Tập nói lại	Load câu cải thiện, user nói lại với karaoke/transcript	W4 TTS replay câu mẫu + W1 Practice mic (no pass requirement - just practice)
Tập thêm [kiến thức]	Mở practice extra với 2 ví dụ khác từ KB	W3 Knowledge mini-card expanded với 2 ví dụ + 2× W1 Practice mic cho từng ví dụ
Giải thích	AI teacher giải thích lại ngắn gọn theo narrator_language	New AI message với rich text + W3 Knowledge mini-card recap

Practice Extra

• Dùng giao diện giống Speak a Sentence.
• Mỗi knowledge chỉ cần 2 ví dụ, giảm độ khó và ưu tiên lặp đúng pattern.
• Không ảnh hưởng completion chính của câu hiện tại; chỉ tăng practice tracking.

---

Scene Flow

Entry:
    Check mic
        ├── passed/skipped → chọn ngôn ngữ giáo viên
        └── chưa pass/denied → xin quyền hoặc test mic

    Chọn narrator_language
        ├── Tiếng Việt
        └── Tiếng Anh

Opening:
    AI teacher nói + hiện chat:
        "Nói một câu bất kỳ theo chủ đề {assigned_topic}..."
    → narrator dừng
    → auto mở mic cho user

User sentence intake:
    User nói câu gốc
        ├── nói được → submit → analyzing
        ├── im/bí → gợi ý một câu cơ bản theo assigned_topic
        └── nói lại → reset transcript và mở mic lại

Analyze:
    STT + validity + error + KB fit
        ├── không nghe/không phải câu tiếng Anh → retry/gợi ý
        └── hợp lệ → tạo target_path

Improve:
    Với từng step trong target_path:
        AI giải thích + đưa câu mẫu
        → auto mở mic
        → user nói lại
        → phân tích
            ├── đạt → update current_sentence + next step
            └── chưa đạt → feedback + retry cùng step

Complete:
    target reached + user nói lại version cuối
    → bật CTA Câu mới / Tiếp tục

Review:
    User bấm record
        ├── Tập nói lại
        ├── Tập thêm knowledge
        └── Giải thích

User Actions

Study Mode

Bước	User làm gì	Hệ thống/AI phản hồi
0	Vào bài	Check mic status theo user_id + exercise_type
1	Chọn ngôn ngữ giáo viên	Lưu narrator_language; lời dẫn/feedback theo ngôn ngữ này
2	Nghe AI teacher mở bài	Chat bubble hiện cùng nội dung narrator nói
3	Nói câu gốc	Auto transcript trong user bubble
4	Bấm Xong	AI phân tích câu + tạo target path
5	Nếu bí, bấm gợi ý	AI gợi ý một câu cơ bản theo topic hiện tại
6	Nghe bước cải thiện	Progress panel activate step mới
7	Nói lại câu mẫu	AI check target knowledge
8	Nói sai/chưa đủ	Feedback cụ thể + giữ step hiện tại
9	Nói đúng	Step passed, update câu, chuyển step tiếp
10	Đạt mục tiêu	Bật Câu mới / Tiếp tục

Review Mode

Bước	User làm gì	Hệ thống/AI phản hồi
1	Bấm record cải thiện	Hiện trước/sau + highlight knowledge
2a	Bấm Tập nói lại	Load câu cải thiện, user nói lại
2b	Bấm Tập thêm [kiến thức]	2 ví dụ practice extra
2c	Bấm Giải thích	AI teacher giải thích lại ngắn
3	Đóng review/practice	Quay lại flow chính

AI Behavior & AI-UI Interaction

Trigger	AI action	Hiển thị trên UI
User chưa có mic status	Check permission + audio signal	Mic preflight
User chọn narrator language	Save language preference	Card Tiếng Việt / Tiếng Anh selected
AI teacher nói	TTS + tạo chat bubble cùng nội dung	Bubble AI + avatar
Narrator nói xong	Chuyển lượt cho user	Auto mở mic + user bubble active
User đang nói	STT live	Transcript chạy trong bubble
User bí/im lâu	Generate câu mẫu cơ bản theo assigned_topic	Chip Gợi ý một câu cơ bản
User submit câu gốc	Analyze STT + sentence + KB fit	Đang phân tích...
Câu hợp lệ	Generate target_path + step 1	Progress panel mở
Step explanation	Tạo giải thích + sample sentence	AI bubble + progress card
User nói lại đúng	Mark pass + update current sentence	Card xanh/complete, câu mới lưu
User nói sai	Generate feedback theo case	Attention state + CTA Nghe lại/Nói lại
Target reached	Mark completed	Hoàn thành, CTA Câu mới / Tiếp tục

Gemini Voice Script Examples

Tình huống	Gemini nói
Opening	Nói một câu bất kỳ theo chủ đề "weekend" nhé. Nếu chưa biết nói gì thì tôi có thể gợi ý cho bạn.
Gợi ý câu mẫu	Thử mở đầu bằng câu này nhé: I love cooking for my family.
Sau phân tích	Hay lắm. Giờ mình cải thiện câu này từng bước nhé.
Correction	Mình sửa nhẹ câu trước để câu đúng hơn nhé.
Word pattern	Hãy thêm word pattern này để câu tự nhiên hơn: like it when I get to...
Idiomatic language	Tiếp, mình thêm idiomatic language để câu có sắc thái hơn nhé.
Suffixing structure	Giờ thêm một phần đuôi để câu rõ hoàn cảnh hơn.
User nói đúng	Tốt rồi. Em áp dụng đúng phần này rồi nhé.
User nói sai cấu trúc	Cấu trúc này cần đi theo mẫu này. Nghe lại rồi thử nói lại nhé.
Completion	Câu đã được phát triển tốt theo yêu cầu.

---

Completion & Scoring

Per-sentence

Kết quả	Điều kiện
Chưa bắt đầu	Chưa có câu gốc hợp lệ
Đang cải thiện	Có câu gốc, còn step pending/retry
Đạt mục tiêu	Target path đã pass, câu cuối đã nói lại thành công
Hoàn thành	User bấm Tiếp tục hoặc Câu mới sau khi đạt mục tiêu

Session tracking

• Số câu đã cải thiện.
• Knowledge đã luyện: correction, word pattern, idiomatic language, suffixing structure.
• Số lần user nói lại mỗi step.
• Last successful improved sentence.
• Narrator language preference.

---

Lưu ý quan trọng từ Brief

• AI teacher/narrator dẫn dắt bằng voice và chat song song - cả 2 layers chạy đồng thời, voice không lặp 100% với text.
• 🔥 AI mentor model, KHÔNG phải Q&A chatbot: Improve a Sentence khác Speak a Sentence ở chỗ AI cần dạy WHY và HOW câu được nâng cấp, không chỉ judge đúng/sai. Mỗi turn AI = rich text formatting (bold/bullet/highlight) + contextual widgets (xem AI Conversation Architecture §Widget catalog).
• 🔥 Widget composability: 1 AI message có thể stack nhiều widgets theo pedagogical order (explain → show → practice). Widget = inline message trong chat, KHÔNG phải separate panel UI.
• 🔥 Bidirectional sync chat ↔ progress panel: AI tạo improvement → panel auto add card; user click panel card → chat scroll + flash highlight tới moment đó.
• 🔥 Chat = pedagogical record persistent: append-only history. User scroll lại để hiểu TẠI SAO mỗi version cải thiện - đây là learning value chính.
• Sau khi narrator dừng nói, hệ thống tự mở mic cho user để giảm thao tác.
• Gợi ý ban đầu phải cơ bản, không làm thay bài nâng cấp.
• Tên kiến thức (word pattern, idiomatic language, suffixing structure) giữ đúng với Knowledge Base Linear 7.0S.
• User phải nói lại câu mẫu/phiên bản cải thiện mới được pass step (qua W1 Practice mic widget).
• Không auto-complete khi user nói tiếng Việt hoặc nói khác câu mẫu; chỉ accept khi câu khác vẫn đúng nghĩa và có target knowledge.
• Review Mode và Practice Extra là lớp củng cố, không thay thế flow cải thiện chính.
• No empty/dead AI text: AI message KHÔNG bao giờ chỉ là “Good!” hoặc “Wrong, try again!”; mỗi message phải có (a) structured explanation, (b) widget action, hoặc (c) cả hai.

References

• ./PRA_EXAI_Speak_A_Sentence.md - reuse narrator language, mic/speaking states, karaoke/retry behavior.
• ./PRA_EXAI_Speaking_00_Overview.md - Speaking group principles and improvement order.
• ./PRA_EXAI_Speaking_Knowledge_Base.md - Word patterns, idiomatic language, suffixing structures.
• Brief: docs/Command/Resources/Documents/Exercise with AI 2026/Speaking/Brief - Speaking LMS New.pdf
• Demo: https://ias.dol.vn/

Verified design state (2026-04-29 audit)

Inspection of Figma section 2271:10465 (Improve a sentence) - 15 frames mapped vs spec phases. Captured key screens cho F1, F1 hint, F2 transcript, F3 mid-step, F4 retry, F5 success. Cross-checked spec claims vs actual design.

Frame inventory

Frame ID	Name	Phase	Notes
2433:14478	Check mic	F0	Mic preflight
2572:21850	Chọn ngôn ngữ	F0	Narrator language picker
2464:32547	AI nói trước	F1	AI mở bài (Red avatar)
2239:10598	Started	F1	Variant of “AI nói trước”
2558:21607	Loading gợi ý	F1	Transient - hint loading
2262:41945	Gợi ý câu	F1	W5 hint chip + W1 sample mic visible
2457:21641	User nói - Nghe và transcript	F2	Live transcript + W5 chip
2275:11337	Nói xong - Loading phân tích	F2	Transient - analysis loading
2457:21226	Gợi ý câu - Cải thiện 1	F3	Step 1 (Word Pattern)
2278:14619	Cải thiện 2	F3	Step 2 (Idiomatic Language) - most representative
2359:45138	Cải thiện 3	F3	Step 3 (Suffixing Structure)
2278:14948	Nói Sai	F4	W14 Sửa lỗi widget already designed here
2464:31964	Nói Sai (alt)	F4	Variant/duplicate to verify with design team
2551:34174	Pause	Edge	Mic paused state
2359:46013	Đạt chỉ tiêu - Success	F5	Final success + green HOÀN THÀNH banner

Reconciliation: spec ↔ Figma

Spec area	Spec claim	Figma reality	Verdict
F1 AI bubble	AI voice + chat bubble	✓ Confirmed	OK
W5 Hint chip	Lightbulb chip “Gợi ý một câu cơ bản”	✓ 2457:21641	OK
W1 Practice mic	NÓI LẠI CÂU MẪU header + Dừng/Nói lại/Xong	✓ Multiple frames	OK
F3 3-step	Word Pattern → Idiomatic → Suffixing	✓ 2278:14619 + 2359:46013	OK
Progress panel cards	Per step + pattern badge + Nghe lại + Giải thích	✓ Confirmed	OK
W14 Sửa lỗi	Red Highlight Text blank	✓ Already in 2278:14948	My session widget rebuild was redundant
F6 Review Mode	Tự kích hoạt khi hoàn thành	❌ No Figma frame	Gap - needs design
W9 Stuck Rescue	4 lifeline options sau ≥2 fail	❌ No Figma frame	Gap - needs design
W7 Concept Check	Quiz giữa W3 explain và W1 practice	❌ No Figma frame	Gap - needs design
W10 Pattern Variation	Optional sau W1 pass	❌ No Figma frame	Gap - needs design

New findings (codified inline in §F1, §F3, §F5 below)

A. AI dual-avatar pattern

AI uses 2 distinct visual avatars depending on role:

Avatar	Visual	Role	Used in
Red logo	DOL Đỉnh Lực red circular logo	Intro / orchestrator / topic invite	F1 (mở đầu, Started, Gợi ý câu)
Blue gem	Blue diamond icon	Teacher / feedback / improvement explanation	F2/F3/F4/F5 (after first user attempt)

Avatar shifts at AI’s first praise after user submits original sentence - signals mode change from welcomer → mentor. Codified in §F1 below.

B. Right panel - 3 distinct visual states

State	Trigger	Title copy	Border/icon	Active card badge
Default	Step in progress, no error	✨ Tiến độ cải thiện	Subtle	step pattern badge (WORD PATTERN etc.)
Error	User fail W1 → Sửa lỗi flow active	❗ Cải thiện câu (different copy!)	Red border	SỬA LỖI red badge
Complete	All steps passed	✓ Tổng N bước cải thiện	Subtle + green banner inside	All cards + HOÀN THÀNH! green banner

Title copy CHANGES with state - not just visual treatment. Codified in §F3 Progress panel behavior below.

C. Bottom CTA state shift

Phase	Bottom-right CTA	Visual
During flow (F1–F4)	Bỏ qua →	Secondary (slate outline)
Post-completion (F5)	Tiếp tục →	Primary red filled

Codified in §F5 below.

D. End-of-step Knowledge chips

After each step success, 2 action chips appear below user bubble:

• 💡 Xem giải thích - opens explanation drawer (W3 access surface)
• 📕 Kiến thức - opens KB excerpt (W3 access surface, deeper)

These are W3 access surfaces, not separate widgets. Anchor: post-W1-pass position in chat.

E. Pagination meaning

Bottom pagination 1–9 = 9 micro-steps total per session = 3 sentences × 3 improvement steps. Each sentence completes its own 3-step journey before moving to next. Should be added to §UI Overview below.

Bugs / drift to fix in design (not spec)

1. Panel numbering typo: “CÂU CẢI THIỆN 1” appears 3× in 2359:46013 - should be “1 / 2 / 3” per step. Component instance number not incrementing.
2. Sửa lỗi closing copy in 2278:14948: “câu của bạn còn vài lỗi, hãy nghe từ sửa giáo lỗi viên lại nhé. bạn dưới mẫu và đẩy thử câu” - has typos. UX writing pass needed.

Change log

• 2026-04-29 (v3.1): Design audit reconciliation. Inspected Figma section 2271:10465 - 15 frames mapped vs spec phases. Added new section §Verified design state với frame inventory, spec ↔ Figma reconciliation table, 5 new findings (AI dual-avatar pattern, right panel 3-state visual, bottom CTA shift, end-of-step Knowledge chips, pagination = 3 sentences × 3 steps), 2 design bugs to fix (panel numbering, Sửa lỗi closing copy typo), 4 design gaps (F6 Review Mode, W7, W9, W10 chưa có Figma frame). Inline refinements: §UI Overview pagination meaning, §F1 dual-avatar mode shift, §F3 panel 3-state visual detail, §F4 Sửa lỗi visual reference (frame 2278:14948), §F5 completion bubble + green banner + red Tiếp tục CTA. No scope change - verifies + clarifies existing spec.
• 2026-04-28 (v3): Scope pull-back per user feedback. Production widget scope reduced to: AI bubble với rich-text format (DS Bubble chat - User + Content/suggestion + Exercise/Text blank variants) + W1 Practice mic + new W14 Error correction widget (sửa lỗi). v2 catalog kept as exploration record only. Codified rule: widgets must compose from existing DS components, not hand-built primitives. W14 uses DS Type=Red, Case=Highlight Text blank variant cho phrase lỗi, Type=Bold cho fix correctness. Recipe: ai-memory/lessons/dol-ds-text-blank-variants-for-chat-content.md. Figma example: section 2976:303592 (Improve a Sentence canvas).
• 2026-04-28 (v2): Widget catalog expanded v1 → v2 (6 → 9 widgets). Added 3 adaptive widgets per pedagogical analysis: W7 Concept Check Quiz (lock comprehension giữa W3 explain và W1 practice - 1 question, escalate to W9 sau ≥2 fails), W9 Stuck Rescue / Lifeline (4 lifeline options khi user fail same step ≥2 lần liên tiếp - re-explain / slow demo / skip / retry), W10 Pattern Practice Variation (optional reinforce abstraction sau W1 pass với pre-fill template + suggested fillers). AI message anatomy refactored thành 2-message pattern explain → check → practice: Message 1 = W3 + optional W6 + W7; Message 2 = W2 + W4 + W1. F3 step composition + F4 retry feedback table updated với adaptive widget triggers (W9 escalation rule sau ≥2 fail same step). Interaction principles thêm 2 mới: adaptive vs proactive widget rendering + two-message pacing rule. Anti-patterns thêm 4 cases (don’t skip W7, don’t premature W9, don’t bloat W10/W7).
• 2026-04-28 (v1): AI Conversation Architecture codified (per user clarification 2026-04-28). Thêm major section “AI Conversation Architecture” giữa UI Overview và Tính năng - định nghĩa 3 trụ cột (Voice + Rich text + Widgets), widget catalog v1 (W1 Practice mic, W2 Diff card, W3 Knowledge mini-card, W4 TTS replay, W5 Hint pill, W6 Comparison view), AI message anatomy với widget composability example, 7 interaction principles, anti-patterns table. Update §F1 (W5 hint pill), §F3 (widget composition per step explain→show→practice), §F4 (widget mapping per 8 retry cases), §F6 Review Mode (3 action widgets), §Lưu ý (AI mentor model + bidirectional sync + no empty text). Phân biệt rõ Improve = mentor (dạy WHY/HOW) vs Speak = judge (đúng/sai) như brand differentiator.
• 2026-04-24: Bổ sung flow mới cho Improve a Sentence: mic preflight, chọn ngôn ngữ narrator, hội thoại voice+chat, auto-open mic sau lượt AI, live transcript, hint khi user bí, phân tích câu gốc, progress panel theo KB, feedback đa kịch bản, và điều kiện completion dựa trên target reached.
• 2026-04-21: Refresh Brief source path sau khi import tài liệu vào Speaking/.
• 2026-04-08: Rewrite theo Brief PDF - bổ sung logic sửa bài 4 steps (2a→2b→2c→2d), branching logic, Study Mode / Review Mode, Practice Extra (pattern/idiom/suffixing), Gemini voice scripts.
• 2026-04-06: Rewrite - bổ sung Features, User Actions, AI-UI Interaction, Completion & Scoring.
• 2026-04-06: Khởi tạo draft từ meeting note.