@edupia-tutor/spec-driven-docs 0.14.7 → 0.14.9
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/commands/generate-bdd.md +76 -8
- package/commands/generate-bdd.tmpl +56 -108
- package/commands/generate-code.md +18 -1
- package/commands/generate-code.tmpl +18 -1
- package/commands/generate-design-spec.md +35 -5
- package/commands/generate-design-spec.tmpl +35 -5
- package/commands/generate-prd.md +15 -5
- package/commands/generate-prd.tmpl +1 -0
- package/commands/generate-tech-docs.md +1 -0
- package/commands/generate-tech-docs.tmpl +1 -0
- package/commands/propose-scenario.md +6 -2
- package/commands/propose-scenario.tmpl +6 -2
- package/commands/qc-analyze.md +14 -0
- package/commands/qc-analyze.tmpl +14 -0
- package/commands/refine-prd.md +25 -6
- package/commands/refine-prd.tmpl +18 -6
- package/commands/review-context.md +27 -12
- package/commands/review-context.tmpl +20 -12
- package/commands/validate-traces.md +1 -0
- package/commands/validate-traces.tmpl +1 -0
- package/core/FRAMEWORK_VERSION +1 -1
- package/core/commands/generate-bdd.md +76 -8
- package/core/commands/generate-code.md +18 -1
- package/core/commands/generate-design-spec.md +35 -5
- package/core/commands/generate-prd.md +15 -5
- package/core/commands/generate-tech-docs.md +1 -0
- package/core/commands/propose-scenario.md +6 -2
- package/core/commands/qc-analyze.md +14 -0
- package/core/commands/refine-prd.md +25 -6
- package/core/commands/review-context.md +27 -12
- package/core/commands/validate-traces.md +1 -0
- package/core/skills/code/SKILL.md +7 -759
- package/core/skills/debug/SKILL.md +9 -859
- package/core/skills/design-spec/SKILL.md +3 -582
- package/core/skills/prd/SKILL.md +5 -464
- package/core/skills/setup-ai-first/SKILL.md +3 -208
- package/core/skills/spec/SKILL.md +7 -450
- package/core/skills/test/SKILL.md +10 -1290
- package/core/steps/review-fanout.md +7 -0
- package/core/steps/spawn-agent.md +12 -7
- package/core/templates/feature.template +83 -222
- package/core/templates/prd.template.md +14 -5
- package/core/templates/project-context.yaml +1 -1
- package/docs/01-getting-started/core-concepts.md +2 -2
- package/docs/01-getting-started/quickstart.md +4 -3
- package/docs/02-guides/bdd-input-checklist.md +68 -0
- package/docs/02-guides/developer/README.md +3 -0
- package/docs/02-guides/developer/bdd-and-trace.md +1 -0
- package/docs/02-guides/developer/commands.md +3 -3
- package/docs/02-guides/developer/pr-checklist.md +1 -0
- package/docs/02-guides/developer/workflow.md +2 -2
- package/docs/02-guides/prd-input-checklist.md +94 -0
- package/docs/02-guides/product-owner/README.md +3 -1
- package/docs/02-guides/product-owner/commands.md +1 -1
- package/docs/02-guides/tech-docs-input-checklist.md +82 -0
- package/docs/02-guides/tester/README.md +1 -1
- package/docs/02-guides/tester/bug-reporting.md +1 -1
- package/docs/02-guides/tester/qc-automation.md +1 -1
- package/docs/03-concepts/README.md +1 -0
- package/docs/03-concepts/mechanisms-explained.md +57 -0
- package/docs/03-concepts/pipeline.md +12 -9
- package/docs/03-concepts/traceability.md +4 -1
- package/docs/04-operations/bug-flow.md +2 -0
- package/docs/05-reference/command-cheatsheet.md +8 -8
- package/docs/05-reference/commands.md +12 -10
- package/docs/05-reference/trace-schema.md +2 -1
- package/package.json +1 -1
- package/skills/code/SKILL.md +7 -759
- package/skills/code/SKILL.tmpl +7 -164
- package/skills/debug/SKILL.md +9 -859
- package/skills/debug/SKILL.tmpl +9 -252
- package/skills/design-spec/SKILL.md +3 -582
- package/skills/design-spec/SKILL.tmpl +3 -87
- package/skills/prd/SKILL.md +5 -464
- package/skills/prd/SKILL.tmpl +5 -63
- package/skills/setup-ai-first/SKILL.md +3 -208
- package/skills/setup-ai-first/SKILL.tmpl +3 -108
- package/skills/spec/SKILL.md +7 -450
- package/skills/spec/SKILL.tmpl +7 -162
- package/skills/test/SKILL.md +10 -1290
- package/skills/test/SKILL.tmpl +10 -288
- package/steps/review-fanout.md +7 -0
- package/steps/spawn-agent.md +12 -7
- package/templates/feature.template +83 -222
- package/templates/prd.template.md +14 -5
- package/templates/project-context.yaml +1 -1
package/commands/generate-prd.md
CHANGED
|
@@ -624,6 +624,8 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
|
|
|
624
624
|
|
|
625
625
|
## b. Phạm vi
|
|
626
626
|
|
|
627
|
+
> **Scope = ranh giới, KHÔNG phải đặc tả.** Mỗi mục một dòng ngắn "làm gì / không làm gì". Đừng nhét **cơ chế** (retry/timeout/nhánh lỗi → BR/BL) hay **định nghĩa thuật ngữ** (vd "điểm khởi tạo = …" → Business Definition / business-dictionary) vào đây.
|
|
628
|
+
|
|
627
629
|
**In Scope**
|
|
628
630
|
- {hạng mục trong phạm vi 1}
|
|
629
631
|
- {hạng mục trong phạm vi 2}
|
|
@@ -642,10 +644,14 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
|
|
|
642
644
|
# 2. Acceptance Criteria
|
|
643
645
|
|
|
644
646
|
> Mỗi AC kế thừa liên kết "Bắt nguồn từ BR" của Product Definition (Phase 6), remap sang BR ID của PRD. Vì BR ID đã chứa số UC nên ref BR truy ngược được tới đúng UC.
|
|
647
|
+
>
|
|
648
|
+
> **1 AC = 1 tiêu chí NGHIỆM THU (outcome quan sát/kiểm được) + ref BR.** KHÔNG viết cơ chế trong AC (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết) — cái đó thuộc **BR/BL** ở §3, AC chỉ trỏ tới. Nếu tiêu chí có **nhiều nhánh** → tách **bullet con** (mỗi ý một dòng), đừng dồn thành câu dài. Khi `/refine-prd` làm rõ thêm: chi tiết cơ chế → đẩy sang BR/BL; ở tầng AC thì tách bullet/AC mới — KHÔNG nối mệnh đề vào câu cũ (tránh AC thành "đoạn văn" và trùng BR).
|
|
645
649
|
|
|
646
650
|
**AC1:** {Tiêu chí nghiệm thu, văn xuôi, kiểm chứng được.} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
|
|
647
651
|
|
|
648
|
-
**AC2:** {
|
|
652
|
+
**AC2:** {Tiêu chí có nhiều nhánh — tách bullet:} _(BR: {TICKET}-{N}-UC{n}-BR{m})_
|
|
653
|
+
- {nhánh/điều kiện 1 → kết quả kỳ vọng}
|
|
654
|
+
- {nhánh/điều kiện 2 → kết quả kỳ vọng}
|
|
649
655
|
|
|
650
656
|
---
|
|
651
657
|
|
|
@@ -752,11 +758,14 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
|
|
|
752
758
|
|
|
753
759
|
# Change Log
|
|
754
760
|
|
|
755
|
-
|
|
761
|
+
> Hiện tại: **v1.0** ({date}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET}-{N}-{slug}.changelog.md) *(file kho chỉ tạo khi changelog vượt 5 version)*
|
|
762
|
+
|
|
763
|
+
<!-- Bảng phẳng, MỘT dòng/version, MỚI NHẤT TRÊN CÙNG. Chỉ giữ tối đa 5 version gần nhất ở đây;
|
|
764
|
+
cũ hơn → /refine-prd & /review-context tự dồn (rollover) sang file changelog/ ở link trên. -->
|
|
756
765
|
|
|
757
|
-
|
|
|
758
|
-
|
|
759
|
-
|
|
|
766
|
+
| Version | Date | Changes (UC/AC/BR bị ảnh hưởng) |
|
|
767
|
+
|---------|------|---------------------------------|
|
|
768
|
+
| 1.0 | {date} | Bản đầu — sinh từ product-definition. |
|
|
760
769
|
|
|
761
770
|
---
|
|
762
771
|
|
|
@@ -774,6 +783,7 @@ _(Nếu không có độ vênh: ghi "Không có — toàn bộ nội dung đã
|
|
|
774
783
|
## Quality Checklist *(kiểm tra trước khi ghi)*
|
|
775
784
|
|
|
776
785
|
- [ ] Mọi AC đều testable (pass/fail rõ ràng), không có chi tiết kỹ thuật (API/token/DB) hay visual chi tiết (màu sắc, font, animation)
|
|
786
|
+
- [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
|
|
777
787
|
- [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
|
|
778
788
|
- [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
|
|
779
789
|
- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
|
|
@@ -130,6 +130,7 @@ Ghi `{paths.specs_dir}/{domain}/{prd-slug}/{TICKET-ID}-{prd-slug}.md` theo cấu
|
|
|
130
130
|
## Quality Checklist *(kiểm tra trước khi ghi)*
|
|
131
131
|
|
|
132
132
|
- [ ] Mọi AC đều testable (pass/fail rõ ràng), không có chi tiết kỹ thuật (API/token/DB) hay visual chi tiết (màu sắc, font, animation)
|
|
133
|
+
- [ ] **Altitude (AC vs BR/BL)**: AC chỉ nêu **outcome quan sát/kiểm được + ref BR** — KHÔNG chứa cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi chi tiết); cơ chế nằm ở **BR/BL** (§3). AC không lặp lại nội dung BR nó ref. **Scope** = ranh giới (KHÔNG định nghĩa thuật ngữ / KHÔNG cơ chế)
|
|
133
134
|
- [ ] Mỗi UC có Actor / Description / Pre-condition / Post-condition
|
|
134
135
|
- [ ] §1c "Phụ thuộc liên service" có mặt: kế thừa từ discovery Phase 1 câu 8 (hoặc "Không có" nếu discovery trống); case partner song song có ghi phụ thuộc partner ở đây
|
|
135
136
|
- [ ] Business Rule (WHAT) và Business Logic (HOW) nằm chung bảng 3 cột `ID | Business Rule | Business Logic`
|
|
@@ -113,6 +113,7 @@ Chờ người dùng trả lời rõ ràng "Y" hoặc "N" rồi mới tiếp t
|
|
|
113
113
|
Rồi: /review-context --resume {feature-file} ← áp dụng các finding được chấp nhận còn lại
|
|
114
114
|
Rồi chạy lại: /generate-tech-docs {feature-file}
|
|
115
115
|
```
|
|
116
|
+
4. **Đồng thời** đọc `# @trace.status:` của `.feature` (tín hiệu duyệt chuẩn — B3): nếu ≠ `approved` → cảnh báo MỀM (đồng bộ qc-analyze/generate-code): "BDD chưa duyệt (@trace.status: {status}) — tech-docs sinh từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)". *(Nếu `approved` thì BDD đã sign-off; finding-gate ở trên vẫn chạy để chặn critical sót.)*
|
|
116
117
|
|
|
117
118
|
## Context
|
|
118
119
|
# Context Loader — Nạp toàn bộ context dự án
|
|
@@ -25,6 +25,7 @@
|
|
|
25
25
|
Rồi: /review-context --resume {feature-file} ← áp dụng các finding được chấp nhận còn lại
|
|
26
26
|
Rồi chạy lại: /generate-tech-docs {feature-file}
|
|
27
27
|
```
|
|
28
|
+
4. **Đồng thời** đọc `# @trace.status:` của `.feature` (tín hiệu duyệt chuẩn — B3): nếu ≠ `approved` → cảnh báo MỀM (đồng bộ qc-analyze/generate-code): "BDD chưa duyệt (@trace.status: {status}) — tech-docs sinh từ BDD chưa chốt có thể phải làm lại. Tiếp tục? (Y/N)". *(Nếu `approved` thì BDD đã sign-off; finding-gate ở trên vẫn chạy để chặn critical sót.)*
|
|
28
29
|
|
|
29
30
|
## Context
|
|
30
31
|
{{include:steps/context-loader.md}}
|
|
@@ -466,7 +466,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
|
|
|
466
466
|
|
|
467
467
|
Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
|
|
468
468
|
KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
|
|
469
|
-
(xem Output)
|
|
469
|
+
(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
|
|
470
|
+
|
|
471
|
+
> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
|
|
472
|
+
> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
|
|
470
473
|
|
|
471
474
|
## Step 5 — Handoff (để PO/Dev thực sự thấy)
|
|
472
475
|
|
|
@@ -612,7 +615,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
|
|
|
612
615
|
|
|
613
616
|
Để PO/Dev promote:
|
|
614
617
|
[ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
|
|
615
|
-
[ ]
|
|
618
|
+
[ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
|
|
619
|
+
[ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
|
|
616
620
|
[ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
|
|
617
621
|
|
|
618
622
|
Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
|
|
@@ -71,7 +71,10 @@ Viết Gherkin nhất quán với convention của `/generate-bdd` cho `active_p
|
|
|
71
71
|
|
|
72
72
|
Ghi vào `{paths.bdd_proposals_dir}/{UC-ID}-{slug}.md` (phân giải về `{spec_source}/feedback/bdd-proposals/` ở umbrella mode; tạo dir nếu cần).
|
|
73
73
|
KHÔNG đụng `.feature` canonical. Doc proposal chứa draft + metadata review
|
|
74
|
-
(xem Output)
|
|
74
|
+
(xem Output), **gồm dòng `Status: proposed`**. Nếu nguồn là một bug, tham chiếu `BUG-ID` của nó.
|
|
75
|
+
|
|
76
|
+
> **Vòng đời proposal** (máy đọc được để `/generate-bdd` intake đúng):
|
|
77
|
+
> `proposed` → PO/Dev duyệt đặt `accepted` (hoặc `rejected`) → `/generate-bdd` chèn cái `accepted` vào `.feature` rồi đặt `incorporated` + lưu trữ. **Chỉ `accepted` mới được đưa vào BDD.**
|
|
75
78
|
|
|
76
79
|
## Step 5 — Handoff (để PO/Dev thực sự thấy)
|
|
77
80
|
|
|
@@ -117,7 +120,8 @@ Scenario đề xuất (DRAFT — chờ PO/Dev review):
|
|
|
117
120
|
|
|
118
121
|
Để PO/Dev promote:
|
|
119
122
|
[ ] AC mapping đúng? (hoặc cập nhật PRD nếu requirement thực sự mới)
|
|
120
|
-
[ ]
|
|
123
|
+
[ ] Đặt `Status: accepted` trong file proposal (để /generate-bdd đưa vào)
|
|
124
|
+
[ ] Chạy lại /generate-bdd {UC-ID} — nó tự chèn proposal `accepted` vào .feature rồi lưu trữ
|
|
121
125
|
[ ] Rồi: /generate-code {UC-ID} + /dev-gen-test {UC-ID}
|
|
122
126
|
|
|
123
127
|
Handoff : {✅ committed + pushed to spec repo | ⚠️ chạy git command ở trên / mở PR}
|
package/commands/qc-analyze.md
CHANGED
|
@@ -411,6 +411,20 @@ Sau khi hoàn thành tất cả các bước, bạn đã nạp:
|
|
|
411
411
|
Tiếp tục sang bước kế tiếp của lệnh đang gọi.
|
|
412
412
|
|
|
413
413
|
|
|
414
|
+
---
|
|
415
|
+
|
|
416
|
+
## Guard — BDD đã duyệt chưa
|
|
417
|
+
|
|
418
|
+
Đọc `# @trace.status:` từ header file `.feature` của UC target:
|
|
419
|
+
- `approved` → tiếp tục bình thường.
|
|
420
|
+
- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
|
|
421
|
+
```
|
|
422
|
+
⚠️ BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
|
|
423
|
+
Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
|
|
424
|
+
Vẫn chạy QC bây giờ? (Y/N)
|
|
425
|
+
```
|
|
426
|
+
Chỉ tiếp khi chọn Y.
|
|
427
|
+
|
|
414
428
|
---
|
|
415
429
|
|
|
416
430
|
## Role
|
package/commands/qc-analyze.tmpl
CHANGED
|
@@ -18,6 +18,20 @@ ported_from: ai-automation-qc-base
|
|
|
18
18
|
|
|
19
19
|
---
|
|
20
20
|
|
|
21
|
+
## Guard — BDD đã duyệt chưa
|
|
22
|
+
|
|
23
|
+
Đọc `# @trace.status:` từ header file `.feature` của UC target:
|
|
24
|
+
- `approved` → tiếp tục bình thường.
|
|
25
|
+
- `draft` (hoặc khác `approved`) → **CHECKPOINT cảnh báo mềm** (không chặn cứng — cho phép QC sớm/prototype):
|
|
26
|
+
```
|
|
27
|
+
⚠️ BDD của {UC-ID} đang ở @trace.status: {status} (chưa duyệt). QC chạy trên BDD chưa chốt có thể phải làm lại.
|
|
28
|
+
Khuyến nghị: review-context (BDD) sạch + người duyệt đặt `# @trace.status: approved` rồi mới chạy QC.
|
|
29
|
+
Vẫn chạy QC bây giờ? (Y/N)
|
|
30
|
+
```
|
|
31
|
+
Chỉ tiếp khi chọn Y.
|
|
32
|
+
|
|
33
|
+
---
|
|
34
|
+
|
|
21
35
|
## Role
|
|
22
36
|
|
|
23
37
|
Bạn là **QC Analyst** — stage đầu tiên của QC automation pipeline. Lấy requirement
|
package/commands/refine-prd.md
CHANGED
|
@@ -574,6 +574,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
|
|
|
574
574
|
List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
|
|
575
575
|
contradictions, missing edge/negative paths, coverage holes, terminology drift,
|
|
576
576
|
structural omissions, and any issue that a fix to an existing finding would expose.
|
|
577
|
+
ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
|
|
578
|
+
content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
|
|
579
|
+
names/owners, error branches) written INSIDE an acceptance criterion or a scope line
|
|
580
|
+
instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
|
|
581
|
+
(same content, converged); a term definition crammed into In/Out Scope. For these, the
|
|
582
|
+
suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
|
|
583
|
+
outcome + BR ref) — NOT to delete it, and NOT to add more detail.
|
|
577
584
|
Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
|
|
578
585
|
nothing new.
|
|
579
586
|
```
|
|
@@ -638,8 +645,8 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
|
|
|
638
645
|
**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
|
|
639
646
|
toàn bộ PRD qua đúng lăng kính của nó:
|
|
640
647
|
|
|
641
|
-
- **Lăng kính QA**: AC có
|
|
642
|
-
- **Lăng kính DEV**:
|
|
648
|
+
- **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
|
|
649
|
+
- **Lăng kính DEV (tầng cơ chế)**: BR (WHAT) + Business Logic (HOW) đã đủ & rõ chưa — **đây là NƠI chứa chi tiết**: rẽ nhánh, điều kiện biên, retry, error path. Business rule có mơ hồ không? Cross-service deps đủ chưa? Rủi ro kỹ thuật?
|
|
643
650
|
- **Lăng kính SA**: Khớp kiến trúc hiện tại? Hệ luỵ security/auth? Mô hình dữ liệu rõ chưa?
|
|
644
651
|
- **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
|
|
645
652
|
|
|
@@ -886,6 +893,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
|
|
|
886
893
|
Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
|
|
887
894
|
- Đi tới section PRD được chỉ định bởi `finding.section`.
|
|
888
895
|
- Áp dụng `finding.suggestion`. Với finding `status: "modified"`, người đã sửa sẵn `finding.suggestion` trong Review Board — giá trị đã sửa đó CHÍNH LÀ bản fix cần áp dụng.
|
|
896
|
+
- **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = **outcome quan sát được + ref BR**, KHÔNG chứa cơ chế. Nếu fix là **chi tiết cơ chế/rule** (retry N, timeout, tên/chủ cờ, nhánh lỗi) → **ghi vào bảng BR/BL của UC** (hoặc tạo BR mới), AC chỉ **ref**; KHÔNG inline vào câu AC. Nếu fix làm rõ **≥2 điều kiện/nhánh** ở đúng tầng của nó → **tách bullet con** (mỗi ý một dòng ` - …`) hoặc **AC/BR mới**, đừng nối mệnh đề vào câu cũ. Một AC = một tiêu chí kiểm chứng; đừng để AC lặp lại nội dung BR.
|
|
889
897
|
- **Chạy Business Language Guard trên text mới TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ"): diễn đạt lại / gỡ thuật ngữ kỹ thuật-UI để fix không tự kéo theo term kỹ thuật vào PRD.
|
|
890
898
|
- Không thay đổi bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận.
|
|
891
899
|
|
|
@@ -909,10 +917,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
|
|
|
909
917
|
- `| **Version** | {new_version} |`
|
|
910
918
|
- `| **Updated** | {today YYYY-MM-DD} |`
|
|
911
919
|
- `| **Status** | draft |` ← reset về draft, phải được duyệt lại
|
|
912
|
-
5.
|
|
913
|
-
|
|
914
|
-
|
|
915
|
-
|
|
920
|
+
5. Cập nhật `# Change Log` của PRD — **bảng phẳng 1 dòng/version, cửa sổ trượt 5 entry** (nếu gặp format cũ `### v{X}` block → chuẩn hoá sang bảng phẳng khi cập nhật):
|
|
921
|
+
- Thêm row mới lên **đầu** bảng:
|
|
922
|
+
```
|
|
923
|
+
| {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
|
|
924
|
+
```
|
|
925
|
+
*(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
|
|
926
|
+
- Cập nhật dòng đầu section: `> Hiện tại: **v{new_version}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
|
|
927
|
+
- **Rollover (giữ PRD gọn — đây là chuẩn chung, /review-context cũng theo):** nếu bảng `# Change Log` có **> 5 row** → chuyển **mọi row vượt 5** (cũ nhất) sang **đầu** bảng của file kho `{paths.specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md` (giữ thứ tự mới→cũ); PRD chỉ giữ **5 row gần nhất**. Tạo thư mục `changelog/` + file kho nếu chưa có, theo skeleton:
|
|
928
|
+
```
|
|
929
|
+
# Change Log (lịch sử) — {TICKET-ID}
|
|
930
|
+
> PRD: [../{TICKET-ID}-{prd-slug}.md](../{TICKET-ID}-{prd-slug}.md) — 5 version gần nhất nằm trong PRD; đây là phần cũ hơn.
|
|
931
|
+
|
|
932
|
+
| Version | Date | Changes |
|
|
933
|
+
|---------|------|---------|
|
|
934
|
+
```
|
|
916
935
|
6. Ghi `applied_to_version: "{new_version}"` ở **root level** của findings — đóng dấu "PRD đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt được thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
|
|
917
936
|
|
|
918
937
|
### Phase 4 — Report
|
package/commands/refine-prd.tmpl
CHANGED
|
@@ -55,8 +55,8 @@ Chạy review qua **Quy trình Review** ở trên (`steps/review-fanout.md`).
|
|
|
55
55
|
**DIMENSIONS** = 4 lăng kính dưới đây — fan out một sub-agent cho mỗi lăng kính, mỗi cái quét
|
|
56
56
|
toàn bộ PRD qua đúng lăng kính của nó:
|
|
57
57
|
|
|
58
|
-
- **Lăng kính QA**: AC có
|
|
59
|
-
- **Lăng kính DEV**:
|
|
58
|
+
- **Lăng kính QA (tầng nghiệm thu)**: AC có nêu **outcome quan sát/kiểm được** chưa? — **KHÔNG** hỏi "AC đủ chi tiết chưa" (câu đó kéo cơ chế vào AC). Chi tiết cơ chế (số lần retry, timeout, tên/chủ cờ, nhánh lỗi vụn) thuộc **BR/BL**: nếu gap là cơ chế → suggestion phải **route sang BR/BL + AC ref**, KHÔNG phình AC. AC có lặp lại nội dung BR (trùng tầng) không → nếu có, đề xuất làm mỏng AC.
|
|
59
|
+
- **Lăng kính DEV (tầng cơ chế)**: BR (WHAT) + Business Logic (HOW) đã đủ & rõ chưa — **đây là NƠI chứa chi tiết**: rẽ nhánh, điều kiện biên, retry, error path. Business rule có mơ hồ không? Cross-service deps đủ chưa? Rủi ro kỹ thuật?
|
|
60
60
|
- **Lăng kính SA**: Khớp kiến trúc hiện tại? Hệ luỵ security/auth? Mô hình dữ liệu rõ chưa?
|
|
61
61
|
- **Lăng kính PO**: Scope đã khoanh vùng? Priority rõ chưa? Success metric đã định nghĩa? Rủi ro scope creep?
|
|
62
62
|
|
|
@@ -203,6 +203,7 @@ Nếu có finding nào có `status: "needs_discussion"`, thêm warning block sau
|
|
|
203
203
|
Với mỗi finding được chấp nhận, theo thứ tự severity (critical → major → minor):
|
|
204
204
|
- Đi tới section PRD được chỉ định bởi `finding.section`.
|
|
205
205
|
- Áp dụng `finding.suggestion`. Với finding `status: "modified"`, người đã sửa sẵn `finding.suggestion` trong Review Board — giá trị đã sửa đó CHÍNH LÀ bản fix cần áp dụng.
|
|
206
|
+
- **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = **outcome quan sát được + ref BR**, KHÔNG chứa cơ chế. Nếu fix là **chi tiết cơ chế/rule** (retry N, timeout, tên/chủ cờ, nhánh lỗi) → **ghi vào bảng BR/BL của UC** (hoặc tạo BR mới), AC chỉ **ref**; KHÔNG inline vào câu AC. Nếu fix làm rõ **≥2 điều kiện/nhánh** ở đúng tầng của nó → **tách bullet con** (mỗi ý một dòng ` - …`) hoặc **AC/BR mới**, đừng nối mệnh đề vào câu cũ. Một AC = một tiêu chí kiểm chứng; đừng để AC lặp lại nội dung BR.
|
|
206
207
|
- **Chạy Business Language Guard trên text mới TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ"): diễn đạt lại / gỡ thuật ngữ kỹ thuật-UI để fix không tự kéo theo term kỹ thuật vào PRD.
|
|
207
208
|
- Không thay đổi bất kỳ section nào không được tham chiếu bởi một finding được chấp nhận.
|
|
208
209
|
|
|
@@ -226,10 +227,21 @@ Cập nhật `status: "applied"` ở **root level** của file findings (không
|
|
|
226
227
|
- `| **Version** | {new_version} |`
|
|
227
228
|
- `| **Updated** | {today YYYY-MM-DD} |`
|
|
228
229
|
- `| **Status** | draft |` ← reset về draft, phải được duyệt lại
|
|
229
|
-
5.
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
230
|
+
5. Cập nhật `# Change Log` của PRD — **bảng phẳng 1 dòng/version, cửa sổ trượt 5 entry** (nếu gặp format cũ `### v{X}` block → chuẩn hoá sang bảng phẳng khi cập nhật):
|
|
231
|
+
- Thêm row mới lên **đầu** bảng:
|
|
232
|
+
```
|
|
233
|
+
| {new_version} | {today} | {tóm tắt — KÈM UC/AC/BR bị ảnh hưởng, vd "UC2: sửa BR5; thêm AC7"} |
|
|
234
|
+
```
|
|
235
|
+
*(Nêu rõ UC/AC/BR giúp `/generate-bdd` Version Check biết scenario nào cần cập nhật.)*
|
|
236
|
+
- Cập nhật dòng đầu section: `> Hiện tại: **v{new_version}** ({today}) · Lịch sử đầy đủ → [changelog](./changelog/{TICKET-ID}-{prd-slug}.changelog.md)`
|
|
237
|
+
- **Rollover (giữ PRD gọn — đây là chuẩn chung, /review-context cũng theo):** nếu bảng `# Change Log` có **> 5 row** → chuyển **mọi row vượt 5** (cũ nhất) sang **đầu** bảng của file kho `{paths.specs_dir}/{domain}/{prd-slug}/changelog/{TICKET-ID}-{prd-slug}.changelog.md` (giữ thứ tự mới→cũ); PRD chỉ giữ **5 row gần nhất**. Tạo thư mục `changelog/` + file kho nếu chưa có, theo skeleton:
|
|
238
|
+
```
|
|
239
|
+
# Change Log (lịch sử) — {TICKET-ID}
|
|
240
|
+
> PRD: [../{TICKET-ID}-{prd-slug}.md](../{TICKET-ID}-{prd-slug}.md) — 5 version gần nhất nằm trong PRD; đây là phần cũ hơn.
|
|
241
|
+
|
|
242
|
+
| Version | Date | Changes |
|
|
243
|
+
|---------|------|---------|
|
|
244
|
+
```
|
|
233
245
|
6. Ghi `applied_to_version: "{new_version}"` ở **root level** của findings — đóng dấu "PRD đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt được thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
|
|
234
246
|
|
|
235
247
|
### Phase 4 — Report
|
|
@@ -585,6 +585,13 @@ mới**, hoặc tới cap cứng **3 vòng**, cái nào đến trước:
|
|
|
585
585
|
List ONLY real, additional issues NOT already in the list — gaps, ambiguities,
|
|
586
586
|
contradictions, missing edge/negative paths, coverage holes, terminology drift,
|
|
587
587
|
structural omissions, and any issue that a fix to an existing finding would expose.
|
|
588
|
+
ALSO flag ROLE-BOUNDARY / altitude violations (you are NOT limited to adding detail):
|
|
589
|
+
content sitting in the WRONG section — detailed mechanism (retry counts, timeouts, flag
|
|
590
|
+
names/owners, error branches) written INSIDE an acceptance criterion or a scope line
|
|
591
|
+
instead of the Business Rule/Logic section; an AC that merely restates its referenced BR
|
|
592
|
+
(same content, converged); a term definition crammed into In/Out Scope. For these, the
|
|
593
|
+
suggestion must be to MOVE the detail to its proper section (AC keeps only the observable
|
|
594
|
+
outcome + BR ref) — NOT to delete it, and NOT to add more detail.
|
|
588
595
|
Do NOT repeat anything already listed. Return the same finding JSON shape, or [] if
|
|
589
596
|
nothing new.
|
|
590
597
|
```
|
|
@@ -713,8 +720,10 @@ Quét mỗi AC và BR tìm:
|
|
|
713
720
|
| Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
|
|
714
721
|
| Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
|
|
715
722
|
| Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
|
|
723
|
+
| **AC lấn tầng (chứa cơ chế)** | AC ghi số lần retry / timeout / tên-chủ cờ / nhánh lỗi chi tiết — cái này thuộc BR/BL | Major |
|
|
724
|
+
| **AC ≈ BR (trùng nội dung, hội tụ tầng)** | AC lặp lại đúng nội dung BR nó ref | Major |
|
|
716
725
|
|
|
717
|
-
→ AI không thể auto-fix finding P2. Người
|
|
726
|
+
→ AI không thể auto-fix finding P2. Người viết bản fix trong note "Modify". Với 2 tín hiệu **altitude** (AC lấn tầng / AC≈BR): suggestion là **DI DỜI chi tiết cơ chế xuống BR/BL (§3), AC giữ outcome + ref** — không xoá, không phình.
|
|
718
727
|
|
|
719
728
|
### P3 — Domain Conflict Check
|
|
720
729
|
|
|
@@ -994,8 +1003,10 @@ Lựa chọn tiếp theo:
|
|
|
994
1003
|
→ /review-context --resume {target-file}
|
|
995
1004
|
|
|
996
1005
|
{CHỈ in khối này khi 0 finding critical còn lại — còn critical thì nhắc duyệt là vô nghĩa}:
|
|
997
|
-
✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
|
|
998
|
-
|
|
1006
|
+
{If PRD}: ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
|
|
1007
|
+
Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
|
|
1008
|
+
{If BDD}: ✅ BDD đã sạch critical. Sau khi review xong → đặt `# @trace.status: approved` trong
|
|
1009
|
+
header file .feature (dấu duyệt BDD, do người quyết) → rồi /generate-tech-docs.
|
|
999
1010
|
```
|
|
1000
1011
|
|
|
1001
1012
|
---
|
|
@@ -1050,8 +1061,8 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
|
|
|
1050
1061
|
### Phase 3 — Version bump
|
|
1051
1062
|
|
|
1052
1063
|
- **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
|
|
1053
|
-
|
|
1054
|
-
- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
|
|
1064
|
+
`| {new_version} | {today} | Auto-fix: applied {N} auto-fixable findings |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
|
|
1065
|
+
- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại — đồng bộ với cơ chế reset draft của PRD)
|
|
1055
1066
|
- **Cả hai**: ghi `applied_to_version: "{version vừa bump tới}"` ở root level của findings — đóng dấu "target đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
|
|
1056
1067
|
|
|
1057
1068
|
### Phase 4 — Report
|
|
@@ -1068,13 +1079,14 @@ Còn pending (cần quyết định của con người): {N}
|
|
|
1068
1079
|
- F00X [{severity}] {tóm tắt finding} ← mở file findings trong Review Board
|
|
1069
1080
|
|
|
1070
1081
|
{If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
|
|
1071
|
-
{If BDD}: bdd_version: {old} → {new}
|
|
1082
|
+
{If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
|
|
1072
1083
|
|
|
1073
1084
|
File findings:
|
|
1074
1085
|
{If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
|
|
1075
1086
|
{If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
|
|
1076
1087
|
Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
|
|
1077
|
-
Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
1088
|
+
{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
1089
|
+
{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
|
|
1078
1090
|
```
|
|
1079
1091
|
|
|
1080
1092
|
Nếu 0 finding nào auto-fixable → in:
|
|
@@ -1108,6 +1120,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
1108
1120
|
|
|
1109
1121
|
> **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — đặc biệt với P2 (sửa câu mơ hồ) / P4 skeleton: không để bản fix tự kéo thuật ngữ kỹ thuật-UI vào PRD.
|
|
1110
1122
|
|
|
1123
|
+
> **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = outcome quan sát được + ref BR, KHÔNG chứa cơ chế. Fix là **chi tiết cơ chế/rule** (retry, timeout, tên/chủ cờ, nhánh lỗi) → **di dời vào bảng BR/BL của UC** (hoặc BR mới), AC chỉ ref; KHÔNG inline vào AC. Fix làm rõ ≥2 nhánh ở đúng tầng → **tách bullet con** hoặc AC/BR mới, đừng nối mệnh đề vào câu cũ. Đừng để AC lặp lại nội dung BR.
|
|
1124
|
+
|
|
1111
1125
|
**Với finding PRD:**
|
|
1112
1126
|
| check_id | Làm gì |
|
|
1113
1127
|
|----------|-----------|
|
|
@@ -1117,7 +1131,7 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
1117
1131
|
| P4 (Structure) | Thêm section/metadata field còn thiếu (row Status vắng → thêm mặc định `draft`) |
|
|
1118
1132
|
| P5 (Custom) | Áp dụng như nêu trong suggestion/note |
|
|
1119
1133
|
|
|
1120
|
-
→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm
|
|
1134
|
+
→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm row Changelog (bảng phẳng, **kê UC/AC/BR bị ảnh hưởng**, + **rollover giữ 5 row gần nhất** dồn dư sang `changelog/` — xem quy ước ở refine-prd Phase 3), và ghi `applied_to_version: "{new_version}"` ở root level của findings (xem "Chọn full vs delta").
|
|
1121
1135
|
|
|
1122
1136
|
**Với finding BDD:**
|
|
1123
1137
|
| check_id | Làm gì |
|
|
@@ -1129,8 +1143,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
1129
1143
|
| B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
|
|
1130
1144
|
| B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
|
|
1131
1145
|
|
|
1132
|
-
→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
|
|
1133
|
-
→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, và đặt `last_updated` thành ngày hôm nay.
|
|
1146
|
+
→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại).
|
|
1147
|
+
→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, đặt `uc_status = draft` (khớp header), và đặt `last_updated` thành ngày hôm nay.
|
|
1134
1148
|
→ Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
|
|
1135
1149
|
|
|
1136
1150
|
### Phase 3 — Report
|
|
@@ -1145,8 +1159,9 @@ Changes:
|
|
|
1145
1159
|
- {tóm tắt change 2}
|
|
1146
1160
|
|
|
1147
1161
|
{If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
|
|
1148
|
-
{If BDD}: bdd_version: {old} → {new}
|
|
1162
|
+
{If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
|
|
1149
1163
|
|
|
1150
1164
|
Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
|
|
1151
|
-
Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
1165
|
+
{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
1166
|
+
{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
|
|
1152
1167
|
```
|
|
@@ -130,8 +130,10 @@ Quét mỗi AC và BR tìm:
|
|
|
130
130
|
| Tham chiếu chưa định nghĩa | "{SomeThing}" được dùng nhưng chưa định nghĩa trong PRD này | Major |
|
|
131
131
|
| Thiếu luồng âm | AC chỉ mô tả happy path nhưng BR có điều kiện lỗi | Minor |
|
|
132
132
|
| Câu bị động giấu actor | "Invoice is created" — ai tạo? | Minor |
|
|
133
|
+
| **AC lấn tầng (chứa cơ chế)** | AC ghi số lần retry / timeout / tên-chủ cờ / nhánh lỗi chi tiết — cái này thuộc BR/BL | Major |
|
|
134
|
+
| **AC ≈ BR (trùng nội dung, hội tụ tầng)** | AC lặp lại đúng nội dung BR nó ref | Major |
|
|
133
135
|
|
|
134
|
-
→ AI không thể auto-fix finding P2. Người
|
|
136
|
+
→ AI không thể auto-fix finding P2. Người viết bản fix trong note "Modify". Với 2 tín hiệu **altitude** (AC lấn tầng / AC≈BR): suggestion là **DI DỜI chi tiết cơ chế xuống BR/BL (§3), AC giữ outcome + ref** — không xoá, không phình.
|
|
135
137
|
|
|
136
138
|
### P3 — Domain Conflict Check
|
|
137
139
|
|
|
@@ -311,8 +313,10 @@ Lựa chọn tiếp theo:
|
|
|
311
313
|
→ /review-context --resume {target-file}
|
|
312
314
|
|
|
313
315
|
{CHỈ in khối này khi 0 finding critical còn lại — còn critical thì nhắc duyệt là vô nghĩa}:
|
|
314
|
-
✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
|
|
315
|
-
|
|
316
|
+
{If PRD}: ✅ PRD đã sạch critical. Khi PO hài lòng → đặt `| **Status** | approved |` trong
|
|
317
|
+
Metadata PRD (dấu duyệt nghiệp vụ, do người quyết) → rồi /generate-bdd.
|
|
318
|
+
{If BDD}: ✅ BDD đã sạch critical. Sau khi review xong → đặt `# @trace.status: approved` trong
|
|
319
|
+
header file .feature (dấu duyệt BDD, do người quyết) → rồi /generate-tech-docs.
|
|
316
320
|
```
|
|
317
321
|
|
|
318
322
|
---
|
|
@@ -367,8 +371,8 @@ Sau khi áp dụng mỗi finding, đánh dấu nó `status: "applied"` + `applie
|
|
|
367
371
|
### Phase 3 — Version bump
|
|
368
372
|
|
|
369
373
|
- **PRD**: nếu ≥1 finding được áp dụng → bump version **minor** (auto-fix chỉ áp dụng thay banned-term P1 và thêm skeleton P4 — không bao giờ thay đổi cấu trúc UC hay nội dung BR, nên minor bump luôn đúng), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → con dấu duyệt cũ hết hiệu lực, phải duyệt lại — đồng bộ với /refine-prd), thêm entry Changelog:
|
|
370
|
-
|
|
371
|
-
- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1
|
|
374
|
+
`| {new_version} | {today} | Auto-fix: applied {N} auto-fixable findings |` — bảng phẳng + **rollover giữ 5 row gần nhất** (dồn dư sang `changelog/{TICKET-ID}-{prd-slug}.changelog.md`); xem quy ước đầy đủ ở refine-prd Phase 3.
|
|
375
|
+
- **BDD**: nếu ≥1 finding được áp dụng → tăng `@trace.bdd_version` lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại — đồng bộ với cơ chế reset draft của PRD)
|
|
372
376
|
- **Cả hai**: ghi `applied_to_version: "{version vừa bump tới}"` ở root level của findings — đóng dấu "target đổi tới version này là do lệnh này áp", để lần review delta sau phân biệt thay đổi của chính mình với thay đổi do actor khác (xem "Chọn full vs delta").
|
|
373
377
|
|
|
374
378
|
### Phase 4 — Report
|
|
@@ -385,13 +389,14 @@ Còn pending (cần quyết định của con người): {N}
|
|
|
385
389
|
- F00X [{severity}] {tóm tắt finding} ← mở file findings trong Review Board
|
|
386
390
|
|
|
387
391
|
{If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
|
|
388
|
-
{If BDD}: bdd_version: {old} → {new}
|
|
392
|
+
{If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
|
|
389
393
|
|
|
390
394
|
File findings:
|
|
391
395
|
{If PRD}: {paths.refinement_dir}/{prd-slug}-review-context-findings.yaml
|
|
392
396
|
{If BDD}: {paths.refinement_dir}/{uc-id}-review-bdd-findings.yaml
|
|
393
397
|
Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
|
|
394
|
-
Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
398
|
+
{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
399
|
+
{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
|
|
395
400
|
```
|
|
396
401
|
|
|
397
402
|
Nếu 0 finding nào auto-fixable → in:
|
|
@@ -425,6 +430,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
425
430
|
|
|
426
431
|
> **Chạy Business Language Guard trên text vừa sửa TRƯỚC khi ghi** (xem section "Ngôn ngữ nghiệp vụ") — đặc biệt với P2 (sửa câu mơ hồ) / P4 skeleton: không để bản fix tự kéo thuật ngữ kỹ thuật-UI vào PRD.
|
|
427
432
|
|
|
433
|
+
> **Giữ ĐÚNG TẦNG + gọn khi áp fix (altitude):** AC = outcome quan sát được + ref BR, KHÔNG chứa cơ chế. Fix là **chi tiết cơ chế/rule** (retry, timeout, tên/chủ cờ, nhánh lỗi) → **di dời vào bảng BR/BL của UC** (hoặc BR mới), AC chỉ ref; KHÔNG inline vào AC. Fix làm rõ ≥2 nhánh ở đúng tầng → **tách bullet con** hoặc AC/BR mới, đừng nối mệnh đề vào câu cũ. Đừng để AC lặp lại nội dung BR.
|
|
434
|
+
|
|
428
435
|
**Với finding PRD:**
|
|
429
436
|
| check_id | Làm gì |
|
|
430
437
|
|----------|-----------|
|
|
@@ -434,7 +441,7 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
434
441
|
| P4 (Structure) | Thêm section/metadata field còn thiếu (row Status vắng → thêm mặc định `draft`) |
|
|
435
442
|
| P5 (Custom) | Áp dụng như nêu trong suggestion/note |
|
|
436
443
|
|
|
437
|
-
→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm
|
|
444
|
+
→ Sau khi áp dụng, bump version PRD (minor), **reset `| **Status** | draft |` trong Metadata** (PRD vừa đổi sau khi duyệt → phải duyệt lại — đồng bộ với /refine-prd), thêm row Changelog (bảng phẳng, **kê UC/AC/BR bị ảnh hưởng**, + **rollover giữ 5 row gần nhất** dồn dư sang `changelog/` — xem quy ước ở refine-prd Phase 3), và ghi `applied_to_version: "{new_version}"` ở root level của findings (xem "Chọn full vs delta").
|
|
438
445
|
|
|
439
446
|
**Với finding BDD:**
|
|
440
447
|
| check_id | Làm gì |
|
|
@@ -446,8 +453,8 @@ Với mỗi finding `accepted`/`modified` sau khi áp xong → đặt `status: "
|
|
|
446
453
|
| B5 (Metadata) | Thêm @trace header còn thiếu, sinh lại Coverage Matrix / Pre-merge Checklist |
|
|
447
454
|
| B6 (Side effects) | Thêm `And <side-effect>` còn thiếu vào block Then |
|
|
448
455
|
|
|
449
|
-
→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1.
|
|
450
|
-
→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, và đặt `last_updated` thành ngày hôm nay.
|
|
456
|
+
→ Sau khi áp dụng, tăng `@trace.bdd_version` trong header file lên 0.1, **reset `# @trace.status: draft`** trong header (BDD đổi sau khi duyệt → phải duyệt lại).
|
|
457
|
+
→ Đồng thời cập nhật `{paths.trace_dir}/{domain}/{prd-slug}/{UC-ID}.tsv`: đặt cột `bdd_version` thành giá trị `@trace.bdd_version` mới cho mọi row, đặt `uc_status = draft` (khớp header), và đặt `last_updated` thành ngày hôm nay.
|
|
451
458
|
→ Ghi `applied_to_version: "{@trace.bdd_version mới}"` ở root level của findings (xem "Chọn full vs delta").
|
|
452
459
|
|
|
453
460
|
### Phase 3 — Report
|
|
@@ -462,8 +469,9 @@ Changes:
|
|
|
462
469
|
- {tóm tắt change 2}
|
|
463
470
|
|
|
464
471
|
{If PRD}: Version bumped: {old} → {new} | Status: reset về draft (cần duyệt lại)
|
|
465
|
-
{If BDD}: bdd_version: {old} → {new}
|
|
472
|
+
{If BDD}: bdd_version: {old} → {new} | @trace.status: reset về draft (cần duyệt lại)
|
|
466
473
|
|
|
467
474
|
Chạy lại /review-context {file} để xác nhận 0 finding critical còn lại.
|
|
468
|
-
Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
475
|
+
{If PRD}: Khi sạch critical + PO duyệt → đặt | **Status** | approved | trong Metadata rồi /generate-bdd.
|
|
476
|
+
{If BDD}: Khi sạch critical + duyệt → đặt # @trace.status: approved trong header .feature rồi /generate-tech-docs.
|
|
469
477
|
```
|
|
@@ -488,6 +488,7 @@ Skip loại nào không có doc / không có revision đã lưu (`—`).
|
|
|
488
488
|
*Bỏ qua step này nếu không có file TSV nào (đã xử lý bởi path no-TSV của Step 1).*
|
|
489
489
|
|
|
490
490
|
Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
|
|
491
|
+
Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
|
|
491
492
|
**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
|
|
492
493
|
|
|
493
494
|
### Step 7 — Tính aggregate cho dashboard
|
|
@@ -93,6 +93,7 @@ Skip loại nào không có doc / không có revision đã lưu (`—`).
|
|
|
93
93
|
*Bỏ qua step này nếu không có file TSV nào (đã xử lý bởi path no-TSV của Step 1).*
|
|
94
94
|
|
|
95
95
|
Với mỗi file `.tsv` đã xử lý: ghi `spec_ver`, `status`, `last_updated` đã cập nhật lại disk.
|
|
96
|
+
Đồng thời **đồng bộ `uc_status` ← `@trace.status`** của file `.feature` tương ứng (header `.feature` là nguồn-sự-thật về duyệt BDD — người đặt `approved` sau khi review sạch, giống PO đặt PRD Metadata `Status`). Nhờ vậy `approved_ucs` trên dashboard phản ánh đúng thay vì luôn = 0.
|
|
96
97
|
**Đừng** sửa `dev_selftest`/`dev_selftest_at` (do `/dev-run-test` sở hữu) hay `qc_status`/`qc_run_at`/`qc_owner`/`qc_blocked_by` (do `/qc-run-test` + `/report-bug` sở hữu); lệnh này chỉ đọc chúng cho report.
|
|
97
98
|
|
|
98
99
|
### Step 7 — Tính aggregate cho dashboard
|
package/core/FRAMEWORK_VERSION
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.14.
|
|
1
|
+
0.14.9
|