AI Tutor Platform - Master Product Spec

0) Decision Baseline

Spec này khóa theo các quyết định Product Discovery:

• Core AI Tutor: DEC-0082, DEC-0083, DEC-0084, DEC-0085.
• Smart Search boundary/handoff liên quan AI Tutor: DEC-0086, DEC-0087, DEC-0088, DEC-0089.
• Wave 2 quality contracts: DEC-0090, DEC-0091, DEC-0092.
• Existing recovery-plan policy cluster: DEC-0024 -> DEC-0031.

1) Product Goals and Non-goals

Goals

1. Giúp learner hỏi đáp và hiểu sâu kiến thức ngay trong quá trình học.
2. Chuyển phản hồi AI thành hành động học cụ thể trên platform.
3. Giữ tính toàn vẹn học tập: hỗ trợ làm bài nhưng không làm bài hộ.
4. Dùng tri thức nền tảng làm nguồn chính, giảm trả lời mơ hồ/hallucination.
5. Giúp learner hiểu mình đang ở đâu trước khi đẩy sang nên làm gì tiếp.

Non-goals

1. Không biến AI Tutor thành auto-open assistant ở mọi màn.
2. Không thay thế giáo viên trong các bài đánh giá quan trọng của course mode.
3. Không tối ưu theo mục tiêu “chat lâu”; ưu tiên hiệu quả học tập và continuity.
4. Không mặc định biến mọi AI surface thành planner/checklist generator.

2) User Segments and JTBD

Segment matrix

• New learner (ít dữ liệu): cần giải thích nhanh + bài tập nhỏ để bắt đầu.
• Active self-study learner: cần gợi ý luyện tập sát câu hỏi và ngữ cảnh hiện tại.
• High-attention learner: cần adaptive plan guidance để phục hồi nhịp học.
• Course learner: cần hỗ trợ hỏi đáp trong course boundary, tôn trọng teacher authority.

JTBD

1. “Khi không hiểu kiến thức, tôi muốn được giải thích dễ hiểu và có ví dụ ngay.”
2. “Khi làm bài, tôi muốn được gợi ý cách làm, nhưng vẫn tự giải được.”
3. “Khi không biết học gì tiếp theo, tôi muốn một bước học ngay và một bước đào sâu.”
4. “Khi xem tiến độ, tôi muốn hiểu mình đang ở đâu và làm gì tiếp theo.”

2.5) Learner-facing Platform Logic Baseline

• Trên toàn platform, AI không nên bắt đầu bằng roadmap nếu câu hỏi chính của page là mình đang ở mức nào, điều gì đang xảy ra, hoặc task nào đang chờ.
• Thứ tự phản hồi baseline cho learner-facing AI:
  1. Current-state synthesis: chụp nhanh trạng thái hiện tại từ vài tín hiệu mạnh nhất.
  2. Meaning: giải thích trạng thái đó nói gì về learner ở page hiện tại.
  3. Next useful action: chỉ 1 bước làm ngay hoặc 1 queue item nên xử lý trước.
  4. Deepen if needed: chỉ khi hữu ích mới mở rộng bằng CTA Hỏi sâu hơn với AI Tutor.
• Compression của output phụ thuộc surface archetype:
  • action_hub: why-now summary -> next step,
  • strategy_panel: goal/gap/priority -> ordered steps,
  • coaching_rail: focus point -> hint -> self-check,
  • analysis_panel: signal -> meaning -> fix -> next action,
  • queue_guide: queue snapshot -> readiness note -> do-now item.
• Nếu một AI surface có hơn một mục đích đọc khác nhau, runtime nên tách phản hồi thành purpose-based sections trước khi UI quyết định render thành tabs, stacked blocks, hay split layout.
• Tên tab/section không phải canon cố định; chúng phải thay đổi theo mục đích thật của content, miễn là giữ được ranh giới rõ giữa các purpose như assessment, actions, explanation, queue, readiness.
• plan_guidance chỉ là một mode của hệ AI, không phải default posture cho mọi surface.

3) Invocation and Entry Policy

Global policy

• on-demand only.
• Không auto-open chat panel ở Home, Search, Practice, Learning, Course.

Entry channels

1. Direct query: ACT_AI_TUTOR từ Smart Search.
2. Escalation: từ AI Inline CTA Hỏi sâu hơn với AI Tutor.
3. Manual trigger: Home/Course/Practice/Vocabulary surfaces.
4. Plan entry: high-attention recovery-plan touchpoints.

No auto-open guardrails

• AI Inline render không tự bật AI Tutor.
• Notification/deeplink chỉ dẫn tới context phù hợp; chat mở khi user chủ động tương tác entry.

Runtime and harness boundary

• Runtime là luồng thật dành cho learner; mọi role/mode resolution phải bám cùng một decision order.
• Decision order chuẩn:
  1. guardrail state
  2. surface default
  3. user intent
  4. learner state
  5. entry channel
• Harness chỉ là lớp override nội bộ cho QA/demo/design review:
  • override input state,
  • không bypass guardrail,
  • không mutate learner actual state,
  • phải restore baseline khi đóng harness.
• Chi tiết authoring/runtime rules xem AIT_04_Runtime_and_Harness_Guidelines.md.

4) Conversation Modes

Mode ID	Primary intent	Khi dùng	Bắt buộc output	Guardrail
quick_explain	hiểu nhanh kiến thức	query kiến thức ngắn	concise answer + ví dụ ngắn	không over-claim
deep_tutor_chat	đào sâu theo chuỗi câu hỏi	user muốn hỏi tiếp liên tục	structured explanation + follow-up prompts	giữ context continuity
exercise_coaching	hỗ trợ khi làm bài	active attempt	hint ladder + self-check	không đáp án cuối
plan_guidance	phục hồi nhịp học	high-attention/personalized plan	checklist các bước tiếp theo + next actions	non-blocking
progress_insight	giải thích tiến độ	user hỏi thống kê/tiến độ	metric-window summary + recommendation	on-demand only
resource_recommender	điều hướng tài nguyên	user cần học thêm	do-now + learn-more resources	ưu tiên platform KB
diagram_mindmap_ready	học qua sơ đồ/cấu trúc	user cần visual structure	diagram-ready structure + learning steps	fallback text nếu không render

5) Input Context Contract

5.1 Base session context

interface AITSessionContext {
  sourceModule: 'home' | 'course' | 'learning' | 'practice' | 'vocabulary' | 'program' | 'search';
  pageContextId?: string;
  surfaceArchetype?: 'action_hub' | 'strategy_panel' | 'coaching_rail' | 'analysis_panel' | 'queue_guide' | `${string}.${string}`;
  mainQuestion?: string;
  entryChannel: 'manual' | 'search' | 'inline_escalation' | 'plan_entry' | 'deeplink';
  // Canon: matches aiOrchestrator.ts EntryChannel type.
  // Renamed from spec v0: manual_trigger→manual, search_direct→search, search_inline_escalation→inline_escalation.
  userTier?: 'free' | 'pro' | 'pro_max';
  learnerState?: {
    highAttention?: boolean;
    activePlan?: boolean;
    activeAttempt?: boolean;
  };
  locale?: 'vi' | 'en';
  returnTo?: string;
}

5.2 Handoff Payload (Smart Search → AI Tutor)

// Canon name: AIHandoffPayload (AIChatPanel.tsx)
// Previously: AIInlineExportPacket (spec v0), AIInlineTutorHandoffPayload (carryover notes)
interface AIHandoffPayload {
  inlineFeatureKey: string;
  intentId: string;
  query: string;
  inlineSummary: string;
  surfaceArchetype?: 'action_hub' | 'strategy_panel' | 'coaching_rail' | 'analysis_panel' | 'queue_guide' | `${string}.${string}`;
  mainQuestion?: string;
  evidence?: string[];
  provenanceHints?: Array<{
    sourceClass: 'practice' | 'course' | 'blog' | 'history';
    sourceId?: string;
  }>;
  recommendedActions?: string[];
  sourceModule: 'home' | 'course' | 'learning' | 'practice' | 'vocabulary' | 'program';
  pageContextId?: string;
  freshnessAt?: string;
  confidence?: 'high' | 'medium' | 'low';
  payloadTier?: 'full' | 'balanced' | 'lite';
  returnTo: string;
}

5.3 Fallback context minimum

Khi packet lỗi/thiếu:

interface AITFallbackSeed {
  intentId: string;
  query: string;
  sourceModule: 'home' | 'course' | 'learning' | 'practice' | 'vocabulary' | 'program' | 'search';
}

5.4 Handoff payload compression policy

• Packet runtime dùng tier:
  • full: ưu tiên context richness.
  • balanced: default cho mobile.
  • lite: low-end/poor network.
• Compression caps:
  • evidence[]: 3/2/0-1 theo tier.
  • recommendedActions[]: 3/2/1 theo tier.
  • inlineSummary: cắt theo ngưỡng ký tự tier-specific.
• Invariant:
  • luôn giữ required minimum fields cho handoff.
  • nếu packet degraded/lỗi: vẫn mở chat bằng AITFallbackSeed, không block user.

6) Output Contract and UX States

6.1 Response envelope

interface AITResponseEnvelope {
  artifactType:
    | 'concise_answer'
    | 'guided_checklist'
    | 'mini_exercise'
    | 'diagram_or_mindmap_ready'
    | 'progress_insight';
  message: string;
  contentSections?: Array<{
    purpose: 'summary' | 'assessment' | 'actions' | 'explanation' | 'readiness' | 'queue' | 'evidence';
    label: string;
    emphasis: 'primary' | 'secondary';
    content?: string;
  }>;
  presentationLayoutHint?: 'single' | 'stacked_sections' | 'tab_candidate';
  actions?: Array<{
    type: 'continue_chat' | 'open_resource' | 'open_exercise' | 'open_plan' | 'open_progress';
    label: string;
    target?: string;
  }>;
  provenance: Array<'practice' | 'course' | 'blog' | 'history' | 'general_fallback'>;
  confidence?: 'high' | 'medium' | 'low';
  safetyMode?: 'normal' | 'exercise_coaching_integrity';
}

6.2 Action continuity rule

• Với output không tầm thường (checklist, mini-exercise, progress, mindmap-ready), phản hồi phải có ít nhất 1 action kế tiếp:
  • tiếp tục trong chat, hoặc
  • deeplink sang tài nguyên/bài tập phù hợp.

6.2.1 Purpose-based section rule

• Không nhồi toàn bộ insight, action, explanation, và queue state vào cùng một khối text.
• Nếu response có từ 2 purpose khác nhau trở lên, runtime nên gắn contentSections và tách content thành các section ngắn, rõ ranh giới.
• Nếu surface có lane summary và detail/evidence, contentSections nên cho phép body riêng theo lane để summary không chỉ là bản rút gọn cơ học của detail.
• Nếu model chưa trả body riêng đủ tốt, runtime nên hydrate lane content tối thiểu để summary vẫn là conclusion-first và detail/evidence vẫn là phần lý do/tín hiệu.
• Với learner-facing inline surfaces, UI nên ưu tiên một compact switch hoặc segmented toggle để chỉ foreground 1 section tại một thời điểm.
• stacked_sections chỉ là fallback khi việc switch làm mất ngữ cảnh cần nhìn đồng thời; contract không ép cố định các tab tên gì.
• Nếu response có checklist hoặc roadmap rõ ràng, lane này nên được coi là một purpose/action lane riêng để UI có thể đưa nó vào cùng hệ toggle thay vì luôn đẩy xuống dưới.
• Khi section title hoặc toggle label đã đủ semantic, không thêm helper label dư kiểu Phần đang xem, Summary, Actions ở ngay phần thân nội dung.
• Surface defaults:
  • strategy_panel, analysis_panel, vocabulary diagnosis: thường phù hợp với 3 lane nếu response có đủ summary + rationale + action.
  • action_hub, course guide/queue: thường chỉ cần 2 lane.
  • coaching_rail: không ép 3 lane; giữ guidance-first.

6.3 UX states

• loading: hiển thị trạng thái “AI đang tổng hợp”.
• success: render artifact + actions + provenance.
• stale: cảnh báo dữ liệu cũ + CTA refresh/nguồn chuẩn.
• empty: chưa đủ dữ liệu -> onboarding-safe guidance.
• error: lỗi kỹ thuật -> fallback concise guidance + retry CTA.

6.4 Diagram and mindmap rendering policy

• diagram_or_mindmap_ready dùng 3 tầng render:
  1. visual_native: khi renderer/device hỗ trợ.
  2. structured_graph_text: fallback node-edge text chuẩn.
  3. guided_checklist_fallback: fallback cuối khi vượt complexity gate.
• Mọi tầng render phải giữ action continuity.

6.5 Provenance visibility depth policy

• Depth modes:
  • compact,
  • standard,
  • detailed (on-demand).
• Segment defaults:
  • new learner -> compact,
  • active learner/course/high-attention -> standard.
• Bất kể depth mode:
  • nếu general_fallback phải luôn có disclosure giới hạn dữ liệu.

7) Cross-module Handoff Contracts

7.1 AI Inline Surface -> AI Tutor

• CTA escalation chuẩn: Hỏi sâu hơn với AI Tutor.
• CTA này là secondary action:
  • không auto-open chat,
  • chỉ mở khi user chủ động muốn đào sâu thêm,
  • không thay thế CTA chính của page nếu page đang action-first.
• Export AIHandoffPayload (canon name, AIChatPanel.tsx).
• Handoff packet chọn payloadTier theo device/network profile.
• Open chat với seed context ngay lượt đầu.
• Nếu export lỗi: mở Tutor với AITFallbackSeed, hiển thị notice nhẹ, không block user.
• Packet handoff từ embedded AI inline phải giữ tối thiểu:
  • intentId,
  • query,
  • inlineSummary,
  • sourceModule,
  • entryChannel = inline_escalation,
  • returnTo.
• Inline escalation phải preserve chính nội dung learner đang xem:
  • inline summary hiện tại,
  • context page hiện tại,
  • role/mode seed nếu có.
• Smart Search là một variant của cùng rule này, không phải contract riêng tách khỏi baseline chung.
• Mapping AI Thi thu Full Test:
  • canonical intent giữ ACT_TEST,
  • inline variant dùng AIF_MOCK_FULL_TEST,
  • không tách intent mới trong v1 taxonomy.

7.2 Home -> AI Tutor

• Home chỉ cung cấp manual entry.
• Không mở chat tự động khi vào Home/notification state.

7.3 Practice Attempt -> AI Tutor

• Nếu activeAttempt = true:
  • bật exercise_coaching_integrity mode.
  • áp dụng hint ladder và block final-answer outputs.

7.4 Practice Result -> AI Tutor

• Sau submit/finalized result:
  • cho phép giải đầy đủ như material tham khảo.
  • ưu tiên gắn link bài tương tự/related practice.

7.5 AI Tutor -> module action

• Action types chuẩn:
  • open_exercise, open_resource, open_plan, open_progress, continue_chat.
• Mỗi action cần returnTo khi applicable để giữ continuity.

8) Safety and Policy

8.1 Active-attempt integrity hard rule

Trong active attempt, AI Tutor không được:

1. đưa đáp án cuối;
2. chọn đáp án đúng trực tiếp;
3. viết full bài nộp thay user.

8.2 Hint ladder

1. Orientation hint: chỉ điểm phạm vi cần tập trung.
2. Concept hint: nhắc rule/pattern nền.
3. Scaffolded steps: chia bước giải.
4. Self-check: yêu cầu learner tự kiểm chứng trước nộp.

8.3 Repeated direct-answer requests

• AI nhắc ngắn policy integrity và tiếp tục ở mức hint hợp lệ.

8.4 Teacher boundary

• Ở course mode, AI không thay giáo viên trong chốt điểm bài quan trọng.

8.5 Grounding transparency

• Thiếu evidence platform: phải nói rõ giới hạn + đưa fallback actions an toàn.

8.6 Sandbox exception policy (non-graded only)

• Hard rule no-final-answer vẫn áp dụng cho mọi graded active attempt.
• Chỉ trong context non_graded_sandbox và no_score_or_streak_impact:
  • AI được phép cung cấp sample/reference answer có label rõ.
• Exception không áp dụng cho bài có submission impact hoặc bài quan trọng course mode.

9) Metrics and Quality Gates

9.1 North-star metrics

1. ait_action_continuation_rate: % phiên AI có hành động học tiếp theo.
2. ait_helpful_session_rate: % phiên được user đánh dấu hữu ích hoặc có tiếp diễn học tập.

9.2 Guardrail metrics

1. ait_final_answer_leak_rate_active_attempt -> mục tiêu 0.
2. ait_grounding_fallback_rate (theo module).
3. ait_handoff_fallback_open_rate (inline -> tutor).
4. ait_latency_p95 cho response first token.

9.3 Release gates

• Gate 1: no-final-answer pass trên bộ scenario active attempt.
• Gate 2: handoff packet + fallback open pass.
• Gate 3: provenance tag hiển thị đúng theo source class.
• Gate 4: action continuity đạt threshold tối thiểu đã chốt trong sprint.

10) Rollout and Governance

10.1 Rollout phases

• Phase 0: contract lock + docs sync.
• Phase 1: quick explain + deep chat + direct/inline handoff.
• Phase 2: exercise coaching integrity + mini exercise.
• Phase 3: progress insight + diagram/mindmap-ready enhancements.

10.2 Experiment policy

• Không bật đại trà mode mới khi chưa có acceptance scenarios pass.
• Ưu tiên A/B nhỏ cho output format và CTA continuity.

10.3 Stop / rollback rules

• Rollback ngay nếu phát hiện answer leak trong active attempt.
• Rollback nếu handoff fail gây block mở chat.
• Rollback nếu provenance hiển thị sai gây hiểu nhầm nguồn tri thức.

11) Open Questions

• No blocker-level open questions for AI Tutor core baseline.
• Remaining items are implementation tuning (thresholds, microcopy, telemetry cut-offs).

12) Supporting Documents

• AIT_00_Overview.md
• AIT_01_Conversation_Modes_and_Output_Contracts.md
• AIT_02_Exercise_Coaching_Integrity_Policy.md
• AIT_03_Smart_Search_Handoff_Contract.md
• AIT_Smart_Search_Carryover_Notes.md
• AIT_Doc_Landscape.md

Change log

• 2026-03-01: Wave 2 contract closure theo DEC-0088..DEC-0092 (mobile payload tiers, full-test mapping, rendering fallback policy, provenance depth, sandbox exception boundaries).
• 2026-03-01: Nâng từ scaffold thành active master spec theo DEC-0082..DEC-0087, bổ sung mode matrix, context contracts, integrity hard rule, output taxonomy, release gates.
• 2026-02-28: Tạo master spec scaffold để dùng làm khung phát triển chi tiết cho conversation AI Tutor riêng.