AI Tutor Platform - Runtime and Harness Guidelines

0) Mục tiêu

• Chốt một SSOT ngắn cho runtime logic của AI Tutor.
• Tách rõ user-facing runtime và internal harness.
• Tạo bộ rule ngắn để AI, design, product, và engineering có thể tái sử dụng khi viết spec hoặc mở rộng surface mới.

1) Baseline

• AI Tutor runtime là luồng thật dành cho learner trên platform.
• Harness là lớp override nội bộ cho design review, QA, demo, và debug nhanh.
• Harness được phép override input state, nhưng không được tạo ra logic riêng tách khỏi runtime thật.
• User cuối không được nhìn thấy các toggle như Agent Role, Mode, Integrity, hay Error Simulation.

2) Runtime Resolution Order

Mọi turn của AI Tutor phải resolve theo thứ tự này:

1. Guardrail state
2. Surface default
3. User intent
4. Learner state
5. Entry channel

Shared reasoning layer

• Không để từng surface tự bóc learnerState theo kiểu ad-hoc.
• Nếu nhiều surface cùng cần đọc highAttention, weakness, momentum, hay next-best action, phải gom chúng vào một shared decision layer.
• Surface runtime chỉ nên đọc decision state + decision summary, sau đó mới build prompt hoặc default UI state.
• Decision layer nên giữ tối giản: chỉ chứa attention track, focus track, preferred mode, recommended action, và evidence ngắn.
• Nếu runtime cùng lúc cần query routing + decision state + next-best action, phải đi qua một shared conversation planner thay vì để chatbox, suggestion planner, hay surface runtime tự ghép các lớp này riêng rẽ.
• Shared conversation planner tối thiểu phải trả ra:
  • query profile,
  • decision state,
  • insight state,
  • preferred mode,
  • next-best action,
  • decision / insight / query-routing / response-profile summaries.
• Nếu AI surface cần nói về learner đang ở mức nào, đang học được gì, thiên về chủ đề nào, hay đã sẵn sàng cho bước tiếp theo chưa, phải đi qua một shared insight synthesis layer thay vì để từng surface tự kể learner state bằng prompt riêng.
• Shared insight synthesis layer nên giữ tối giản và chỉ tạo ra:
  • current level label,
  • recent learning focus,
  • learned summary,
  • current strength,
  • primary risk,
  • readiness note,
  • recommended focus.

Platform signal hierarchy

• Trong DOL English, AI chỉ nên kéo các tín hiệu nào thật sự đổi được quyết định của learner ở page hiện tại.
• Baseline signal families:
  • goal / target gap / study rhythm,
  • practice performance / weak skill / result,
  • course queue / due item / unread feedback,
  • vocab review queue / topic focus / memory health,
  • program priority / current estimate / readiness.
• First response của AI nên tổng hợp tối đa 2..3 signal families mạnh nhất; nếu một signal không đổi được next useful action hoặc meaning, bỏ nó khỏi first response.
• Ở tầng shared learner state, nên giữ tối thiểu vài queue/readiness signals generic như due review count, pending course items, và recent completions để AI vẫn tổng hợp được readiness hoặc backlog ngay cả khi page context của route hiện tại còn mỏng.
• Các tín hiệu backlog/readiness mới nên tác động vào decision layer theo kiểu soft signal / soft weight, không biến mỗi field mới thành một mode matrix cứng. Chúng chỉ nên nghiêng quyết định sang recovery / repair / progress insight khi thật sự cộng hưởng với bối cảnh page và các tín hiệu mạnh khác.

Invariants

• AI không tự “chọn vai” một cách tự do.
• active attempt luôn thắng mọi intent khác.
• Nếu không có override mạnh hơn, runtime phải giữ currentMode của conversation thay vì reset về surface default mỗi turn.
• scenario / what-if luôn chạy trên scenario state, không chạm actual state.
• Mọi state mutation đều theo rule confirm-before-write.
• Nếu AI tạo ra plan_guidance có checklist đủ rõ để áp dụng, runtime phải chuyển nó thành scenario plan qua shared helper; chatbox/surface chỉ được cho user áp dụng hoặc bỏ qua, không tự commit.
• Scenario plan phải model bằng steps[], không dùng days[]; AI được gợi ý bước tiếp theo, không neo cứng vào lịch theo ngày trừ khi có context đặc biệt yêu cầu.
• Với learner-facing surfaces, output mặc định nên theo state -> meaning -> next action -> deep-dive CTA, trừ coaching_rail là focus -> hint -> self-check.
• Plan guidance chỉ được lên làm lớp đầu khi page thật sự là strategy-first hoặc learner đang ở explicit recovery/high-attention context.
• Program landing là source domain riêng: dùng sourceModule = program, không tái dùng learning như proxy semantic.
• Content AI hiển thị cho learner phải ưu tiên compact-by-default: nếu response có nhiều ý, giới hạn còn 2-4 purpose-based sections ngắn với heading rõ.
• Purpose-based sections là lớp semantic trước lớp UI:
  • runtime xác định response đang có các purpose nào như assessment, actions, explanation, queue, readiness,
  • rồi UI mới quyết định render thành compact switch, stacked block, hay split layout.
• Không dùng một bộ tab cố định cho mọi surface; label/tab phải thay đổi theo job-to-be-done của page và bản chất content.
• Với learner-facing inline surfaces có nhiều purpose, mặc định ưu tiên compact switch: chỉ một section active hiển thị tại một thời điểm để giữ card ngắn và bảo vệ spacing bên dưới.
• stacked_sections chỉ là fallback khi switch làm mất ngữ cảnh cần đọc cùng lúc; còn nếu nội dung dài nhưng không chia section rõ thì UI phải collapse preview thay vì để text đẩy mất CTA.
• Nếu response có checklist/roadmap đủ rõ, lane này phải được coi là một purpose/action lane riêng để UI có thể switch tới nó thay vì luôn render nối tiếp dưới narrative body.
• Với surfaces có lane summary và detail/evidence cùng tồn tại, runtime nên ưu tiên section-specific content cho từng lane; summary là kết luận ngắn nhất có thể, còn detail/evidence phải giải thích hoặc mở rộng chứ không lặp lại cùng một copy.
• Với strategy_panel, analysis_panel, và vocab diagnosis, lane detail/evidence nên có ít nhất 2 lớp support như evidence + readiness/explanation để learner hiểu không chỉ “vì sao AI nghĩ vậy” mà còn “điều đó ảnh hưởng gì lúc này”.
• Nếu model không trả lane-specific content đủ rõ, runtime vẫn phải tự hydrate lại summary/detail ở mức tối thiểu để summary không biến thành bản sao của detail.
• Nếu model chỉ trả partial contentSections, runtime phải merge chúng với planner-defined sections thay vì thay thế toàn bộ; model được phép làm section sâu hơn, nhưng không được làm rơi các detail-support lanes như readiness.
• Nếu detail/evidence chỉ là một paraphrase hơi dài hơn của summary, runtime nên coi lane đó là under-detailed và hydrate lại bằng rationale rõ hơn thay vì giữ một detail tab chỉ đổi wording.
• Nếu surface persist inline AI snapshot theo ngày, stale detection chỉ nên đọc semantic page identity + learner activity signals; không được mark stale chỉ vì page summary, title, hay available-actions chrome đổi sau một lượt polish/UI update.
• Nếu page có domain state riêng giàu hơn shared learner store, page đó nên đăng ký thêm activityFingerprint trong AIPageContext để same-day snapshot freshness bám đúng hoạt động học mới của domain đó. Ưu tiên áp dụng cho các route ổn định nhưng state đổi nhiều như dashboard tab, program landing, vocab notebook, course queue.
• Tránh helper label dư trong body như Phần đang xem, Summary, Actions nếu toggle label hoặc section title đã đủ semantic cho learner.
• Nếu surface đã có top-level toggle/segmented control, body của lane active không lặp lại cùng title đó thêm lần nữa; toggle là semantic carrier chính.
• Nếu learner đã switch sang lane detail/evidence, renderer không tự mở thêm compact switch nội bộ hoặc Xem thêm nội dung; lane này phải hiển thị đầy đủ theo stacked/full mode.
• Surface matrix mặc định:
  • strategy_panel, analysis_panel, vocabulary diagnosis: ưu tiên 3 lane = summary + detail/evidence + action nếu có đủ nội dung.
  • action_hub, course queue/guide: thường chỉ cần 2 lane = snapshot + next action.
  • coaching_rail: ưu tiên inline guidance tuần tự, không nên cố tab hóa thành 3 lane chỉ để đồng bộ hình thức.
• Với weekly recap và các recap surface nhẹ, chỉ bật lane detail khi runtime thực sự có evidence/detail purpose; không ép 3 lane mặc định nếu recap chỉ cần snapshot + next action.

3) Input Contract tối thiểu cho mọi AI surface

Mỗi surface mới phải khai báo đủ:

• sourceModule
• entryChannel
• defaultRole
• defaultMode
• activeAttempt behavior
• availableActions
• fallback state

Memory tối thiểu phải giữ

• Conversation persistence chỉ nên giữ metadata tối thiểu cần cho continuity:
  • artifactType của assistant
  • chatSuggestions vừa hiện
• Không lưu thêm metadata nặng nếu runtime hiện chưa thật sự dùng đến nó.

Action execution rule

• Client executor phải ưu tiên availableActions của page context trước.
• Chỉ fallback về canonical route khi page context không khai báo action tương ứng.
• Không cho AI tự suy luận target DOM hay internal route ngoài registry của page.
• Page context phải được normalize trước khi runtime dùng đến nó; nếu surface thiếu sourceModule, summary, pageTitle, hay availableActions, runtime được phép tự suy luận bản tối thiểu từ pagePath + pageContext + surface defaults.
• Không duy trì nhiều action runtime song song cho cùng một nhiệm vụ. Nếu đã có shared executor thì các AI cards, chat panel, và harness phải đi qua cùng lane đó.
• Embedded AI surfaces không được gọi raw callAITutor() với prompt ad-hoc. Mọi surface card phải đi qua một shared surface runtime có spec chung cho role + mode + prompt builder.
• Shared surface runtime không được đưa raw internal prompt vào query router. Mỗi surface phải có một routing query ngắn theo job-to-be-done của surface để dùng chung intent logic với chatbox.
• Prompt của embedded AI surfaces không được tự derive lại highAttention, weakTopics, recentScoreAvg trực tiếp trong từng surface runtime; các heuristic này phải đi qua decision layer trước.
• Nếu model không trả actionSuggestions hợp lệ, surface runtime phải tự hydrate next-best action từ shared conversation planner trước khi trả response cho UI.
• Embedded AI card không được hardcode CTA fallback kiểu “Tiếp tục luyện tập” hay “Sửa lộ trình” nếu CTA đó không đi qua shared action contract.

Context intelligence rule

• Đừng đẩy toàn bộ bài toán ngữ cảnh vào prompt. Ưu tiên một lớp context-intelligence nhỏ để:
  • suy luận surface khi page registration còn thiếu
  • tạo seed chat suggestions từ surface + skill/program + learner state + availableActions
  • validate hoặc backfill actionSuggestions trước khi render
• Default quick suggestions và follow-up chatSuggestions phải đi qua một shared suggestion planner; planner được phép trộn model output + decision state + conversation history + contextual seeds, nhưng UI shell không tự sinh chip ad-hoc.
• Nếu muốn model tạo suggestion tốt hơn, prompt phải nhận một decision summary ngắn từ shared decision layer trước khi gọi model.
• chatSuggestions phải là câu hỏi/nguyện vọng từ góc nhìn learner, tối đa 2-3 item, không lặp lại gợi ý gần nhất.
• actionSuggestions chỉ hợp lệ khi khớp với availableActions của page hoặc với canonical fallback đã được cho phép.
• Nếu một embedded AI inline surface có nội dung đủ giàu để learner muốn đào sâu thêm, surface đó nên có một secondary CTA Hỏi sâu hơn với AI Tutor.
• CTA deep-dive này không được tự ghép payload ad-hoc trong từng card. Nó phải đi qua một shared inline -> chat handoff bridge.
• Handoff bridge tối thiểu phải mang:
  • intentId,
  • query,
  • inlineSummary,
  • sourceModule,
  • entryChannel = inline_escalation,
  • returnTo.
• Hỏi sâu hơn với AI Tutor là CTA secondary:
  • không auto-open,
  • không thay CTA chính của page,
  • không được làm learner rời flow nếu page đang ở active-work state mà chưa có chủ động từ user.
• Nếu cần focus/highlight/prefill, dùng semantic target keys qua data-ai-target hoặc registry tương đương; không cho AI trỏ thẳng vào selector tùy ý.
• User query có quyền override page bias khi tín hiệu nội dung đủ mạnh:
  • nếu learner đang ở Vocabulary nhưng hỏi grammar, AI phải trả lời grammar trực tiếp trước,
  • nếu learner đang ở Course nhưng hỏi progress, AI có thể chuyển sang analysis/progress mode,
  • page context khi đó chỉ còn là secondary context để cá nhân hóa ví dụ, CTA, hoặc follow-up action.
• Với direct content question, AI không được mở đầu bằng phân tích dài về page hiện tại; phải trả lời trực diện trước, rồi mới thêm context hoặc bước tiếp theo nếu thật sự hữu ích.
• Query router phải trả ra một shared response profile tối thiểu cho runtime:
  • answerFormat,
  • detailLevel,
  • pageContextUsage,
  • ctaIntensity.
• Chatbox, tutor service, và embedded AI surfaces không được tự quyết định các trục trên theo kiểu ad-hoc; nếu muốn đổi độ trực diện, độ sâu, hay độ chủ động của CTA thì phải đi qua shared response profile trước.
• Tutor service, shared suggestion planner, và shared surface runtime không được tự import rồi ghép query router + decision layer theo ba đường khác nhau; nếu cả hai lớp cùng cần thiết thì phải đọc qua shared conversation planner trước.
• AI inline suggest không được xem như một widget/card cố định toàn hệ. Mỗi page phải chọn surface archetype theo main question của page:
  • action_hub cho page action-first,
  • strategy_panel cho page strategy-first,
  • coaching_rail cho active work,
  • analysis_panel cho diagnosis/result,
  • queue_guide cho queue/resource-driven page.
• Một surface mới chưa đủ điều kiện promote nếu chưa khai báo:
  • main question,
  • primary archetype,
  • why-this-archetype,
  • allowed actions / blocked actions.
• Với learner-facing AI surfaces, insight-first là baseline:
  • AI nên mở bằng current-state synthesis,
  • chỉ sau đó mới tới next useful action,
  • không đẩy learner vào checklist/roadmap nếu job-to-be-done chính của page là hiểu hiệu suất, mức hiện tại, hoặc readiness.
• Insight-first không có nghĩa là report dài:
  • action_hub chỉ cần 1 short why-now line,
  • queue_guide chỉ cần queue snapshot + do-now item,
  • analysis_panel mới được phép mở rộng signal -> meaning -> fix,
  • strategy_panel mới được phép mở rộng ordered steps.

Nếu thiếu một trong các trường trên thì surface chưa đủ điều kiện để promote thành shared pattern.

4) Harness Rules

Harness được phép override

• surface context
• entry channel
• learner state
• attempt state
• default mode seed
• role hint

Harness không được phép override

• core guardrails của runtime
• policy no-final-answer
• policy confirm-before-write
• output contract schema
• provenance disclosure rules

Harness safety

• Harness chỉ mô phỏng input, không commit dữ liệu thật.
• Khi harness đóng, baseline runtime phải được restore.
• Nếu harness cần mô phỏng plan hay progress, phải dùng scenario state hoặc snapshot mock, không mutate state thật của learner.
• Nếu có nhiều harness surfaces cùng mount trong app, chúng phải dùng chung một shared harness store; không giữ panel state cục bộ ở từng hook instance.
• Harness là representative scenario matrix, không phải bản đồ đầy đủ của mọi AI behavior trong platform.
• Bộ scenario của harness nên tách tối thiểu thành:
  • canonical_runtime,
  • query_override,
  • edge_case.
• Khi program đã là source domain hạng nhất trong runtime, canonical_runtime nên có ít nhất một scenario program landing thật để test strategy-first semantics mà không đi vòng qua learning.
• Nếu thêm scenario mới, ưu tiên lấp gap coverage trước khi tăng số lượng preset trùng nhau.

5) Authoring Rules cho tài liệu AI Tutor

Khi viết hoặc cập nhật spec/UX docs:

1. Viết surface question trước, rồi mới viết component UI.
2. Mỗi surface phải nói rõ AI đang đóng vai gì.
3. Mỗi surface phải có allowed actions và blocked actions.
4. Mọi state giả định phải được dán nhãn là scenario.
5. Nếu thêm action mới, phải cập nhật shared registry/contract trước khi rải xuống UX docs.
6. Nếu thêm guardrail mới, phải cập nhật master spec trước rồi mới propagate xuống surface docs.
7. Không được copy cùng một AI card structure sang nhiều page chỉ vì cùng dùng AI Tutor; phải map page vào surface archetype trước.
8. Nếu page action-first, ưu tiên compact next-step surface; nếu page diagnosis-first, ưu tiên analysis surface; không pha hai job-to-be-done vào cùng một inline unit nếu không có lý do mạnh.
9. Mọi page learner-facing đăng ký vào AI runtime nên có tối thiểu sourceModule + surfaceArchetype + mainQuestion + availableActions; nếu thiếu, runtime được quyền infer tạm nhưng inference không thay contract chính thức của page.
10. Nếu page là multi-surface container như dashboard có tabs/lanes, AI context phải bám active sub-surface semantics; không được chỉ đăng ký theo parent shell rồi để runtime tự đoán tab hiện tại.

6) Reuse Checklist

Trước khi chốt một AI Tutor change, hãy kiểm:

• Role/mode của surface đã map vào runtime order chưa?
• Handoff payload có đủ sourceModule + entryChannel + context chưa?
• Surface này có bypass guardrail nào không?
• Nếu là state giả định, đã tách khỏi actual state chưa?
• Harness có dùng lại cùng enum/contract với runtime chưa?
• Baseline có được restore sau khi test/demo không?

7) Kết luận

• Runtime là sản phẩm thật.
• Harness là công cụ nội bộ để ép runtime rõ ràng hơn.
• Mọi mở rộng AI Tutor nên ưu tiên thêm input contract chuẩn thay vì thêm toggle ngẫu nhiên hay prompt logic riêng lẻ.