Docs Content Placement Implementation Plan

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

Goal: Chốt canonical placement cho các tài liệu trong docs/**, di chuyển file ecosystem overview lệch chỗ rõ nhất, và cập nhật rule/router để AI đọc đúng cấu trúc mới.

Architecture: Giữ docs/Domains/** và docs/Shared/** làm canonical layer. Các folder cũ như docs/Domains/DOL English/Product Discovery/**, docs/Domains/DOL English/Feature Package/**, docs/Shared/Knowledge Base/**, docs/Shared/Design System/** tiếp tục là source bridge trong giai đoạn migrate. Chỉ move các repo-level overview thật sự cross-domain để giảm churn nhưng tăng rõ ràng điều hướng.

Tech Stack: Markdown docs, context router cards (docs/context/*.mdc), repo rules (.agent/rules/*.md), shell verification commands.

---

Task 1: Lock repo-level placement map

Files:

• Create: docs/Domains/DOM_Docs_Content_Placement_Map.md
• Modify: docs/README.md
• Modify: docs/Domains/DOM_Documentation_Guidelines_for_AI.md
• Modify: .agent/rules/rule-domain-split-guard.md

Step 1: Write the placement matrix

• Define placement for each current top-level docs lane:
  • docs/Domains/** = canonical domain workspaces
  • docs/Shared/** = canonical shared workspaces
  • docs/Domains/DOL English/Product Discovery/**, docs/Domains/DOL English/Feature Package/**, docs/Shared/Knowledge Base/**, docs/Shared/Design System/** = source bridge / legacy source / shared canon source
  • docs/context/**, docs/plans/**, docs/tmp/**, docs/Command/**, docs/Shared/Operations/** = support layers
• Mark whether each lane is canonical, source bridge, support, or artifact.

Step 2: Sync the map into onboarding and AI routing docs

• Update docs/README.md default placement section.
• Update docs/Domains/DOM_Documentation_Guidelines_for_AI.md to point to the new map.
• Update .agent/rules/rule-domain-split-guard.md so placement decisions reference the map first.

Step 3: Review for duplication

• Remove wording that conflicts with the new placement map.

Task 2: Move the ecosystem-level UX overview into the correct shared lane

Files:

• Create: docs/Shared/Shared Capabilities/Ecosystem Experience/SHR_ECOSYSTEM_UX_00_Overview.md
• Retire: docs/UX Design/UX_00_Overview.md
• Modify: docs/Domains/DOM_UX_Area_To_Domain_Migration_Map.md
• Modify: docs/context/base-context-index.mdc
• Modify: any docs/rules referencing the retired root UX path

Step 1: Split scope cleanly

• Move ecosystem-level narrative and cross-domain principles into the new shared file.
• Remove or downscope DOL English-specific KPI wording from the shared version if it reads like whole-system canon.

Step 2: Preserve a light bridge at the old path

• Remove the old root UX file after all references have been repointed to the shared canonical file.
• Do not keep duplicate long-form content in both places.

Step 3: Update references

• Update maps, router cards, and docs that should now point to the new canonical path.

Task 3: Verify routing and placement behavior

Files:

• Modify if needed: docs/context/*.mdc
• Modify if needed: config/context-routing-benchmark.json

Step 1: Run verification Run:

• npm run context:guard
• npm run context:benchmark
• npm run context:stale

Expected:

• all commands exit 0
• no uncovered canonical docs
• benchmark stays green after the placement changes

Step 2: Self-check against quality rubric

• Correctness: canonical placement matches content semantics
• Requirement coverage: map + rule + moved overview are all updated
• Risk and safety: no large unnecessary physical move of source bridge folders
• Verification evidence: fresh command output
• Maintainability: one clear placement map, no duplicate canon
• Delivery efficiency: minimal set of files changed for maximum routing clarity

Step 3: Run docs commit gate Run:

• npm run docs:commit:preview Then summarize changed count and ask the required blocker question.