Issue Discovery Report Generator
Overview
Skill này tạo file .docx chuyên nghiệp theo format Issue Discovery Report, phục vụ
quy trình phát hiện và báo cáo bug/missing case ngoài scope. Report được thiết kế để
cả BA và Dev đều đọc hiểu, có thể đưa lên Confluence để review, approve/reject, và
tạo Jira ticket.
Khi nào dùng skill này
- Phát hiện bug/lỗi nằm ngoài scope hiện tại
- Phát hiện missing case, edge case chưa được BA cover
- Muốn document vấn đề kỹ thuật để team review
- Tạo evidence cho performance review
Workflow
Step 1: Thu thập thông tin từ user
Hỏi user các thông tin sau (bỏ qua những gì đã có trong context):
Bắt buộc:
- Tóm tắt vấn đề: Mô tả ngắn gọn bug/issue là gì?
- Module/Service: Thuộc module nào? (VD: Compute Engine, Network, IAM...)
- Expected vs Actual: Hệ thống nên làm gì vs đang làm gì?
- Severity: Critical / Major / Minor / Suggestion
Tùy chọn (hỏi thêm nếu cần):
5. Môi trường (DEV/STG/PRD)
6. Steps to reproduce
7. Evidence (screenshot, log, API response)
8. Đánh giá ảnh hưởng (ai bị ảnh hưởng, tần suất, workaround)
9. Đề xuất giải pháp
10. Liên quan đến module/ticket nào khác
Step 2: Xác định Report ID
Format: BDR-YYYY-NNN
- YYYY = năm hiện tại
- NNN = số thứ tự (hỏi user hoặc dùng 001 nếu chưa biết)
Step 3: Generate Report
Đọc file template tại scripts/generate-report.js trong thư mục skill này,
sau đó tùy chỉnh nội dung theo thông tin user cung cấp.
# Install dependency
npm install -g docx
# Copy template ra working directory và sửa nội dung
cp <skill-path>/scripts/generate-report.js /home/claude/generate-report.js
Chỉnh sửa file JS với nội dung thực tế, sau đó chạy:
cd /home/claude && node generate-report.js
python <skill-path>/../../public/docx/scripts/office/validate.py /home/claude/<output-file>.docx
Step 4: Deliver
Copy file sang /mnt/user-data/outputs/ và dùng present_files để gửi cho user.
Report Structure (11 sections)
Mỗi report PHẢI có đủ các section sau. Đọc references/report-structure.md để xem
chi tiết format và hướng dẫn viết từng section.
| # |
Section |
Ai đọc |
Ghi chú |
| 1 |
Thông tin cơ bản |
Tất cả |
ID, ngày, reporter, module, severity |
| 2 |
Tóm tắt vấn đề |
Tất cả |
Highlight box, expected vs actual |
| 3 |
Background/Giải thích |
BA |
Giải thích kỹ thuật bằng ngôn ngữ đơn giản, bảng ví dụ |
| 4 |
Phân tích chi tiết |
Dev + BA |
So sánh cũ vs mới, bảng color-coded |
| 5 |
Edge case |
Dev + BA |
Scenario cụ thể với số liệu |
| 6 |
Đề xuất giải pháp |
Tất cả |
Tách theo hướng: Backend, Frontend/UX, Infra |
| 7 |
Bảng tóm tắt logic |
Dev |
Quick reference table |
| 8 |
Đánh giá ảnh hưởng |
BA + Lead |
Ảnh hưởng user, tần suất, workaround |
| 9 |
Data source |
Dev |
API endpoint, field reference |
| 10 |
Action Items |
Tất cả |
Bảng action, owner, platform, priority |
| 11 |
Review & Quyết định |
BA + Lead |
Status, reviewer, Jira ticket |
Nguyên tắc quan trọng:
- Section 3 (Background) phải viết sao cho BA không có kiến thức kỹ thuật sâu cũng hiểu
- Code example chỉ dùng pseudocode ngắn gọn, KHÔNG paste full implementation
- Dùng bảng và color code (đỏ = sai/nguy hiểm, xanh = đúng/ok, cam = cảnh báo)
- Highlight box cho thông tin quan trọng nhất
- Nếu issue liên quan nhiều platform (VMware, OpenStack...), tách giải pháp theo platform
Styling Guide
Đọc references/report-structure.md phần "Styling Constants" để lấy chính xác
color codes, font sizes, và component helpers dùng trong docx-js.
Severity Definitions
| Level |
Khi nào dùng |
| Critical |
Mất dữ liệu, sập hệ thống, ảnh hưởng bảo mật, không có workaround |
| Major |
Chức năng chính bị ảnh hưởng, có workaround nhưng phiền phức |
| Minor |
Lỗi nhỏ, UI/UX không đúng, edge case ít gặp |
| Suggestion |
Không phải bug, nhưng có thể cải thiện (missing case, UX improvement) |
Tips
- Nếu user chỉ mô tả ngắn gọn, vẫn tạo report đầy đủ — điền những gì biết,
đánh dấu placeholder cho phần chưa có
- Report nên self-contained: người đọc không cần context bên ngoài để hiểu vấn đề
- Luôn có section Action Items với owner rõ ràng — đây là phần quan trọng nhất
để chuyển từ report sang Jira ticket
- File output đặt tên theo format:
BDR-YYYY-NNN-<short-slug>.docx
1---2name: issue-discovery-report3description: Tạo tài liệu Issue Discovery Report (.docx) khi phát hiện bug, missing case, hoặc vấn đề nằm ngoài scope trong quá trình phát triển phần mềm. Sử dụng skill này khi user muốn tạo report cho bug/issue/lỗi mới phát hiện, viết báo cáo phát hiện lỗi, tạo BDR (Bug Discovery Report), document missing case hoặc edge case, tạo report để BA/Dev review, hoặc bất kỳ khi nào user đề cập "tạo report lỗi", "phát hiện bug", "missing case", "issue report", "BDR", "discovery report". Cũng trigger khi user nói "tạo report như template", "report theo format cũ", hoặc muốn document vấn đề kỹ thuật để team review.4---56# Issue Discovery Report Generator78## Overview910Skill này tạo file `.docx` chuyên nghiệp theo format Issue Discovery Report, phục vụ11quy trình phát hiện và báo cáo bug/missing case ngoài scope. Report được thiết kế để12cả BA và Dev đều đọc hiểu, có thể đưa lên Confluence để review, approve/reject, và13tạo Jira ticket.1415## Khi nào dùng skill này1617- Phát hiện bug/lỗi nằm ngoài scope hiện tại18- Phát hiện missing case, edge case chưa được BA cover19- Muốn document vấn đề kỹ thuật để team review20- Tạo evidence cho performance review2122## Workflow2324### Step 1: Thu thập thông tin từ user2526Hỏi user các thông tin sau (bỏ qua những gì đã có trong context):2728**Bắt buộc:**291. **Tóm tắt vấn đề**: Mô tả ngắn gọn bug/issue là gì?302. **Module/Service**: Thuộc module nào? (VD: Compute Engine, Network, IAM...)313. **Expected vs Actual**: Hệ thống nên làm gì vs đang làm gì?324. **Severity**: Critical / Major / Minor / Suggestion3334**Tùy chọn (hỏi thêm nếu cần):**355. Môi trường (DEV/STG/PRD)366. Steps to reproduce377. Evidence (screenshot, log, API response)388. Đánh giá ảnh hưởng (ai bị ảnh hưởng, tần suất, workaround)399. Đề xuất giải pháp4010. Liên quan đến module/ticket nào khác4142### Step 2: Xác định Report ID4344Format: `BDR-YYYY-NNN`45- YYYY = năm hiện tại46- NNN = số thứ tự (hỏi user hoặc dùng 001 nếu chưa biết)4748### Step 3: Generate Report4950Đọc file template tại `scripts/generate-report.js` trong thư mục skill này,51sau đó **tùy chỉnh nội dung** theo thông tin user cung cấp.5253```bash54# Install dependency55npm install -g docx5657# Copy template ra working directory và sửa nội dung58cp <skill-path>/scripts/generate-report.js /home/claude/generate-report.js59```6061Chỉnh sửa file JS với nội dung thực tế, sau đó chạy:6263```bash64cd /home/claude && node generate-report.js65python <skill-path>/../../public/docx/scripts/office/validate.py /home/claude/<output-file>.docx66```6768### Step 4: Deliver6970Copy file sang `/mnt/user-data/outputs/` và dùng `present_files` để gửi cho user.7172## Report Structure (11 sections)7374Mỗi report PHẢI có đủ các section sau. Đọc `references/report-structure.md` để xem75chi tiết format và hướng dẫn viết từng section.7677| # | Section | Ai đọc | Ghi chú |78|---|---------|--------|---------|79| 1 | Thông tin cơ bản | Tất cả | ID, ngày, reporter, module, severity |80| 2 | Tóm tắt vấn đề | Tất cả | Highlight box, expected vs actual |81| 3 | Background/Giải thích | BA | Giải thích kỹ thuật bằng ngôn ngữ đơn giản, bảng ví dụ |82| 4 | Phân tích chi tiết | Dev + BA | So sánh cũ vs mới, bảng color-coded |83| 5 | Edge case | Dev + BA | Scenario cụ thể với số liệu |84| 6 | Đề xuất giải pháp | Tất cả | Tách theo hướng: Backend, Frontend/UX, Infra |85| 7 | Bảng tóm tắt logic | Dev | Quick reference table |86| 8 | Đánh giá ảnh hưởng | BA + Lead | Ảnh hưởng user, tần suất, workaround |87| 9 | Data source | Dev | API endpoint, field reference |88| 10 | Action Items | Tất cả | Bảng action, owner, platform, priority |89| 11 | Review & Quyết định | BA + Lead | Status, reviewer, Jira ticket |9091**Nguyên tắc quan trọng:**92- Section 3 (Background) phải viết sao cho BA không có kiến thức kỹ thuật sâu cũng hiểu93- Code example chỉ dùng pseudocode ngắn gọn, KHÔNG paste full implementation94- Dùng bảng và color code (đỏ = sai/nguy hiểm, xanh = đúng/ok, cam = cảnh báo)95- Highlight box cho thông tin quan trọng nhất96- Nếu issue liên quan nhiều platform (VMware, OpenStack...), tách giải pháp theo platform9798## Styling Guide99100Đọc `references/report-structure.md` phần "Styling Constants" để lấy chính xác101color codes, font sizes, và component helpers dùng trong docx-js.102103## Severity Definitions104105| Level | Khi nào dùng |106|-------|-------------|107| **Critical** | Mất dữ liệu, sập hệ thống, ảnh hưởng bảo mật, không có workaround |108| **Major** | Chức năng chính bị ảnh hưởng, có workaround nhưng phiền phức |109| **Minor** | Lỗi nhỏ, UI/UX không đúng, edge case ít gặp |110| **Suggestion** | Không phải bug, nhưng có thể cải thiện (missing case, UX improvement) |111112## Tips113114- Nếu user chỉ mô tả ngắn gọn, vẫn tạo report đầy đủ — điền những gì biết,115 đánh dấu placeholder cho phần chưa có116- Report nên self-contained: người đọc không cần context bên ngoài để hiểu vấn đề117- Luôn có section Action Items với owner rõ ràng — đây là phần quan trọng nhất118 để chuyển từ report sang Jira ticket119- File output đặt tên theo format: `BDR-YYYY-NNN-<short-slug>.docx`
dangtran1003