Long-term Documentation Architecture & Governance Plan

Intent: Thiết kế lại cách tổ chức tài liệu theo hướng dùng được lâu dài, kể cả khi logic sản phẩm thay đổi nhiều, số feature tăng, hoặc nhiều người/AI cùng cập nhật song song.

Goal

Tạo một kiến trúc tài liệu cân bằng đủ 4 thứ cùng lúc:

• dễ đọc cho người,
• dễ parse cho AI,
• không mất traceability khi logic đổi,
• không để nhiều file cùng nói một truth theo cách mâu thuẫn.

Success criteria

• Với một feature lớn, người đọc có thể hiểu current truth trong 1 hop.
• AI không cần tự tổng hợp từ 5-7 file mới hiểu được logic cấp feature.
• Mỗi loại truth chỉ có 1 owner layer rõ ràng.
• Screen-level docs và idea-flow artifacts không còn vô tình trở thành source-of-truth của feature logic.
• Khi feature thay đổi lớn, team có một update order chuẩn để tránh đè logic lên nhau.

Non-goals

• Không gom toàn bộ repo vào một “siêu file”.
• Không rewrite toàn bộ docs trong một đợt.
• Không xóa hàng loạt legacy/supporting docs nếu chúng vẫn còn giá trị reference.
• Không ép mọi doc trong repo về cùng một template cứng nhắc.

Constraints

• Giữ docs/Domains/** và docs/Shared/** là home canon cấp repo.
• Giữ UX Design là home canon của logic UX theo domain.
• Giữ Product Discovery cho change log, decision trail, workshop flow, và sync-back khi thật sự cần.
• Giữ idea-flow cho screen/concept workflow; không biến nó thành product canon hay feature logic lane.
• Không biến governance model này thành bureaucracy nặng; dùng cấu trúc nhẹ nhất vẫn đủ rõ cho bài toán thực tế.
• Ưu tiên migration nhỏ, đảo ngược được, và có thể rollout theo phase.

Quality rubric

• Correctness
  • hard gate: không để 2 file cùng layer giữ cùng một truth active.
• Safety
  • hard gate: không làm AI hoặc contributor route vào sai owner doc.
• Readability
  • 1 feature phải có đường đọc ngắn và rõ.
• Traceability
  • vẫn truy ra được vì sao, khi nào đổi, và canon hiện tại là gì.
• Maintainability
  • khi thêm feature mới, team biết nên tạo file gì trước, file gì sau.
• Scalability
  • dùng được khi repo có thêm domain, thêm feature, thêm agent/tooling.

---

Target architecture

1. Repo-level architecture

• docs/Domains/<domain>/Product Discovery/**
  • giữ EVT / DEC / VIEWS và các sync-back notes cần thiết
  • trả lời: vì sao đổi, đã chốt gì, branch nào đã bị loại, còn mở gì
• docs/Domains/<domain>/UX Design/**
  • giữ feature logic, surface logic, page/flow logic, và current UX truth
  • trả lời: user sẽ thấy gì, đi flow nào, interaction ra sao, logic active hiện tại là gì
• docs/Shared/**
  • chỉ dùng khi logic đúng cho nhiều domain
• docs/context/**
  • routing layer cho AI
• docs/tmp/**
  • artifacts tạm, không phải nguồn truth

2. UX doc role stack

Trong docs/Domains/<domain>/UX Design/**, mọi file active nên rơi vào đúng một role:

1. workspace-entry

• cửa vào của cả UX workspace trong một domain
• ví dụ: ENG_UX_00_Overview.md

2. feature-master

• one-stop file owner cho một feature lớn hoặc cross-surface
• giữ:
  • objective
  • problem framing
  • current truth
  • owner map
  • reading path
  • open validation
  • các rule đủ để hiểu feature trong 1 hop

3. feature-rule (optional)

• chỉ tách riêng khi feature quá lớn hoặc rule quá dày
• ví dụ: shell rules, state contracts, ownership contracts, behavior matrix

Default use rule:

• feature nhỏ hoặc chỉ sống gọn trong một surface có thể dừng ở surface-entry + page docs
• chỉ nâng lên feature-master khi feature bắt đầu cross-surface, bị phân mảnh, hoặc cần một file owner rõ để tránh drift

4. surface-entry hoặc surface-overview

• overview của một area owner như Home, Identity, Course Experience, Self-study Experience

5. page / flow / IA / spec docs

• owner detail theo surface hoặc page

6. concept / idea-flow docs

• screen concept, reminder-first artifact, UI exploration output

3. One-truth-per-layer model

Không để cùng một truth bị giữ ở nhiều layer khác nhau:

• feature-level synthesis + current UX truth -> feature-master
• detailed feature rules when needed -> feature-rule
• surface ownership / local behavior -> surface/page docs
• history / rationale / change log / workshop branch -> EVT / DEC / VIEWS
• screen-level creative artifact -> idea-flow docs

4. Source-of-truth ladder

Khi có mâu thuẫn về UX logic, thứ tự ưu tiên là:

1. feature-master
2. feature-rule
3. surface/page docs
4. Product Discovery supporting notes
5. idea-flow / concept docs

Product Discovery không phải current truth mặc định; nó là evidence/history/workshop backing cho UX Design.

---

Naming and frontmatter contract

Required role metadata on active docs

Với các file active ở lane UX, chuẩn hóa dần các field:

• title
• updated
• status
• owner
• doc_role

Recommended metadata for long-term scale

Khi feature count tăng, nên thêm dần cho active docs:

• feature_key
• surface_key
• source_of_truth_level
• supersedes hoặc replaced_by khi có chuyển vai

Naming rule

• *_00_Overview.md
  • dùng cho workspace-entry, feature-master, hoặc surface-entry
  • không dùng mơ hồ cho nhiều role khác nhau nếu file không tự nói rõ role
• *_Contracts.md
  • dùng cho rule-level docs
• *_Information_Architecture.md
  • dùng cho IA / owner behavior ở tầng surface/page
• *_Flow*.md
  • dùng cho route/state progression theo flow cụ thể
• *_UI_CONCEPT.md
  • chỉ dùng cho screen concept / idea-flow output

---

Conflict-prevention rules

Rule 1: One feature, one active feature-master

Trong một domain, một feature lớn mặc định chỉ nên có 1 feature-master active tại một thời điểm.

Rule 2: Lower layers cannot silently redefine upper layers

• surface/page docs không được tự chốt lại cross-surface rule nếu feature-master hoặc feature-rule đã giữ rule đó.
• Product Discovery không được trở thành file owner song song với UX Design cho cùng một logic feature.
• idea-flow docs không được tự giữ canonical feature logic.

Rule 3: Supporting docs must point up

Nếu một file không phải owner layer cao nhất, opening section phải nói rõ:

• file này dùng để làm gì,
• current truth nằm ở file nào cao hơn,
• khi nào nên mở file này.

Rule 4: Discovery stays supporting

Product Discovery chỉ ghi lại phần cần truy vết: change log, decision, rationale, workshop branch, impacted docs.

Rule 5: AI refinement stays lightweight

• Agent nên chủ động rà các góc dễ thiếu khi feature bị sửa:
  • entry
  • state
  • ownership
  • cross-surface impact
  • open validation
• Nhưng các gap non-blocking chỉ nên thành follow-up notes hoặc suggested clarifications, không nên tự động trở thành blocker hay scope expansion.

---

Update order standard

A. Khi thay đổi chạm feature logic hoặc cross-surface behavior

1. update feature-master
2. update feature-rule nếu feature đó có file rule riêng
3. update surface/page docs
4. sync-back Product Discovery nếu thay đổi đó cần decision log, change log, hoặc workshop record
5. update idea-flow / concept docs chỉ khi cần giữ concept artifact
6. update context routing nếu reading path thay đổi

Exception:

• nếu feature chưa đủ lớn để warrant feature-master, có thể bắt đầu từ surface/page docs rồi chỉ promote lên feature-master khi thấy tín hiệu phân mảnh thật sự

B. Khi thay đổi chỉ ở mức screen/presentation

1. update surface/page doc trước
2. update idea-flow / concept docs chỉ nếu đó là bài concept/UI exploration
3. chỉ sync-back lên feature-master nếu thay đổi đó thực sự làm đổi logic

C. Khi review xung đột

Nếu thấy hai file mâu thuẫn:

1. xác định chúng đang ở layer nào
2. ưu tiên file owner layer cao hơn
3. sửa file lower layer để nó không redefine truth nữa

---

Idea-flow alignment

Role of idea-flow in the long-term model

Idea Flow Lite vẫn giữ vai trò rất rõ:

• screen concepts
• flow checkpoints
• lightweight reminders cho AI/contributor
• ghi lại idea mới hoặc concept delta trong lúc build UX docs

Creative guardrail:

• không dùng governance rules này để ép concept work thành full spec quá sớm
• giữ không gian cho thử nghiệm UI khi logic feature chưa cần hard-lock
• dùng refinement loop như một lớp gợi ý thông minh, không phải compliance checklist

Nó không nên giữ:

• canonical feature overview
• cross-surface rule owner
• domain-level current truth

Boundary rule

• Prompt cấp feature -> route vào feature-master trước
• Prompt cấp screen / concept / UI state -> idea-flow chỉ vào thẳng khi task thực sự là concept/UI capture
• Nếu idea-flow phát hiện một unresolved feature-level rule, nó phải sync-back hoặc mở file owner cao hơn, không tự chốt trong concept doc

Tooling implication

Sau phase pilot, nên update prompt/rule của idea-flow theo hướng:

• nếu task nêu feature nhưng chưa xuống screen, không bắt đầu ở idea-flow; route thẳng vào UX Design
• nếu task nêu screen, chỉ dùng idea-flow khi cần artifact concept hoặc capture delta

---

AI routing model

docs/context/** nên route theo stack sau:

1. workspace-entry
2. feature-master
3. feature-rule
4. surface-entry
5. page/spec/flow
6. idea-flow / concept

Không để AI bắt đầu ở:

• docs/tmp/**
• run logs
• screen concepts
• old bridge docs nếu feature-level owner doc đã tồn tại.

---

Migration roadmap

Phase 0: Freeze the model

• Khóa rule role stack ở docs/README.md
• Khóa pilot pattern ở ít nhất một domain active
• Không rollout rộng trước khi pilot pass

Phase 1: Pilot on high-conflict features

Feature ưu tiên:

• Navigation
• Identity & Access
• Course Experience

Deliverables mỗi feature:

• 1 feature-master
• file feature-rule chỉ tạo khi thật sự cần
• reading path được link từ workspace-entry
• supporting docs trỏ đúng owner layer

Definition of done:

• người đọc hiểu feature trong 1 hop
• AI không cần tự ghép nhiều file để hiểu current truth

Phase 2: Normalize doc roles on touched surfaces

• Gắn doc_role cho các file active chính
• Standardize opening sections:
  • purpose
  • doc role
  • when to read
  • what this file does not own

Definition of done:

• file active tự giải thích vai trò của chính nó

Phase 3: Align AI routing and idea-flow prompts

• update docs/context/** để route ưu tiên feature-master
• update idea-flow rules/prompt để không bỏ qua feature layer

Definition of done:

• feature prompts route vào feature-master trước
• screen prompts không phá canon feature

Phase 4: Demote legacy clutter

• review Auto / Prototypes / Archive / tmp
• giữ lại reference cần thiết nhưng không cho chúng cạnh tranh canon

Definition of done:

• AI và contributor không bị hút vào artifact lane trước canon lane

Phase 5: Expand pattern domain-wide

• rollout sang các feature cross-surface còn lại
• không cần áp dụng cho mọi feature nhỏ

Definition of done:

• tất cả feature lớn có feature-master
• feature nhỏ vẫn có thể sống ở surface-entry + page docs nếu đủ rõ

Phase 6: Governance and drift control

• thêm audit checklist ngắn cho review docs
• chỉ cần kiểm tra:
  • feature này đã có feature-master chưa
  • current truth có nằm đúng owner layer không
  • idea-flow docs có đang lấn sang canon không

Definition of done:

• drift mới bị bắt sớm ở review, không đợi tới lúc repo quá rối

---

Rollout priority

P0

• Navigation
• Identity & Access
• Course Experience

Lý do:

• cross-surface cao
• dễ conflict giữa rule và page docs
• tác động trực tiếp tới nhiều flow khác

P1

• Self-study Experience
• Commerce
• AI Tutor learner-facing orchestration

P2

• feature nhỏ hơn hoặc feature chỉ sống trong 1 surface owner rõ ràng

---

Governance checklist for every major update

Trước khi kết luận một update lớn đã ổn, check:

• feature này có feature-master chưa
• feature-master có còn khớp với Discovery sync-back note nếu có không
• supporting rule doc có đang trùng vai với feature-master không
• page docs có đang override cross-surface rule không
• idea-flow docs có đang giữ feature truth thay cho file owner không
• AI routing có đang ưu tiên owner docs trước artifact docs không

---

Verification

Lightweight gates

• project_knowledge.py session-audit
• npm run context:lint
• npm run context:guard

Future recommended gate

Khi pattern rollout rộng hơn, nên có thêm một lint/audit nhẹ cho:

• duplicate active feature-master
• active docs thiếu doc_role
• supporting docs không chỉ owner file phía trên

---

Recommended immediate next steps

1. Giữ navigation làm pilot chuẩn.
2. Tạo feature-master cho Identity & Access.
3. Tạo feature-master cho Course Experience.
4. Chỉ tinh chỉnh thêm idea-flow hoặc Discovery tooling nếu rollout thật sự lộ gap mới.
5. Chỉ rollout diện rộng khi 3 pilot trên chứng minh không tạo thêm churn.

---

Long-term verdict

Hướng tối ưu nhất về lâu dài là:

• không chọn giữa traceability và readability,
• mà tách chúng thành các layer rõ ràng,
• rồi thêm feature-master như owner file tối thiểu cho các feature lớn.

Đây là cách ít conflict nhất khi:

• sản phẩm đổi logic nhiều,
• repo tiếp tục lớn lên,
• và AI/contributor cùng viết song song trong thời gian dài.