DOL Academy - Login Documentation Guidelines for AI

Purpose

• Chuẩn hóa cách AI viết/cập nhật tài liệu Login trong domain Academy.
• Đảm bảo tài liệu luôn gọn, dễ đọc cho Product/UX, và không drift theo thời gian.

Canonical Priority Order

1. HOME_ACA_Login_UX_Blueprint.md.
2. HOME_ACA_Concept_Pack.md.
3. HOME_ACA_SCREEN_LIST.md.
4. Screens/ACA-S07_auth_gate_and_return_context_UI_CONCEPT.md.

Nguyên tắc: nếu có khác biệt, luôn ưu tiên thứ tự trên.

Required Structure (for new/updated login docs)

• Purpose
• When to use
• Main user flow
• Edge cases
• UX copy notes
• References
• Change log

Writing Rules (UX-first)

• Viết theo quyết định sản phẩm, không sa vào implementation.
• Mỗi flow chỉ giữ 3-5 bước chính.
• Mỗi lỗi phải có 1 hành động tiếp theo rõ ràng.
• Không tạo thuật ngữ mới nếu chưa cần.
• Ưu tiên câu ngắn, động từ rõ (Đăng nhập, Tiếp tục, Gửi lại mã).

Anti-Drift Rules

• Không để 2 file cùng đóng vai trò nguồn chuẩn cho cùng 1 hành vi.
• Nếu rule đã có trong canon, chỉ tham chiếu ngắn thay vì viết lại dài.
• Khi thêm rule mới, phải rà và gỡ nội dung mâu thuẫn ở file liên quan.
• Nội dung cũ còn giá trị lịch sử thì giữ ngắn dưới nhãn Supporting note.

Quality Rubric (weighted)

Criterion	Weight	Threshold	Gate
Correctness (đúng với canon)	30%	>=95	Critical
Requirement coverage (đủ login/signup/forgot/gate/return)	20%	>=90	Standard
Risk & safety (không dead-end, không mất context)	20%	>=95	Critical
Verification evidence (có references rõ)	15%	>=85	Standard
Maintainability (gọn, dễ mở rộng)	10%	>=85	Standard
Delivery efficiency (đúng trọng tâm, không dư)	5%	>=80	Standard

Iterative Loop (mandatory)

1. Analyze: đọc canon + file liên quan trực tiếp.
2. Draft: viết bản gọn theo đúng scope.
3. Check: tự chấm rubric 6 tiêu chí.
4. Adjust: sửa tiêu chí thấp nhất trước.
5. Repeat: lặp lại bước 3-4 cho tới khi:
   • hai critical gate đều pass,
   • không còn nội dung thừa/lỗi thời,
   • flow đủ bao quát edge case chính.
6. Finalize: cập nhật references + change log.

Reuse Prompt Snippet

• Hãy cập nhật tài liệu Login cho Academy theo UX-first, bám HOME_ACA_Login_UX_Blueprint.md, chỉ giữ quyết định cần thiết, loại bỏ phần kỹ thuật không cần cho Product/UX.

Change log

• 2026-03-05: Tạo guideline tái sử dụng cho AI để duy trì tài liệu Academy Login nhất quán, gọn và chống drift.