UX Docs + AI Structure Cleanup Implementation Plan

Plans1.929 words10 min read

active

Execution note: Use executing-plans to implement this plan task-by-task.

Goal: Làm cho DOL Education Documentation dễ đọc hơn cho người và AI bằng cách: giữ taxonomy hiện tại, sửa route AI bị lệch, dọn legacy path, giảm nhiễu trong DOL English/UX Design, và chuẩn hóa các overview đang là entry docs.

Architecture: Giữ docs/Domains/** và docs/Shared/** làm canonical layer. Không rename top-level folders để đổi thứ tự hiển thị. docs/context/** là AI routing layer. docs/tmp/** và run artifacts không phải canon. Concepts, Archive, Auto, Prototypes chỉ nên sống như support/artifact lane, không được cạnh tranh vai trò với overview/logic docs.

Constraints:

Ưu tiên thay đổi nhỏ, có thể đảo ngược, và không mở migration path lớn nếu chưa cần.
Không delete/move hàng loạt trước khi route AI và link active đã được sửa.
Chỉ chạm file overview/logic đang active khi đã xác định rõ vai trò canon của chúng.
context:guard là hard gate cho lane AI.

Key assumptions:

Taxonomy repo-level hiện tại là đúng: Domains cho domain canon, Shared cho cross-domain canon, Command/context/plans/tmp cho support/artifact.
DOL English/UX Design vẫn là baseline UX lane lớn nhất và là nơi cần cleanup trước.
Một phần archive/concept/prototype vẫn có giá trị tham chiếu, nên mục tiêu là demote + isolate + re-route, không phải xóa sạch.

Main risks:

Cleanup quá nhanh có thể làm hỏng links hoặc làm AI mất coverage.
Gộp overview thiếu kiểm soát có thể làm mất boundary giữa workspace entry, surface entry, global baseline, và domain delta.
Một số doc cross-domain hiện đang sống trong English tree; nếu di chuyển sớm sẽ tạo churn cao hơn giá trị nhận được.

Quality rubric:

Correctness (hard gate): canon path, AI route, và active references phải đúng.
Safety (hard gate): không tạo broken links mới, không xóa support docs khi chưa có bridge.
Requirement coverage: phải chạm đủ 3 mục tiêu: AI structure, UX cleanup, stale/error content.
Verification evidence: mọi phase đều có command gate rõ ràng.
Maintainability: sau cleanup, contributor phải biết file nào là entry và file nào chỉ là support.
Delivery efficiency: xử lý trước các issue có tỷ lệ impact / churn cao.

Phase 0: Freeze the operating model

Goal: Khóa lại các quyết định gốc để tránh cleanup đi lệch kiến trúc.

Files:

Reference: docs/README.md
Reference: docs/Domains/DOM_Docs_Content_Placement_Map.md
Reference: .agent/rules/rule-doc-standards.md
Reference: .agent/rules/rule-context-routing-standards.md

Actions:

Xác nhận Domains/Shared tiếp tục là source of truth.
Xác nhận UX Design cleanup sẽ không đổi taxonomy repo-level.
Khóa nguyên tắc: entry docs và support/artifact docs phải tách vai rõ.

Deliverable:

Không cần move file ở phase này.
Phase này chỉ chốt decision để các phase sau không tự tạo branch kiến trúc mới.

Phase 1: Stabilize AI routing first

Goal: Làm docs/context/** đọc đúng canon hiện tại trước khi dọn nội dung.

Current baseline signal:

npm run context:guard đang fail vì:
- 1 missing explicit file ref: docs/Domains/DOL English/UX Design/Vocabulary Management/Vocab v2/Core Logic/VOCV2_Doc_Rules.md
- 5 uncovered active docs: ENG_Lifecycle_Motivation_Contracts.md, ENG_Page_Role_Contracts.md, LM_Current_Web_Baseline.md, KID_LMS_Sitemap.md, GHA_Minute_Control_Runbook.md
- 1 high-branch card: docs/context/ai-tutor-platform.mdc::ctx-ait-core có next_cards=9

Files likely to change:

docs/context/base-context-index.mdc
docs/context/domains.mdc
docs/context/ai-tutor-platform.mdc
docs/context/home-discovery.mdc
docs/context/lm.mdc
docs/context/vocab.mdc
docs/context/operations.mdc
.agent/rules/rule-context-routing-standards.md

Actions:

Fix hoặc remove explicit reference trỏ tới file không tồn tại trong vocab.mdc.
Thêm coverage cho 5 doc active đang uncovered.
Tách ctx-ait-core thành structure hẹp hơn hoặc chuyển bớt sub-routes sang card trung gian để đưa branch factor về <= 8.
Review các card domain/surface để bảo đảm AI bắt đầu từ domain -> workspace -> surface, không nhảy thẳng vào legacy concept folders.
Giữ docs/tmp/** và run logs ngoài canonical route mặc định.

Definition of done for Phase 1:

npm run context:guard exit 0
npm run context:benchmark exit 0
npm run context:stale chỉ còn stale warnings chấp nhận được hoặc đã được note rõ

Phase 2: Clarify entry docs inside DOL English UX

Goal: Mỗi surface có một điểm vào rõ ràng, các file còn lại được đổi vai rõ thành bridge, baseline, hoặc delta.

Priority surfaces:

Home & Discovery
Identity & Access
Self-study Experience
Commerce

Files likely to change first:

Role model to enforce:

workspace entry
- ví dụ: ENG_UX_00_Overview.md
surface entry
- ví dụ: ENG_Home_Discovery_00_Overview.md
global baseline
- ví dụ: HOME_00_Overview.md nếu còn giữ vai trò cross-domain/module baseline
domain delta
- ví dụ: HOME_ENG_Detailed_Baseline.md

Actions:

Thêm hoặc chuẩn hóa opening section để mỗi file tự nói rõ nó là entry, baseline, bridge, hay delta.
Giảm nội dung decision-heavy trong workspace entry; nếu một block như AI Tutor UX Baseline là reusable policy, cân nhắc tách nó thành doc riêng rồi link vào.
Giữ lại nhiều overview nếu chúng thực sự khác vai, nhưng loại bỏ tình trạng “nhiều overview cùng nói gần như một thứ”.

Definition of done for Phase 2:

Contributor mới có thể đi từ ENG_UX_00_Overview.md tới đúng surface trong 1 hop.
Mỗi surface ưu tiên có 1 file được đọc là entry đầu tiên.
Các overview còn lại có nhãn vai trò rõ ràng, không cạnh tranh với entry doc.

Phase 3: Repair stale paths and broken references

Goal: Loại bỏ các link legacy đang route người đọc/AI tới path đã retire hoặc không tồn tại.

Known stale path groups:

Files likely to touch early:

Actions:

Repoint shared-platform references sang docs/Shared/Shared Capabilities/** hoặc canonical home mới.
Với reference tới folder không còn tồn tại nhưng concept vẫn còn giá trị, thay bằng current canonical overview.
Không giữ links “chỉ để nhớ path cũ”.

Definition of done for Phase 3:

Không còn active overview/logic docs trỏ tới Smart Search Platform, Video Course, Zoom Course dưới English UX tree cũ.
rg theo các pattern legacy chính trả về 0 ở nhóm docs active đã xử lý.

Phase 4: Demote artifact clutter without losing useful history

Goal: Giảm nhiễu trong UX tree nhưng không làm mất tài liệu tham chiếu còn hữu ích.

Current signal in docs/Domains/DOL English/UX Design:

676 markdown files
178 files trong Auto
25 files trong Prototypes
24 .html files
19 .DS_Store
13 files trong Archive

Low-risk cleanup:

Xóa .DS_Store
Bỏ references từ entry docs sang raw prototype HTML nếu không còn là nguồn active
Review Auto/** để bảo đảm không có file nào đang được coi là canon ngầm

Sensitive cleanup:

Move Concepts/Docs/Auto/** sang lane ít nhiễu hơn hoặc giữ nguyên nhưng loại khỏi default route
Move hoặc re-label Concepts/Prototypes/** nếu contributor thường nhầm chúng là source of truth
Review Archive/** để xác định cái nào là historical reference cần giữ, cái nào nên retire hẳn

Files likely to change:

docs/context/*.mdc có folder_roots đang quét concept/router folders
docs/Domains/DOL English/UX Design/**/README or overview docs nếu cần chỉ lại source of truth
có thể thêm 1 guide ngắn ở level folder nếu một cluster concept/prototype vẫn cần giữ

Definition of done for Phase 4:

AI routing không ưu tiên artifact folders trước overview/logic docs.
Contributor mở tree UX không bị Auto/Prototypes/Archive chen lên như canon ngầm.
.DS_Store bị loại khỏi repo.

Phase 5: Normalize overview shape on touched docs only

Goal: Đưa các overview active đã sửa về cùng một contract tối thiểu để AI đọc ổn định hơn.

Files likely to normalize first:

Rules to enforce from rule-doc-standards.md:

Có frontmatter cho doc mới/chỉnh sửa
Heading core rõ và nhất quán
Purpose nói rõ problem / audience / success signal
Nếu là entry doc thì phải nói rõ:
- khi nào mở file này
- đọc file nào tiếp theo
- file này không bao phủ gì

Actions:

Không ép migrate toàn repo trong một pass.
Chỉ normalize các overview đang touched bởi cleanup phases trước.
Nếu một doc không phù hợp full template vì nó là map/router doc, thêm wording rõ để tránh bị hiểu là full UX spec.

Definition of done for Phase 5:

Các overview active vừa chạm đều tự giải thích được vai trò và boundary của mình.
Contributor và AI không cần đoán file là map, spec, hay delta.

Phase 6: Close with verification + durable guidance

Goal: Kết thúc bằng evidence và rule đủ gọn để các vòng sau không lặp lại lỗi cũ.

Verification commands:

npm run context:lint
npm run context:guard
npm run context:benchmark
npm run context:stale
npm run artifacts:prune:dry
npm run docs:commit:preview

Post-cleanup guidance targets:

docs/README.md
.agent/rules/rule-context-routing-standards.md
có thể thêm hoặc update 1 rule ngắn cho UX overview role model nếu sau cleanup vẫn dễ drift

Definition of done for full plan:

context:guard và context:benchmark pass
Các active UX overview không còn trỏ tới path đã retire
Mỗi English UX surface ưu tiên có 1 entry doc rõ
AI routing ưu tiên canon trước artifact
Artifacts còn giữ thì đã bị demote về đúng vai
Các touched overview nói rõ entry / bridge / baseline / delta

Recommended execution order

Phase 1 trước để AI không đọc sai trong lúc cleanup.
Phase 2 để giảm tải nhận thức ở bề mặt người đọc.
Phase 3 để dọn broken/stale references trong active docs.
Phase 4 để hạ nhiễu artifact sau khi routes đã ổn.
Phase 5 để chuẩn hóa shape của các docs vừa chạm.
Phase 6 để khóa evidence và guidance.

Suggested delegation model

Explorer A: rà docs/context/**, mapping coverage gaps, branch factor, stale cards.
Explorer B: rà DOL English/UX Design/**, mapping stale links, duplicate entries, artifact clusters.
Worker 1: sửa AI routing + verification gates.
Worker 2: sửa legacy links + overview labeling ở UX docs.
Main thread: giữ quyết định kiến trúc, review diffs, và chốt cleanup boundary.