@educa-corp/fw 0.8.0 → 0.8.1

package/CHANGELOG.md

@@ -3,6 +3,11 @@
 > `fw install` in các mục của những version mới hơn bản đang cài trong dự án.
 > Mỗi lần sửa lệnh, khuôn, bộ câu hỏi hay công cụ đều phải tăng version và thêm một mục ở đây. Test sẽ báo lỗi nếu version chưa có mục.
 
+## 0.8.1 — 2026-10-01
+
+- Hướng dẫn có thêm loại trang **Cách làm** (`.fw/guide/cach-lam/`), gồm các bước làm một việc cụ thể kèm câu gõ mẫu. Trang đầu tiên: **Cách quyết finding sau khi refine** (cho PO / BA).
+- Sửa lỗi `/prd refine`: gọi lại lệnh khi lượt trước **đang chờ PO quyết** thì không rà lại từ đầu nữa, mà trình lại bảng tóm tắt để PO quyết tiếp. Trước bản này, lệnh sẽ chạy lại cả lượt 1, tốn thêm token và sinh ra finding trùng.
+
 ## 0.8.0 — 2026-10-01
 
 - PRD có mục mới **User flow**: các hành trình xuyên suốt nhiều UC, mỗi hành trình gồm một dòng trong bảng và một sơ đồ mermaid, có nhánh lỗi. **Mỗi UC phải có mặt trong ít nhất một hành trình**, `spec_edit flowcheck` kiểm và PRD thiếu User flow thì không duyệt được. PRD đã có: chạy `/prd <EPIC-ID> change thêm User flow`.

package/docs/guide/README.md

@@ -1,7 +1,7 @@
 # Hướng dẫn sử dụng `@educa-corp/fw`
 
 > Framework làm việc với Claude Code: đưa một tính năng đi từ **ý tưởng → làm rõ yêu cầu → PRD → …**, AI hỏi và viết, con người xác nhận ở mỗi bước.
-> Hướng dẫn này viết cho **bản 0.8.0**. Chỉ mô tả những lệnh **đã có**. Lệnh mới có thì hướng dẫn mới được bổ sung.
+> Hướng dẫn này viết cho **bản 0.8.1**. Chỉ mô tả những lệnh **đã có**. Lệnh mới có thì hướng dẫn mới được bổ sung.
 > Trong dự án đã cài framework, bản hướng dẫn đúng với version đang dùng nằm ở **`.fw/guide/`**. Có thể hỏi Claude: *"Đọc .fw/guide và cho biết cách đổi PRD"*.
 
 ---
@@ -13,6 +13,7 @@
 | Cài vào dự án và chạy lần đầu | [Bắt đầu](01-bat-dau.md) |
 | Hiểu vài khái niệm trước khi dùng (UC, BR, AC, 🤖/✅…) | [Khái niệm](02-khai-niem.md) |
 | Biết **vai trò của mình** dùng lệnh nào | [PO / BA](vai-tro/po-ba.md) · *Dev, QC: sắp có* |
+| Làm một việc cụ thể, từng bước, có câu gõ mẫu | **Cách làm:** [Quyết finding sau khi refine](cach-lam/quyet-finding-refine.md) |
 | Tra cứu một lệnh cụ thể | Bảng lệnh ngay bên dưới |
 | Gặp lỗi | [Xử lý sự cố](xu-ly-su-co.md) |
 

package/docs/guide/cach-lam/quyet-finding-refine.md

@@ -0,0 +1,92 @@
+[← Hướng dẫn](../README.md) · [PO / BA](../vai-tro/po-ba.md) · [/prd refine](../lenh/prd-refine.md)
+
+# Cách quyết finding sau khi refine PRD
+
+> **Dành cho:** PO / BA · **Khi nào:** sau khi `/prd EP-xx refine` trình bảng finding · **Mất khoảng:** 30–60 phút với vài chục finding
+> Muốn tra cứu các luật (lượt, mức độ, điều kiện duyệt) thì xem [/prd refine](../lenh/prd-refine.md).
+
+---
+
+## 1. Mở đúng chỗ
+
+Không cần quyết ngay trong phiên vừa rà. Khi đã sẵn sàng:
+
+```
+/clear
+/prd EP-01 refine
+```
+
+Lệnh thấy lượt trước đang chờ bạn quyết. Nó **không rà lại**, chỉ trình lại bảng tóm tắt theo thứ tự F01 → F… (nặng nhất trước).
+
+Mở thêm file chi tiết bên cạnh, ví dụ trong VS Code:
+
+```
+specs/{domain}/{slug}/review/prd-refine.md
+```
+
+Mỗi finding gồm: **Trích** (đoạn PRD liên quan) · **Vấn đề** · **Đề xuất** · **Nếu chốt đề xuất này** (hệ quả có thể phát sinh, chỉ có ở critical và major).
+
+## 2. Quyết theo từng đợt nhỏ, nặng trước
+
+Nên chia thành 4–5 tin nhắn, đừng dồn tất cả vào một lần:
+
+| Đợt | Gõ ví dụ *(minh hoạ)* |
+|---|---|
+| **Critical**: bắt buộc quyết **từng mã** | `nhận F01` |
+| Major nhóm QA | `nhận F02, F04, F05 · F03 sửa thành "hiển thị thông báo 'Email đã tồn tại'" · bác F06 vì AC đã đủ rõ` |
+| Major nhóm DEV | `nhận F07–F15 trừ F11 · hoãn F11` |
+| Major nhóm SA, Phạm vi | Như trên, quyết từng phần |
+| **Minor** | `nhận tất cả minor` |
+
+Quyết theo nhóm thì Claude **liệt kê lại đúng các mã** sẽ bị áp và hỏi *"Đúng chưa?"*. Kiểm danh sách đó trước khi trả lời "đúng".
+
+## 3. Chọn quyết định nào
+
+| Quyết định | Dùng khi | Lưu ý |
+|---|---|---|
+| `nhận` | Đồng ý cả vấn đề lẫn đề xuất | AI sửa PRD đúng theo đề xuất |
+| `sửa: …` | Đồng ý là có vấn đề, nhưng muốn sửa **theo cách khác** | Ghi rõ cách của bạn, càng cụ thể càng tốt |
+| `bác vì …` | Finding **sai**, **thừa**, hoặc PRD đã trả lời ở chỗ khác | **Luôn ghi lý do.** Lý do được lưu vào sổ quyết định, lần rà sau sẽ không nêu lại |
+| `hoãn` | Đúng là có vấn đề, nhưng **để bước sau** xử lý (giao diện, kỹ thuật, chưa đủ thông tin) | Được ghi vào "Câu hỏi còn mở" của PRD, kèm chú thích "để bước QC" |
+
+**Phân biệt bác và hoãn:** finding **không đúng** thì `bác`. Finding **đúng nhưng chưa phải lúc** thì `hoãn`.
+
+## 4. Chưa hiểu thì hỏi trước
+
+```
+F18 nghĩa là gì? Cho ví dụ tình huống cụ thể.
+F07 và F12 có trùng nhau không?
+Nếu nhận F21 thì UC nào bị sửa?
+```
+
+Claude giải thích **mà không sửa gì**. Chỉ khi bạn gõ quyết định thì mới có thay đổi.
+
+## 5. Cách khác: ghi thẳng vào file
+
+Sửa các dòng `- Quyết định: chờ` trong `prd-refine.md`, ví dụ:
+
+```
+- Quyết định: nhận
+- Quyết định: sửa: khoá 30 phút thay vì 15 phút
+- Quyết định: bác: đã có ở UC-002-BR03
+- Quyết định: hoãn
+```
+
+Xong thì gõ: `Tôi đã ghi quyết định vào file, đọc và áp giúp.`
+
+Cách này hợp khi bạn muốn đọc kỹ từng finding, hoặc cần hỏi ý người khác trước khi quyết.
+
+## 6. Sau khi quyết xong
+
+Khi mọi critical và major đã có quyết định:
+1. Claude áp các finding `nhận` và `sửa` vào PRD, tăng version (ví dụ 1.2 → 1.3), ghi Lịch sử thay đổi.
+2. Bảng **Tóm tắt** trong `prd-refine.md` có thêm số **nhận · sửa · bác · hoãn**.
+3. Claude nhắc `/clear` rồi `/prd EP-01 refine` để chạy **lượt 2**. Lượt này chỉ soi phần vừa sửa, nhanh hơn nhiều.
+
+Minor không bắt buộc phải quyết. Minor còn `chờ` vẫn duyệt PRD được.
+
+## Mẹo
+
+- **Thấy finding sai hoặc thừa thì `bác` và ghi lý do, đừng bỏ qua.** Tỉ lệ bác cho người phụ trách framework biết bước kiểm chứng của AI có làm tốt không.
+- Nhiều finding cùng nói về một UC thì quyết chúng **cùng lúc**, để các bản sửa không giẫm lên nhau.
+- Đang quyết dở mà phải dừng thì cứ dừng. Quyết định nào đã ghi thì đã được lưu. Lần sau gọi lại lệnh là tiếp tục từ chỗ còn `chờ`.

package/docs/guide/lenh/prd-refine.md

@@ -41,21 +41,9 @@ Khi bạn quyết xong, bảng Tóm tắt trong `prd-refine.md` ghi số **nhậ
 
 ## Bạn quyết thế nào
 
-AI trình bảng tóm tắt, **sắp theo mức độ** (critical → major → minor), rồi **theo lăng kính** (QA → DEV → SA → Phạm vi). Mã F đánh theo đúng thứ tự đó, nên F01 luôn là finding nặng nhất. Chi tiết từng finding nằm trong `review/prd-refine.md`.
+> Cách làm từng bước, kèm câu gõ mẫu và mẹo: **[Cách quyết finding sau khi refine](../cach-lam/quyet-finding-refine.md)**.
 
-Quyết theo mã:
-
-```
-nhận F01, F03 · bác F02 vì đã có ở UC-002 · F04 sửa thành "khoá 30 phút" · hoãn F05
-```
-
-Hoặc **quyết theo nhóm**, áp cho major và minor:
-
-```
-nhận tất cả minor · nhận hết UC-003 trừ F12 · bác F20–F24 vì đã có ở epic khác
-```
-
-Quyết theo nhóm thì AI **liệt kê lại đúng các mã** sẽ bị áp rồi hỏi bạn xác nhận. **Critical luôn phải quyết từng mã.**
+AI trình bảng tóm tắt, **sắp theo mức độ** (critical → major → minor), rồi **theo lăng kính** (QA → DEV → SA → Phạm vi). Mã F đánh theo đúng thứ tự đó, nên F01 luôn là finding nặng nhất. Chi tiết từng finding nằm trong `review/prd-refine.md`. Gọi lại lệnh khi lượt trước đang chờ quyết thì lệnh **không rà lại**, chỉ trình lại bảng tóm tắt.
 
 | Quyết định | Kết quả |
 |---|---|
@@ -64,7 +52,8 @@ Quyết theo nhóm thì AI **liệt kê lại đúng các mã** sẽ bị áp r
 | `bác: <lý do>` | Không sửa. Lần rà sau **không nêu lại** điểm này |
 | `hoãn` | Không sửa lúc này. Được ghi vào "Câu hỏi còn mở" của PRD để bước QC xử lý |
 
-Bác hay hoãn đều tính là **đã quyết**. Chỉ cần mọi critical và major đều đã có quyết định là đi tiếp được.
+- Quyết được **theo mã** hoặc **theo nhóm** (chỉ cho major và minor). **Critical phải quyết từng mã.**
+- Bác hay hoãn đều tính là **đã quyết**. Mọi critical và major đã có quyết định là đi tiếp được. Minor còn `chờ` không chặn.
 
 ## Vì sao chỉ có 2 lượt
 

package/docs/guide/vai-tro/po-ba.md

@@ -20,6 +20,12 @@
 | 4 | `/prd EP-xx refine` | Quyết từng finding: nhận, sửa, bác hay hoãn. Tối đa 2 lượt. Xong thì duyệt PRD | [/prd refine](../lenh/prd-refine.md) |
 | 5 | `/prd EP-xx change …` | Khi yêu cầu đổi. Duyệt kế hoạch thay đổi, refine lại phần vừa đổi, rồi duyệt lại PRD | [/prd](../lenh/prd.md#đổi-prd-prd-ep-01-change-mô-tả) |
 
+## Cách làm thường gặp
+
+| Việc | Hướng dẫn |
+|---|---|
+| Quyết vài chục finding sau khi refine PRD | [Cách quyết finding sau khi refine](../cach-lam/quyet-finding-refine.md) |
+
 ## Mẹo
 
 - **Có tài liệu thì dán vào ngay lượt đầu.** AI trích trước, bạn chỉ xác nhận. Nhưng AI vẫn sẽ hỏi những gì tài liệu **chưa nói**.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@educa-corp/fw",
-  "version": "0.8.0",
+  "version": "0.8.1",
   "description": "Framework làm việc với Claude Code cho phòng PTPM",
   "bin": {
     "fw": "bin/fw.js"

package/ref/prd/refine.md

@@ -11,8 +11,11 @@ Chạy `SE upgrade D` trước. Lệnh này bổ sung trường và mục còn t
 
 Đọc frontmatter của `D` (`version`, `refined`) và của `R` (nếu có: `prd_version`, `round`).
 
+Xét **từ trên xuống**, gặp dòng nào khớp trước thì theo dòng đó.
+
 | Tình huống | Lượt | Phạm vi |
 |---|---|---|
+| `R` có `status: pending` (đã rà xong, **đang chờ PO quyết**) | **Không rà lại.** Sang thẳng **Bước C** để trình lại bảng tóm tắt từ `R`, rồi Bước D | — |
 | `refined` = `version` | **Dừng.** Báo *"Bản v{version} đã refine xong."* Có `--full` thì chạy lượt 1 trên toàn PRD | — |
 | Chưa có `R`, hoặc chưa từng refine | **1** | Toàn bộ PRD |
 | `R` có `round: 1` **đã áp** bản sửa, `prd_version` < `version` | **2** | Chỉ các mục mà lượt 1 đã sửa hoặc thêm (đọc từ quyết định `nhận` / `sửa` trong `R`), cộng các mục tham chiếu tới chúng |