docs(agent): thư viện instruction cho việc sửa bug UI/UX

Bộ 7 role chuyên biệt (triage → specialist → implementer → reviewer) cùng
lớp dùng chung: guardrail, tri thức về repo, checklist, và contract đầu ra.

Vì sao có: bug UI/UX được báo bằng lời kể triệu chứng, và người sửa hay bỏ
qua ba thứ mà repo này rất dễ vi phạm — luật "không file nào ngoài theme/
được đặt tên một màu", trần LOC theo bánh cóc, và việc ui/ với presentation/
cùng tồn tại nên sửa nhầm file là "đã fix mà vẫn thấy lỗi".

knowledge/qt_pitfalls.md chép lại 20 nguyên nhân gốc hay gặp của bug PySide6;
examples/bad_fix.md có hai ca CÓ THẬT, gồm ca chính bản vá trong nhánh này
từng mắc (compare_digest trên str ngoài ASCII) và lọt qua vòng review đầu.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

agent/checklist/ux_review.md

@@ -0,0 +1,48 @@
+# Checklist review bản vá UX (flow)
+
+Dùng bởi `ux-flow-fixer` (bước 8) và `regression-reviewer`.
+
+## A. Bốn trạng thái
+
+Cho mỗi view có dữ liệu bất đồng bộ:
+
+- [ ] **Rỗng** — hiện thông điệp có nghĩa, nói được bước tiếp theo (không phải màn trắng).
+- [ ] **Đang tải** — có dấu hiệu chuyển động; nút bị vô hiệu hoá để chống bấm đúp.
+- [ ] **Lỗi** — nói *cái gì hỏng* và *làm gì tiếp*; có đường thử lại; không in nguyên exception.
+- [ ] **Thành công** — có xác nhận rõ; có undo nếu hành động khó đảo ngược.
+
+## B. An toàn dữ liệu
+
+- [ ] Ô nhập dài (instruction, composer, node property, AI Edit) không mất nội dung khi
+      chuyển tab / đóng dialog / đổi project.
+- [ ] Có dirty-state; `closeEvent` chặn khi còn thay đổi chưa lưu.
+- [ ] Hành động phá huỷ (xoá project/task, ghi đè file) có xác nhận.
+- [ ] Xác nhận nêu rõ **cái gì** sẽ mất, không phải "Bạn có chắc không?".
+- [ ] Nút phá huỷ **không** phải default button, **không** nhận Enter.
+
+## C. Phản hồi theo thời gian
+
+- [ ] 100ms-1s: đổi con trỏ hoặc vô hiệu hoá nút.
+- [ ] 1s-10s: chỉ báo tiến trình rõ ràng.
+- [ ] \>10s: có tiến trình, **huỷ được**, không chặn phần còn lại của UI.
+- [ ] Việc nặng chạy ở service `application/`, không ở GUI thread.
+- [ ] Bấm hai lần không chạy hai lần (kiểm `connect()` trùng — P10).
+
+## D. Khám phá được
+
+- [ ] Mọi nút icon-only có tooltip (nav rail thu gọn, toolbar Co4E, top bar).
+- [ ] Nút bị vô hiệu hoá nói được **lý do** (mẫu đúng: `app.nav.needs_project`).
+- [ ] Chức năng chính không bị chôn sau menu chuột phải mà không có lối vào khác.
+- [ ] Thứ tự control khớp thứ tự người dùng thực hiện.
+
+## E. Nhất quán
+
+- [ ] Cùng một hành động dùng cùng một từ trên mọi màn (không chỗ "Lưu" chỗ "Cập nhật").
+- [ ] Vị trí nút chính/phụ giống các dialog khác.
+- [ ] Chuỗi mới đi qua `tr()` với đủ `en`/`ja`/`vi`.
+
+## F. Phạm vi
+
+- [ ] Bản vá chọn mức can thiệp thấp nhất (thêm thông tin trước, đổi luồng sau).
+- [ ] Thay đổi luồng được đánh dấu là **đề xuất** cần Cowork Team duyệt.
+- [ ] Có test regression cho signal/state, chạy headless.