Engagement Platform - Mission Documentation Guidelines for AI

Purpose

• Chuẩn hóa cách AI viết và cập nhật tài liệu liên quan mission system.
• Giữ ngôn ngữ tài liệu ngắn, rõ, và không làm drift khỏi canon engagement đã chốt.
• Giúp team tái dùng cùng một rule set cho:
  • spec logic,
  • screen flow,
  • campaign brief,
  • rollout note,
  • review checklist.

Writing Direction

• Learning-first: luôn mô tả giá trị học trước giá trị game.
• Simple-by-default: mô tả bề mặt user ngắn, không phình backend complexity ra UI.
• Three-layer clarity: luôn tách rõ:
  • Daily Mission,
  • Weekly Community Mission,
  • Event Challenge.
• Canon-first: nếu rule đã có ở Engagement Platform thì không tự viết lại theo ngôn ngữ mới.
• Lean docs: bỏ narrative dài không tạo quyết định.
• Core + Delta: rule dùng chung viết ở core; file lane chỉ ghi delta thực sự khác biệt.

Canonical Sources (Priority)

1. ENG_15_Mission_System_Hybrid_Model.md
2. ENG_04_Achievement_Badge_Governance.md
3. ENG_05_Reward_Economy_Governance.md
4. ENG_06_Event_Contracts.md
5. ENG_09_Operating_Model_and_Change_Control.md
6. ENG_12_Achievement_Badge_Reward_and_Batch_System.md
7. ENG_13_Practice_and_Vocabulary_Point_Conversion_System.md
8. Module docs nguồn nếu đang nói về bề mặt thực thi cụ thể.

Mandatory Naming Rules

• Dùng mission cho daily/personal/community logic chuẩn.
• Dùng challenge cho lớp campaign/event có owner vận hành.
• Không trộn lẫn mission, challenge, leaderboard như cùng một thực thể.
• Nếu dùng từ XP trong tài liệu:
  • phải nói rõ đó là user-facing term,
  • không được tự đồng nhất với learning_points trừ khi canon đã chốt vậy.

Reward Terminology Contract

• learning_points
  • chỉ dùng cho rank/global points.
• lifetime_points
  • dùng cho progression dài hạn.
• spendable_points
  • dùng cho đổi quà/quyền lợi.
• XP
  • chỉ là lớp trình bày hoặc alias UI nếu được dùng.
• AI không được viết tài liệu theo hướng:
  • “mọi mission completion đều cho learning_points”.

Required Doc Structure

• Purpose
• When to use
• Core rule
• Reward rule
• UX boundary
• Edge cases
• References
• Change log

Required Logic Blocks

Mọi tài liệu mission mới phải nói rõ tối thiểu:

• family của mission/challenge là gì.
• generation_mode:
  • automatic,
  • automatic from approved templates,
  • operator-managed.
• qualification_rule là gì.
• difficulty_band hoặc escalation logic là gì.
• template_family là gì nếu là daily mission.
• personalization_inputs là gì nếu mission được generate tự động.
• freshness/cooldown là gì nếu là daily mission.
• minimum participation threshold là gì nếu là community mission.
• verification/moderation là gì nếu là event challenge.
• notification/fatigue rule là gì nếu doc có touchpoint nhắc lại.
• reward mapping đi về badge, lifetime_points, spendable_points, hay lớp nào khác.

Surface Simplicity Contract

• Home không được biến thành mission dashboard dày.
• Mặc định không quá 2 daily missions chính cùng lúc trên bề mặt chính.
• Module phụ chỉ hiển thị CTA hoặc progress gọn, không lặp lại toàn bộ mission board.
• Profile ưu tiên archive bằng badge/reward summary hơn là history mission chi chít.

Anti-drift Rules

• Không có 2 file cùng làm source-of-truth cho daily mission logic.
• Không copy lại toàn bộ core mission rule sang doc SAT/TOEIC/Home/Course.
• Nếu chỉ khác wording hoặc placement:
  • ghi ở UX boundary hoặc Domain delta,
  • không tạo canon mới.
• Nếu đổi behavior:
  • cập nhật ENG_15,
  • cập nhật doc module liên quan,
  • cập nhật changelog rõ rule_version impact.

Acceptance Contract for AI-authored Mission Docs

• Phải có ít nhất 1 rule chống lặp/chống nhàm chán nếu nói về daily mission.
• Phải có ít nhất 1 rule chống “mission impossible”.
• Phải nêu rõ user nhận gì khi mission completed và khi mission expired.
• Phải nêu rõ event nào dùng realtime, event nào có thể settle qua batch.
• Phải giữ nguyên nguyên tắc:
  • low-friction action không được leo rank toàn nền tảng.
• Nếu có generator logic:
  • phải nêu rõ input nào được dùng,
  • input nào bị cấm dùng để tăng áp lực sai lệch.

Creativity-safe Rules

• Được đề xuất pattern UX mới nếu:
  • không phá three-layer clarity,
  • không tạo thêm ledger mới vô cớ,
  • không biến mission thành game nặng hơn giá trị học.
• Được phép dùng cách gọi hấp dẫn hơn ở UI layer nếu:
  • canonical mapping phía dưới vẫn rõ và không mâu thuẫn.

AI Quality Rubric

• Correctness 30%
  Hard gate: không mâu thuẫn ENG_15, ENG_05, ENG_13.
• Coverage 25%
  Hard gate: phân biệt đủ daily, weekly community, event challenge.
• Risk & Safety 15%
  Hard gate: không mở cửa farm điểm hoặc tạo nhiệm vụ bất khả thi.
• Verification Evidence 15%
• Maintainability 10%
• Delivery Efficiency 5%

Iterative Loop (Required)

1. Analyze
   • đọc ENG_15 và các governance docs liên quan.
2. Reuse
   • tìm rule/canonical field đã có trước khi viết mới.
3. Draft
   • viết phần core thật ngắn, ưu tiên rule có thể dùng lại.
4. Check
   • tự rà XP, learning_points, reward, challenge, mission có bị trộn nghĩa không.
5. Adjust
   • bỏ đoạn trùng, bỏ metaphor thừa, rút gọn UI complexity.
6. Finalize
   • cập nhật references và changelog.

Reusable Prompt Snippets

• Mission core
  • Hãy dùng canon Engagement Platform để viết/cập nhật logic mission. Phân biệt rõ Daily Mission, Weekly Community Mission, Event Challenge. Giữ trải nghiệm đơn giản, reward rõ, và không để low-friction action biến thành global rank points.
• Mission surface
  • Hãy mô tả bề mặt mission theo hướng simple-by-default. Home chỉ teaser/summary, CTA quay về hành động học thật, không biến thành dashboard social dày đặc.
• Mission cleanup
  • Hãy rà lại tài liệu mission hiện có, xóa phần trùng lặp hoặc lỗi thời, chỉ giữ lại rule còn giá trị dài hạn và có thể tái dùng.

Change log

• 2026-03-06: Tạo guideline chuẩn cho AI khi viết tài liệu mission system.
• 2026-03-06: Khóa rule phân biệt XP với learning_points để tránh drift taxonomy.
• 2026-03-06: Bổ sung contract three-layer clarity và surface simplicity cho mission docs.