| name | requirements_analyzer |
| description | Skill phân tích requirement document có sẵn (Google Drive, Docs, Figma, .md, .doc, Backlog ticket) — hướng dẫn cách đọc, extract AC, và phát hiện ambiguities. |
Requirements Analyzer
Mục tiêu
Hướng dẫn AI cách đọc và phân tích requirement document có sẵn (Google Drive, Docs, Figma, .md, .doc, Backlog ticket) — không phải tự sinh requirements từ UI.
Nguyên tắc cốt lõi
- Đọc kỹ trước khi phân tích — đọc toàn bộ document, kể cả comments và attachments
- Không tự đoán business logic — những gì không được ghi rõ trong document → đưa vào Ambiguities
- AC do PM tạo — QC đọc, confirm và map AC vào requirements, không tự sinh AC mới
- Ưu tiên độ chính xác — thà hỏi clarify hơn là giả định sai
Kỹ thuật phân tích
1. Đọc hiểu scope
- Xác định rõ: tính năng này thêm mới, chỉnh sửa, hay xóa behavior hiện tại?
- Các module/page nào bị ảnh hưởng — trực tiếp và gián tiếp?
- Ai là actor? (user thường, admin, hệ thống tự động?)
2. Map AC vào Requirements
Với mỗi REQ trong document:
- Tìm AC tương ứng mà PM đã viết
- Kiểm tra AC đã cover: happy path, negative, edge cases chưa?
- REQ nào thiếu AC → đánh dấu là Ambiguity, không tự bổ sung
3. Phát hiện Ambiguities — dấu hiệu cần tìm
| Dấu hiệu | Ví dụ |
|---|
| Từ khóa mơ hồ | "where applicable", "as needed", "tương tự như", "v.v." |
| Validation thiếu | Không ghi min/max, format, required/optional |
| Behavior edge case chưa mô tả | Mất mạng, dữ liệu trống, concurrent access |
| Inconsistency với mockup | Tên field, format, layout khác nhau |
| Threshold chưa định nghĩa | "tiếp cận deadline" — bao nhiêu ngày? |
| Conflict với requirement cũ | REQ mới mâu thuẫn với behavior hiện tại |
4. Phân biệt Business Rules vs UI Rules
- Business rule: "Tài khoản bị khóa sau 5 lần sai" → test kỹ, ảnh hưởng nghiệp vụ
- UI rule: "Nút Submit disabled khi form chưa đủ dữ liệu" → test validation behavior
5. Đọc dependencies
- Tài liệu phụ thuộc → đọc và tóm tắt
- AC từ tài liệu phụ thuộc có thể ảnh hưởng scope của tài liệu chính
- Ghi rõ rule nào đến từ tài liệu nào
Design Integration
(Áp dụng khi user cung cấp design input: Figma link, screenshot, PDF export design...)
Theo dạng input
| Input | Cách đọc |
|---|
| Screenshot / image | Đọc trực tiếp — cross-check ngay với spec |
| PDF export | Đọc từng trang — cross-check theo từng screen |
| Figma link | Dùng Figma MCP tools — theo quy trình 2 phase bên dưới |
Figma — Quy trình 2 Phase
Áp dụng khi Figma file có nhiều pages hoặc nhiều frames. Mục tiêu: xác định đúng scope trước khi đọc sâu — tránh bỏ sót screen và tránh đọc nhầm vào archive/draft.
Phase 1 — Scope Mapping (có checkpoint)
- Gọi
get_pages → list tất cả pages trong file
- Hỏi user:
Figma file có [N] pages: [danh sách tên]. Pages nào liên quan đến feature đang phân tích? (Bỏ qua Archive, Draft, hoặc pages không liên quan)
- Chờ user confirm pages
- Với các pages được confirm: gọi
scan_nodes_by_types với type FRAME → list top-level frames
- Hỏi user:
Tôi thấy [N] frames: [danh sách tên]. Frames nào là screens của feature này?
- Chờ user confirm frames → đây là scope chính thức cho Phase 2
Phase 2 — Deep Read (chỉ trong scope đã confirm)
Với mỗi frame được confirm:
- Gọi
get_node để đọc nội dung frame
- Tìm
COMPONENT_SET nodes — đây là nơi Figma lưu state variants:
- Tìm nodes có tên chứa keyword:
State=, Status=, Type=, Variant=, Mode=
- Ví dụ phổ biến:
State=Error, State=Loading, State=Disabled, Status=Active
- Gọi
get_annotations để đọc annotations và developer notes
- Cross-check với spec theo bảng bên dưới
Cross-check Checklist
| Thứ cần kiểm tra | Cách làm | Nếu không khớp |
|---|
| Screen inventory | Frames đã confirm vs sections trong spec | Frame có trong design nhưng không có trong spec → thêm AMB item |
| UI states | COMPONENT_SET variants vs states được mô tả trong spec | State có trong design (State=Error) nhưng spec không mô tả behavior → thêm AMB item |
| Field names | Label text trong frame vs tên field trong spec | Naming khác nhau → thêm AMB item, KHÔNG tự chọn cái nào đúng |
| Business rules ẩn | Annotations / developer notes trong frame | Annotation chứa rule chưa có trong spec → ghi chú vào AC context |
Figma Findings chỉ bổ sung thêm AMB items — không thay thế hay override phân tích từ spec text.
Những gì KHÔNG làm
- ❌ Tự sinh AC khi PM chưa viết → đưa vào Ambiguities
- ❌ Tự đoán business logic khi document không nói rõ
- ❌ Bỏ qua comments hoặc notes đính kèm trong document
- ❌ Giả định inconsistency giữa document và mockup là lỗi typo — ghi rõ để confirm
