@educa-corp/sdd-framework 0.7.5 → 0.8.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/core/FRAMEWORK_VERSION +1 -1
- package/docs/explain/03-refine-prd.md +86 -86
- package/package.json +1 -1
package/core/FRAMEWORK_VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.
|
|
1
|
+
0.8.0
|
|
@@ -1,86 +1,86 @@
|
|
|
1
|
-
[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
|
|
2
|
-
|
|
3
|
-
# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
|
|
4
|
-
|
|
5
|
-
> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
|
|
6
|
-
|
|
7
|
-
---
|
|
8
|
-
|
|
9
|
-
## Vấn đề giải quyết
|
|
10
|
-
|
|
11
|
-
Một lượt review đơn không bao giờ liệt kê hết vấn đề — model dừng ở mức "đủ", nên mỗi vòng sau lại lòi lỗi mới (**đập chuột chũi**). `/refine-prd` ép review **hội tụ trong một lần chạy**, bắt lỗi nghiệp vụ *trước* khi truyền xuống BDD, giữ altitude & ngôn ngữ nghiệp vụ.
|
|
12
|
-
|
|
13
|
-
---
|
|
14
|
-
|
|
15
|
-
## Vị trí & tiền đề
|
|
16
|
-
|
|
17
|
-
- **Vị trí:** Phase Specification (sau `/generate-prd`).
|
|
18
|
-
- **Tiền đề:** có PRD draft.
|
|
19
|
-
- **Đặc biệt:** có **Resume Mode** (`--resume`) áp findings đã accept và bump version PRD.
|
|
20
|
-
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
## Input / Output
|
|
24
|
-
|
|
25
|
-
**Input:** PRD + core-entities + business-dictionary.
|
|
26
|
-
|
|
27
|
-
**Output:** `{refinement_dir}/{prd-slug}-findings.yaml` — findings với `lens` (DEV/SA/PO), severity, `quote`+`uc_id` (để Review Board jump-to-source), `suggestion`, `resolution_edge_cases`, `status`.
|
|
28
|
-
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
## Các bước xử lý (chi tiết)
|
|
32
|
-
|
|
33
|
-
Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
|
|
34
|
-
|
|
35
|
-
### Phase 1 — Fan-out song song theo dimension
|
|
36
|
-
- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
|
|
37
|
-
| Lăng kính | Soi gì |
|
|
38
|
-
|-----------|--------|
|
|
39
|
-
| **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
|
|
40
|
-
| **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
|
|
41
|
-
| **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
|
|
42
|
-
- ⚠️ **Nguyên tắc DEV & SA: đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ** — chỉ nêu *cái nghiệp vụ còn thiếu/mơ hồ* + đặt câu hỏi làm rõ; KHÔNG đề xuất cơ chế kỹ thuật.
|
|
43
|
-
- `GRANULARITY = per-uc` → luôn fan-out `DIMENSION × UC` (+ phạm vi PRD-global), bỏ ngưỡng cả-file → **lần đầu quét sâu**. Agent cap = 12/wave, gom batch UC nếu vượt.
|
|
44
|
-
|
|
45
|
-
### Phase 2 — Vòng lặp completeness-critic
|
|
46
|
-
- Spawn một critic đọc **toàn PRD** + danh sách findings đã có (slim) → liệt kê **chỉ vấn đề mới** (gap, mâu thuẫn, edge/negative path thiếu, **vi phạm altitude/role-boundary**: cơ chế nằm trong AC, AC lặp lại BR…).
|
|
47
|
-
- Lặp tới khi **2 vòng liên tiếp 0 finding mới** hoặc cap **3 vòng**. Ghi `convergence_rounds`.
|
|
48
|
-
|
|
49
|
-
### Phase 3 — Dedup / xung đột / merge
|
|
50
|
-
- Khử trùng (giữ suggestion phong phú hơn, severity cao hơn); merge được thì merge, loại trừ nhau → một finding `needs_discussion`; sắp theo severity; gán ID `F001…`; map dimension → `lens`; ghi **một** file findings.
|
|
51
|
-
|
|
52
|
-
### Full vs Delta
|
|
53
|
-
- Lần đầu (chưa có findings file) → **FULL**. Lần sau so `prd_version`: chưa đổi → DỪNG; đổi do chính resume này (`applied_to_version` khớp) → **DELTA** (chỉ UC đã đổi + UC mới); đổi bởi actor khác → **FULL** + cảnh báo.
|
|
54
|
-
|
|
55
|
-
### Resume Mode (`--resume`)
|
|
56
|
-
- Áp finding theo `status` (`accepted`/`modified`), bump version PRD, ghi `applied_to_version`. `needs_discussion` chặn resume tới khi người quyết.
|
|
57
|
-
|
|
58
|
-
---
|
|
59
|
-
|
|
60
|
-
## Checkpoint & Gate
|
|
61
|
-
|
|
62
|
-
- 🛑 **Review Board** — PO accept/reject/modify **từng** finding (không auto-apply). Finding lifecycle: `pending → accepted|modified|rejected|needs_discussion|deferred → applied`.
|
|
63
|
-
- `recommendation`: critical≥1 → `BLOCKED`; major≥1 → `NEEDS_REVISION`; else `APPROVED_WITH_MINOR_CHANGES`.
|
|
64
|
-
|
|
65
|
-
---
|
|
66
|
-
|
|
67
|
-
## Cơ chế đặc biệt
|
|
68
|
-
|
|
69
|
-
- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
|
|
70
|
-
- **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
|
|
71
|
-
- **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
|
|
72
|
-
|
|
73
|
-
---
|
|
74
|
-
|
|
75
|
-
## 👓 Góc nhìn tối ưu
|
|
76
|
-
|
|
77
|
-
- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
|
|
78
|
-
- **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
|
|
79
|
-
- **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
|
|
80
|
-
- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
|
|
81
|
-
|
|
82
|
-
---
|
|
83
|
-
|
|
84
|
-
## Kết nối
|
|
85
|
-
|
|
86
|
-
**Trước:** [`/generate-prd`](02-generate-prd.md) hoặc [`/extend-prd`](02b-extend-prd.md) · **Sau:** mở Review Board → cập nhật PRD → [`/review-context`](04-review-context.md).
|
|
1
|
+
[← /extend-prd](02b-extend-prd.md) · [Explain Home](README.md) · [Next: /review-context →](04-review-context.md)
|
|
2
|
+
|
|
3
|
+
# 03 · `/refine-prd` — Tinh chỉnh PRD qua 3 lăng kính
|
|
4
|
+
|
|
5
|
+
> **Một câu.** Fan-out review PRD qua **3 lăng kính DEV / SA / PO**, chạy **vòng lặp completeness-critic** để hội tụ đầy đủ trong một lần, rồi sinh file findings cho PO accept/reject ở Review Board.
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Vấn đề giải quyết
|
|
10
|
+
|
|
11
|
+
Một lượt review đơn không bao giờ liệt kê hết vấn đề — model dừng ở mức "đủ", nên mỗi vòng sau lại lòi lỗi mới (**đập chuột chũi**). `/refine-prd` ép review **hội tụ trong một lần chạy**, bắt lỗi nghiệp vụ *trước* khi truyền xuống BDD, giữ altitude & ngôn ngữ nghiệp vụ.
|
|
12
|
+
|
|
13
|
+
---
|
|
14
|
+
|
|
15
|
+
## Vị trí & tiền đề
|
|
16
|
+
|
|
17
|
+
- **Vị trí:** Phase Specification (sau `/generate-prd`).
|
|
18
|
+
- **Tiền đề:** có PRD draft.
|
|
19
|
+
- **Đặc biệt:** có **Resume Mode** (`--resume`) áp findings đã accept và bump version PRD.
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Input / Output
|
|
24
|
+
|
|
25
|
+
**Input:** PRD + core-entities + business-dictionary.
|
|
26
|
+
|
|
27
|
+
**Output:** `{refinement_dir}/{prd-slug}-findings.yaml` — findings với `lens` (DEV/SA/PO), severity, `quote`+`uc_id` (để Review Board jump-to-source), `suggestion`, `resolution_edge_cases`, `status`.
|
|
28
|
+
|
|
29
|
+
---
|
|
30
|
+
|
|
31
|
+
## Các bước xử lý (chi tiết)
|
|
32
|
+
|
|
33
|
+
Chạy qua step **review-fanout** với tham số `GRANULARITY = per-uc`:
|
|
34
|
+
|
|
35
|
+
### Phase 1 — Fan-out song song theo dimension
|
|
36
|
+
- **DIMENSIONS = 3 lăng kính** (mỗi lăng kính một sub-agent, context window mới, quét toàn PRD chỉ qua lăng kính đó):
|
|
37
|
+
| Lăng kính | Soi gì |
|
|
38
|
+
|-----------|--------|
|
|
39
|
+
| **DEV** (cơ chế nghiệp vụ) | BR + Business Logic đã đủ & không mơ hồ để build không phải đoán chưa? Nhánh nghiệp vụ thiếu, điều kiện biên, đường lỗi bỏ ngỏ |
|
|
40
|
+
| **SA** (thông suốt & nhất quán) | Luồng nghiệp vụ thông suốt trên cả feature/domain? Tương tác UC, quan hệ entity, vòng đời trạng thái, ai-làm-gì |
|
|
41
|
+
| **PO** | Scope khoanh vùng? Priority? Success metric? Rủi ro scope creep? |
|
|
42
|
+
- ⚠️ **Nguyên tắc DEV & SA: đọc bằng mắt kỹ thuật, VIẾT bằng lời nghiệp vụ** — chỉ nêu *cái nghiệp vụ còn thiếu/mơ hồ* + đặt câu hỏi làm rõ; KHÔNG đề xuất cơ chế kỹ thuật.
|
|
43
|
+
- `GRANULARITY = per-uc` → luôn fan-out `DIMENSION × UC` (+ phạm vi PRD-global), bỏ ngưỡng cả-file → **lần đầu quét sâu**. Agent cap = 12/wave, gom batch UC nếu vượt.
|
|
44
|
+
|
|
45
|
+
### Phase 2 — Vòng lặp completeness-critic
|
|
46
|
+
- Spawn một critic đọc **toàn PRD** + danh sách findings đã có (slim) → liệt kê **chỉ vấn đề mới** (gap, mâu thuẫn, edge/negative path thiếu, **vi phạm altitude/role-boundary**: cơ chế nằm trong AC, AC lặp lại BR…).
|
|
47
|
+
- Lặp tới khi **2 vòng liên tiếp 0 finding mới** hoặc cap **3 vòng**. Ghi `convergence_rounds`.
|
|
48
|
+
|
|
49
|
+
### Phase 3 — Dedup / xung đột / merge
|
|
50
|
+
- Khử trùng (giữ suggestion phong phú hơn, severity cao hơn); merge được thì merge, loại trừ nhau → một finding `needs_discussion`; sắp theo severity; gán ID `F001…`; map dimension → `lens`; ghi **một** file findings.
|
|
51
|
+
|
|
52
|
+
### Full vs Delta
|
|
53
|
+
- Lần đầu (chưa có findings file) → **FULL**. Lần sau so `prd_version`: chưa đổi → DỪNG; đổi do chính resume này (`applied_to_version` khớp) → **DELTA** (chỉ UC đã đổi + UC mới); đổi bởi actor khác → **FULL** + cảnh báo.
|
|
54
|
+
|
|
55
|
+
### Resume Mode (`--resume`)
|
|
56
|
+
- Áp finding theo `status` (`accepted`/`modified`), bump version PRD, ghi `applied_to_version`. `needs_discussion` chặn resume tới khi người quyết.
|
|
57
|
+
|
|
58
|
+
---
|
|
59
|
+
|
|
60
|
+
## Checkpoint & Gate
|
|
61
|
+
|
|
62
|
+
- 🛑 **Review Board** — PO accept/reject/modify **từng** finding (không auto-apply). Finding lifecycle: `pending → accepted|modified|rejected|needs_discussion|deferred → applied`.
|
|
63
|
+
- `recommendation`: critical≥1 → `BLOCKED`; major≥1 → `NEEDS_REVISION`; else `APPROVED_WITH_MINOR_CHANGES`.
|
|
64
|
+
|
|
65
|
+
---
|
|
66
|
+
|
|
67
|
+
## Cơ chế đặc biệt
|
|
68
|
+
|
|
69
|
+
- **Không có `--fix` mode** (khác `/review-context`) — finding 3 lăng kính là phán đoán DEV/SA/PO, **bắt buộc qua người** ở Board; `auto_fixable` chỉ là gợi ý quick-accept.
|
|
70
|
+
- **`resolution_edge_cases`** — phân tích bậc-hai (chỉ critical/major): "nếu chốt phương án này thì đẻ ra edge case gì?" → PO thấy trước khi accept (advisory, không chặn).
|
|
71
|
+
- **QA lens đang DISABLED** (comment trong file) — có hướng dẫn bật lại nếu cần.
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## 👓 Góc nhìn tối ưu
|
|
76
|
+
|
|
77
|
+
- **Đây là command tốn agent/token nhất phía thượng nguồn** — `per-uc` × 3 lăng kính × (UC+1) + tới 3 vòng critic. `AGENT_CAP=12` là núm chỉnh chính. Với PRD lớn, đây là điểm cần cân đối chi phí ↔ độ đầy đủ.
|
|
78
|
+
- **Completeness-critic tới 3 vòng** — điểm đáng đo: thực tế hội tụ ở vòng mấy? Nếu thường 1–2 vòng thì cap 3 hợp lý.
|
|
79
|
+
- **Full/delta logic phức tạp** (`applied_to_version` tracking) — mạnh nhưng nhiều nhánh; dễ rơi về FULL khi có actor khác sửa PRD (vd `/review-context` xen giữa).
|
|
80
|
+
- **Ranh giới với `/review-context`** — cả hai đều review PRD, dùng chung review-fanout. `/refine-prd` = phán đoán chất lượng nghiệp vụ (3 lăng kính); `/review-context` = check có mã P0–P5 + auto-fix. Chồng lấn có chủ đích hay có thể gộp?
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## Kết nối
|
|
85
|
+
|
|
86
|
+
**Trước:** [`/generate-prd`](02-generate-prd.md) hoặc [`/extend-prd`](02b-extend-prd.md) · **Sau:** mở Review Board → cập nhật PRD → [`/review-context`](04-review-context.md).
|