plan

name: plan description: Tạo file kế hoạch trong `docs/specs/planning/` cho công việc lớn, rồi chờ user phê duyệt trước khi sửa code. Trigger: lập plan, viết spec, đề xuất thiết kế, refactor lớn.

Dùng sau research khi yêu cầu lớn, phức tạp, liên quan kiến trúc hoặc rủi ro. Công việc nhỏ và rõ ràng có thể bỏ qua.

Quy tắc chung: đọc _shared/CONVENTIONS.md.

Viết kế hoạch bằng tiếng Việt có dấu. Pha tiếng Anh chỉ cho tên riêng, thuật ngữ kỹ thuật, tên API/module/field.
Viết như tài liệu thiết kế, không như changelog hay nhật ký Git.
Thêm Mermaid khi cấu trúc, luồng dữ liệu, quan hệ module khó hiểu bằng chữ.

Tìm nguyên nhân gốc rễ trước: Kế hoạch phải thể hiện vì sao vấn đề tồn tại, phân biệt triệu chứng vs nguyên nhân gốc rễ.
Nhìn tổng quát, giữ trọng tâm: Bao quát context, module boundary, contract, rủi ro; chỉ đề xuất công việc trong phạm vi mục tiêu.

docs/specs/planning/<kebab-case-name>.md

Khi user yêu cầu tạo plan từ branch/commit:

Dùng lệnh chỉ đọc: git merge-base, git log, git diff --stat, git diff, git show. Không switch branch.
Không đưa vào plan: tên branch, hash commit, danh sách commit, tác giả, "files changed" table.
Chuyển hóa thành: mục tiêu thiết kế, cấu trúc giải pháp, module boundary, logic nghiệp vụ, rủi ro, kiểm chứng.

Đảm bảo research đã xác định docs/specs, code path, ràng buộc. Dùng lsp-code-graph khi cần symbol/caller/callee context.
Làm rõ nguyên nhân gốc rễ và động lực thiết kế.
Xác định bức tranh tổng quan rồi thu hẹp: module boundary, data flow, API/contract, vùng ảnh hưởng, ngoài phạm vi.
Nếu từ branch/commit, đọc thay đổi bằng Git chỉ đọc.
Tạo file kế hoạch trong docs/specs/planning/ theo mẫu _shared/templates/plan-template.md.
Trình bày tóm tắt kế hoạch cô đọng bằng tiếng Việt.
Dừng lại và chờ user phê duyệt trước khi sửa code.