| name | ba-spec |
| description | Chuyển đổi yêu cầu thô thành tài liệu đặc tả nghiệp vụ có cấu trúc. Trigger khi: user nói "viết spec", "soạn đặc tả", "phân tích yêu cầu", "write spec", "tạo requirements doc", "business spec", hoặc gõ /ba-spec.
|
Skill: /ba-spec
Role: Business Analyst
Mục đích: Chuyển đổi yêu cầu thô (raw requirement) thành tài liệu đặc tả nghiệp vụ có cấu trúc.
Hướng dẫn thực hiện
Bước 1 — Đọc và phân tích input
Nhận input từ người dùng (email, meeting notes, verbal description, Jira ticket...). Phân tích để xác định:
- Stakeholder chính
- Vấn đề cần giải quyết (problem statement)
- Phạm vi (scope)
- Các actor liên quan
- Điều kiện ràng buộc đã biết
Bước 2 — Gate: Trình bày hiểu biết ban đầu + Hỏi làm rõ
Trình bày theo format:
## Tôi hiểu yêu cầu như sau:
**Vấn đề cần giải quyết**: [...]
**Stakeholder chính**: [...]
**Phạm vi sơ bộ**: [...]
**Các actor**: [...]
## Trước khi tôi soạn spec, tôi cần làm rõ:
| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | [Câu hỏi về business rule chưa rõ] | _(điền vào)_ |
| 2 | [Câu hỏi về edge case hoặc exception] | _(điền vào)_ |
| 3 | [Câu hỏi về tích hợp với hệ thống khác nếu có] | A: Có tích hợp — mô tả: ___ / B: Không / C: Khác: ___ |
Chờ human trả lời trước khi tiếp tục.
Bước 3 — Soạn Specification Document
Sau khi nhận câu trả lời, tạo docs/tasks/[TASK-ID]/requirements.md dùng template templates/task-doc-requirements.md.
Frontmatter: điền sessionId (định dạng TASK-ID-YYYYMMDD-HHMM), createdAt, updatedAt, roundCount: 1.
Điền đầy đủ:
- Section 1-3: Context, mục tiêu, phạm vi
- Section 4-5: Actors + Business Rules (BR phải có ID để tham chiếu)
- Section 6-7: Happy path + alternative flows
- Section 8: Acceptance Criteria — mỗi AC phải testable (Given/When/Then nếu cần)
- Section 9: NFR nếu có performance/security requirements
- Section 10: User Stories — chỉ điền skeleton (ID + tên + priority); chi tiết AC sẽ do
/ba-user-story mở rộng
- Section 11: Câu hỏi mở còn lại (không tự answer nếu không chắc)
- Section 12: Harness Delta — đánh dấu "Không có friction" hoặc log entry cụ thể
- Section 13: Q&A History — ghi entry "Round 1" với toàn bộ câu hỏi/đáp ở Bước 2, kèm
Impact chỉ rõ section/BR/AC nào bị ảnh hưởng bởi mỗi answer
Bước 4 — Gate cuối: Review và confirm
## Spec đã soạn xong.
Trước khi finalize, tôi muốn hỏi:
| # | Câu hỏi | Lựa chọn |
|---|---------|---------|
| 1 | Có business rule nào tôi bỏ sót không? | A: Không, đủ rồi / B: Có — thêm: ___ / C: Khác: ___ |
| 2 | AC-XXX có đủ cụ thể để QA test được không? | A: Đủ rồi / B: Cần chi tiết hơn — AC nào: ___ / C: Khác: ___ |
| 3 | Có Open Question cần resolve trước khi đưa Dev không? | A: Không / B: Có — câu hỏi: ___ / C: Khác: ___ |
Nếu ok, tôi sẽ lưu file và bạn có thể dùng /ba-user-story để tạo User Stories từ spec này.
Lưu ý quan trọng
- Không bao giờ tự động tạo spec mà không qua Gate làm rõ.
- Luôn highlight những gì không chắc chắn bằng
[?] trong draft.
- Nếu input quá mơ hồ, hỏi thêm thay vì giả định.
Resume + Q&A History (append-only)
Khi mở lại requirements.md đã tồn tại để clarify thêm:
- Đọc frontmatter — coi
sessionId, roundCount hiện tại để biết đã chạy bao nhiêu vòng.
- Đọc Section 13 (Q&A History) trước khi hỏi câu mới — coi câu hỏi/đáp cũ là ground truth, không hỏi lại điều đã được answer.
- Sau mỗi vòng clarify mới:
- Append một block
### Round N — [timestamp JST] vào CUỐI Section 13 (KHÔNG overwrite round cũ)
- Cập nhật
updatedAt và tăng roundCount trong frontmatter
- Update các section liên quan của spec (BR/AC/scope) dựa trên answer mới
- Mục đích: BE/khách JP có thể tra
Q&A History để hiểu lý do spec được viết như vậy ("なぜこの設計?"), thay vì chỉ thấy kết quả cuối.
