@relipa/ai-flow-kit 0.2.1 → 0.2.2-beta.0

package/README.md

@@ -80,8 +80,8 @@ ak execute PROJ-44  (or ./testcases.md  or  ak execute)
         │
         ▼
 ⛩️ GATE 1 — Pre-flight & Work Plan           [AI + QA]
-  Parse TC file → verify ak-test/{repo}/ exists
-  Check BASE_URL env var + playwright.config.ts
+  Parse TC file → verify AK-Docs/03.Testing/ subfolders exist
+  Check BASE_URL env var + playwright.config.ts + .gitignore covers 04.Evidence/
   Create execution work plan
   QA reviews → "APPROVED"
         │ APPROVED
@@ -341,9 +341,9 @@ ak execute
 ```
 
 **What happens (4-gate Execute Flow):**
-1. **Gate 1 — Pre-flight:** Parse TC file, verify `ak-test/{repo}/` exists, check `BASE_URL` and `playwright.config.ts` — QA reviews → `APPROVED`
+1. **Gate 1 — Pre-flight:** Parse TC file, verify `AK-Docs/03.Testing/` subfolders exist, check `BASE_URL`, `playwright.config.ts`, and `.gitignore` covers `04.Evidence/` — QA reviews → `APPROVED`
 2. **Gate 2 — Script Sync:** Hash-based TC↔script sync — gen new, update changed, skip unchanged (never fabricates selectors — uses Playwright MCP)
-3. **Gate 3 — Execute & Evidence:** Run Playwright, organize evidence per `run-{N}/`, update TC file R1/R2 columns — QA reviews → `APPROVED`
+3. **Gate 3 — Execute & Evidence:** Run Playwright from `AK-Docs/03.Testing/05.Scripts/`, evidence lands in `04.Evidence/` (gitignored) per `run-{N}/`, update TC file R1/R2 columns — QA reviews → `APPROVED`
 4. **Gate 4 — Report & Bug Logging:** Generate `testreport.md`, ask per-bug Jira confirmation — QA reviews → `APPROVED`
 
 > **Multi-AI:** Works with Claude, Codex, Gemini, Cursor, Copilot — the execute-flow skill is loaded via `ak init`/`ak up`.

package/custom/skills/create-system-requirement/SKILL.md

@@ -21,10 +21,9 @@ keywords: system requirement, uc spec, functionId, trace, acceptance test, excep
 
 **Hand-off from coding Gate 1 Pre-flight** (`read-study-requirement`, Step 0) when:
 - No `System-Requirement_v*.md` exists yet for this `functionId`, **or**
-- The existing one's `UC-Spec-Version` header does not match the UC Spec's current version, **or**
-- It exists and matches but its `Status` header is not `✅ Approved`.
+- The existing one's `UC-Spec-Version` header does not match the UC Spec's current version.
 
-Any of these → coding Gate 1 shows a ⚠️ non-blocking warning and **continues** (it does not cancel). DEV can close the gap at any point — before or after the current ticket — by starting a new task with `ak use`, picking **"📐 Create System Requirement"** at the Task type prompt, and running it through both gates to APPROVED.
+Any of these → coding Gate 1 shows a ⚠️ non-blocking warning and **continues** (it does not cancel). DEV can close the gap at any point — before or after the current ticket — by starting a new task with `ak use`, picking **"📐 Create System Requirement"** at the Task type prompt, and running it through both gates to APPROVED. Approval itself isn't tracked inside the document — the file only lands in `AK-Docs/` (and gets committed/pushed) once DEV has approved it, so its presence there is the approval signal.
 
 ---
 
@@ -91,7 +90,7 @@ For every row in the UC Spec's Main Flow, Alternative/Exception Flows, and Busin
 
 #### Writing style & layering (applies to every item in Sections 1–4)
 
-Every item is a stack of layers, each aimed at a different reader — write each layer, don't blend them:
+Every item is a stack of layers, each aimed at a different reader — write each layer, don't blend them. The field name alone tells the reader who it's for — see the "Ai đọc field nào" table at the top of the template. **Do not** tag individual field labels with `[Role]` — that mapping is fixed for the whole document and stated once, up top; repeating it on every item is noise, not signal.
 
 1. **Requirement** — the system behavior in plain business language. No framework names, class names, method names, or library calls (`Rule::unique`, `FormRequest`, `Middleware`, `permission_handle()`, enum class names, etc.). PM must be able to read this layer alone and understand what the system does.
    - ❌ `Rule::unique(...)` → ✅ "The system validates that the Tag name is unique among active Tags."
@@ -99,12 +98,20 @@ Every item is a stack of layers, each aimed at a different reader — write each
    - When a technical concept (e.g. an enum) has a business meaning, state the business impact first (e.g. "Newly created Tags are assigned the default status PENDING") and put the raw technical value in Implementation Reference as a `Tech Reference:` line — **never invent or assume what an enum/status value means in business terms unless the PM has confirmed it**; if unconfirmed, ask in Step 4 or leave it as the raw value with a Gap/Assumption tag. Every `Tech Reference:` line also gets a row in Section 6.2 (Glossary / Term Mapping) — write it once there, don't leave it scattered only inside individual items.
 2. **System Behavior** — how the system processes it, still in plain language (conditions, order of checks, what triggers what). This is what BA/Tester use to write test cases.
 3. **Error Response** (Validation Rules and Exception & Error Handling only) — the expected result for Tester: keep the HTTP status code (never drop it — Tester needs it), paired with a friendly label and the user-facing message, e.g. `HTTP 422 (Validation Error) — "..."`.
-4. **Implementation Reference** — file/class/method/framework rule, for Developer cross-check only. This is where all the technical detail from Step 2 belongs — it never appears in layers 1–2.
+4. **Implementation Reference** — file/class/method/framework rule, for Developer cross-check only. This is where all the technical detail from Step 2 belongs — it never appears in layers 1–2. **Keep it to one line**: `file:line` (or class/method) plus at most one short clause of context. Do not write multi-sentence prose explaining why the current code is wrong or what the fix should look like — Dev reads the code directly for that; this field is a pointer, not a code review.
 
 Keep each layer short — one requirement, one behavior, one result. If a sentence needs 2–3 clauses to say, split it into separate `Requirement` / `System Behavior` / `Result` lines instead of one long sentence.
 
 Classify every item as **Gap** (missing entirely) / **Assumption** (inferred, unconfirmed) / **Decision** (a choice made and confirmed during Q&A) / **Deviation** (implementation differs from what the UC Spec states) — only when one of these applies. A plain fact (explicit in UC Spec or confirmed in code) needs no tag; do not mark every item "Fact" by default, since a Requirement is a fact unless flagged otherwise. This replaces the old Fact/Assumption/Gap convention from `read-study-requirement` Step 1.75 for this skill's output — `read-study-requirement` itself is unaffected.
 
+**Writing the `Classification` value** — one decision → one line: `[state] — [ID] ([who decided]): [content, one clause]`, e.g. `Decision — OQ-42 (BA): keep the losing customer's cart unchanged`. **Two or more decisions** (e.g. BA decided part of it, Dev decided the rest) → do NOT chain them with `;` in one sentence (unreadable, even to a Tech Lead) — one sub-bullet per decision instead, same `[ID] ([who]): [content]` format:
+```
+- **Classification:** Gap → Decision
+  - OQ-35 (BA): chose the order-attempt-token mechanism to prevent duplicate orders
+  - D-03 (Dev): server responds HTTP 200 with the original order; token expires after 30 minutes
+```
+`OQ-xx` = a decision inherited from BA (originally from the UC Spec). `D-xx` = a decision made while drafting this System Requirement — log it in Section 8 (Decision Log).
+
 ---
 
 ### Step 3.5: Traceability Verification — 1-1 Gap Audit [Gate 1]
@@ -160,7 +167,24 @@ Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N
 **System-Requirement-Version:** v{N}
 **UC-Spec-Version:** [functionId] @ v{N}   <!-- MANDATORY — the 1-1 matching anchor -->
 **Source UC Spec:** AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md
-**Status:** ⏸️ Waiting for Approval
+
+---
+
+## Who reads what field (stated once — not repeated per item)
+
+The field → reader mapping is fixed for the whole document, so it's declared once here instead of tagged on every item:
+
+| Field | Who needs it |
+|---|---|
+| `Requirement` | PM/BrSE/Comtor, Tester |
+| `System Behavior` | Tester |
+| `Error Response` | Tester (full line, incl. HTTP code) — PM/BrSE/Comtor only needs the user-facing message |
+| `Traced UC Ref` / `Traced UC BR` / `Traced Exception Flow` | PM/BrSE/Comtor (cross-check against UC Spec) |
+| `Classification` | PM/BrSE/Comtor — this is the "needs a decision" / "already decided" signal |
+| `Implementation Reference` / `Tech Reference` | Dev |
+| Section 5 (Acceptance Test Scenarios) | Tester |
+
+**Dev and AI read the entire document**, every field, regardless of the table above — Dev needs it to implement, AI needs it across multiple gates (coding Gate 3, testcase generation, traceability audit).
 
 ---
 
@@ -191,7 +215,7 @@ Each item below is layered: **Requirement** (business language, for PM) → **Sy
 - **System Behavior:** [how the system processes it — conditions, order of checks]
 - **Traced UC Ref:** Main Flow #3
 - **Classification:** [Gap | Assumption | Decision | Deviation — omit this line if it's a plain fact]
-- **Implementation Reference:** [file:line / class / method]
+- **Implementation Reference:** [file:line / class / method — one line, no multi-sentence explanation]
 
 <!-- repeat FR-02, FR-03, ... in the same block format -->
 
@@ -271,7 +295,13 @@ Only items tagged Gap / Assumption / Decision / Deviation land here — a plain
 |---|---|---|
 
 ## 8. Decision Log
-[Question asked → decision/answer received → date. Unresolved Gaps stay listed here, never silently dropped. (Renamed from "Open Questions Log" — every entry here already has an answer; unresolved items are Gaps, tracked in Section 7.)]
+Short lookup table — do not restate the full question/answer, that detail already lives in the `Classification` line of the item it applies to (writing it twice is redundant). Just enough to trace back: decision ID → who decided → date → one-line summary.
+
+| ID | Decided by | Date | Summary |
+|---|---|---|---|
+| OQ-xx | PM/BA | [YYYY-MM-DD] | [one line — full detail lives in the matching item in Sections 1–4] |
+
+Unresolved Gaps stay listed in Section 7, not here — this table only holds decisions that **already have** an answer.
 
 ## 9. Change Log
 | Date | Ticket | Change | Note |
@@ -308,6 +338,10 @@ Please review — matching 1-1 with UC Spec v{N} is the point of this document.
   → Type APPROVED (then run `aiflow task next`) to close this task and clear
     the Gate 1 warning for tickets on this functionId
   → Or provide feedback to update
+  → Non-tech reviewer (PM/Comtor/BrSE/Tester)? See
+    docs/common/System-Requirement-Read-Guide.md for what Classification/
+    Implementation Reference/Tech Reference mean, which fields you can skip,
+    an FAQ, and a review checklist.
 
 ⚠️  Until this task is APPROVED, coding Gate 1 for this functionId will keep
     showing a non-blocking warning (it does not cancel).
@@ -316,7 +350,7 @@ Please review — matching 1-1 with UC Spec v{N} is the point of this document.
 
 - Any Gap still open → cannot approve; go back to Step 4 (re-open Gate 1).
 - DEV feedback → update draft → re-show prompt.
-- `APPROVED` → write `Status: ✅ Approved`, task is done — coding Gate 1 unlocks.
+- `APPROVED` → task is done — commit/push the file so it becomes visible to PM; coding Gate 1 unlocks.
 
 ---
 
@@ -363,4 +397,8 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 - ❌ **DO NOT** tag every item "Fact" — a plain fact is the unmarked default; only tag `Gap`, `Assumption`, `Decision`, or `Deviation` when one applies.
 - ❌ **DO NOT** state or assume the business meaning of an enum/status value (e.g. what `PENDING` "means" for the business) unless the PM has confirmed it — reference the raw technical value in `Implementation Reference` and tag it `Assumption` or `Gap` until confirmed.
 - ✅ **MUST** mirror every `Tech Reference:` used in Sections 1–4 as a row in Section 6.2 (Glossary / Term Mapping) — don't leave the mapping only inside individual items.
+- ❌ **DO NOT** tag individual field labels with `[Role]` (e.g. `**Requirement [PM/BrSE/Comtor]:**`) — the field → reader mapping is declared once in the "Who reads what field" table at the top and never repeated per item; that repetition was tried and reverted for being pure noise once the convention is stated.
 - ❌ **DO NOT** include Section 6.3 (External System Interfaces) when the UC has no integration outside the app's own UI/DB — omit the subsection entirely rather than leaving an empty table.
+- ❌ **DO NOT** restate a full question/answer in Section 8 (Decision Log) when the same decision is already explained inline in an item's `Classification` line — Section 8 is a short lookup table (ID → who → date → one-line summary) that points back to the item, not a duplicate narrative.
+- ❌ **DO NOT** write multi-sentence prose in `Implementation Reference` explaining why current code is wrong or how to fix it — one line (`file:line` + at most one short clause) is enough; Dev reads the code itself for the rest.
+- ❌ **DO NOT** chain two or more decisions into one `Classification` sentence with `;` (e.g. "BA decided OQ-35...; DEV decided D-03...") — split into one sub-bullet per decision (`[ID] ([who]): [content]`), see "How to write Classification" above. This was reported as hard to read even by a Tech Lead.

package/custom/skills/create-system-requirement/system-requirement-template-v1.md

@@ -1,128 +1,282 @@
 # Template Yêu Cầu Hệ Thống (System Requirement) — Phiên bản v1
 
-Cấu trúc chuẩn của tài liệu System Requirement. Phải trace 1-1 với một phiên bản UC Spec cụ thể — không bao giờ bịa ra nội dung mà UC Spec không có.
+Đây là cấu trúc chuẩn cho tài liệu **System Requirement**.
+
+Mỗi tài liệu System Requirement phải **trace 1-1 với một phiên bản UC Spec cụ thể**. Không tự bổ sung hoặc suy diễn nội dung nếu nội dung đó không có căn cứ từ UC Spec.
 
 ---
 
 # Tài Liệu Yêu Cầu Hệ Thống: [functionId] — [Tên Chức Năng]
 
 **Ngày tạo (Date):** [YYYY-MM-DD]
+
 **Phiên bản System Requirement (System-Requirement-Version):** v{N}
-**Phiên bản UC Spec tham chiếu (UC-Spec-Version):** [functionId] @ v{N}   <!-- BẮT BUỘC — mốc khớp 1-1 -->
-**UC Spec nguồn (Source UC Spec):** AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md
-**Trạng thái (Status):** ⏸️ Waiting for Approval
+
+**Phiên bản UC Spec tham chiếu (UC-Spec-Version):** [functionId] @ v{N}
+
+<!-- BẮT BUỘC — mốc khớp 1-1 -->
+
+**UC Spec nguồn (Source UC Spec):**
+AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md
+
+---
+
+## Ai cần đọc phần nào?
+
+| Field                                                      | Ai cần đọc                                                                                                          |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `Requirement`                                              | PM/BrSE/Comtor, Tester                                                                                              |
+| `System Behavior`                                          | Tester                                                                                                              |
+| `Error Response`                                           | Tester đọc đầy đủ, bao gồm cả HTTP code. PM/BrSE/Comtor chỉ cần đọc câu thông báo hiển thị, có thể bỏ qua HTTP code |
+| `Traced UC Ref` / `Traced UC BR` / `Traced Exception Flow` | PM/BrSE/Comtor dùng để đối chiếu với UC Spec                                                                        |
+| `Classification`                                           | PM/BrSE/Comtor dùng để nhận biết nội dung nào **cần quyết định** hoặc **đã được chốt**                              |
+| `Implementation Reference` / `Tech Reference`              | Dev                                                                                                                 |
+| Mục 5 (Acceptance Test Scenarios)                          | Tester                                                                                                              |
+
+> **Dev và AI đọc toàn bộ tài liệu**, không phân biệt theo field.
+>
+> * Dev cần đầy đủ thông tin để triển khai.
+> * AI sử dụng tài liệu ở nhiều gate khác nhau, ví dụ: coding Gate 3, sinh testcase và audit traceability.
+>
+> Bảng trên chủ yếu giúp PM/BrSE/Comtor và Tester biết phần nào cần tập trung đọc, và phần nào có thể bỏ qua nếu không liên quan trực tiếp đến công việc của mình.
 
 ---
 
 ## Tóm tắt điều hành (Executive Summary)
-- **Mục đích (Purpose):** [1 câu — tài liệu này bao gồm gì và vì sao nó tồn tại]
-- **Tình trạng triển khai (Implementation status):** [ví dụ: Chưa bắt đầu / Đang triển khai / Khớp với UC Spec v{N}]
-- **Độ khớp truy vết (Traceability coverage — từ audit Step 3.5):** [X]/[Y] mục UC Spec đã có System Requirement tương ứng · [Z] item bị gỡ vì không có căn cứ (unsupported)
-- **Các sai khác chính so với UC Spec (Key deviations from UC Spec):** [danh sách các mục được gắn nhãn Deviation, hoặc "Không phát hiện sai khác"]
-- **Hành động cần từ PM (Action needed from PM):** [danh sách các Gap/Assumption chưa được giải quyết cần PM xác nhận, hoặc "Không có — sẵn sàng chuyển giao cho Dev"]
 
+Phần này giúp người đọc nhanh chóng nắm được phạm vi tài liệu, mức độ hoàn thiện và những điểm cần quyết định trước khi chuyển sang triển khai.
+
+* **Mục đích (Purpose):**
+  [1 câu — tài liệu này bao gồm những gì và vì sao tài liệu này được tạo]
+
+* **Tình trạng triển khai (Implementation status):**
+  [ví dụ: Chưa bắt đầu / Đang triển khai / Khớp với UC Spec v{N}]
+
+* **Độ khớp truy vết (Traceability coverage — từ audit Step 3.5):**
+  [X]/[Y] mục UC Spec đã có System Requirement tương ứng · [Z] item bị gỡ vì không có căn cứ (unsupported)
+
+* **Các sai khác chính so với UC Spec (Key deviations from UC Spec):**
+  [danh sách các mục được gắn nhãn Deviation, hoặc "Không phát hiện sai khác"]
+
+* **Hành động cần từ PM (Action needed from PM):**
+  [danh sách các Gap/Assumption chưa được giải quyết cần PM xác nhận, hoặc "Không có — sẵn sàng chuyển giao cho Dev"]
 
 ---
 
 ## 0. Ma trận truy vết (Traceability Matrix)
+
+Bảng này giúp đối chiếu trực tiếp giữa UC Spec và các mục tương ứng trong System Requirement.
+
 | Tham chiếu UC (Flow / BR) | Mục System Requirement tương ứng |
-|---|---|
-| Main Flow bước 3 | FR-01 |
-| Exception Flow B | FR-05, ER-02 |
-| BR1.1 | VR-01 |
+| ------------------------- | -------------------------------- |
+| Main Flow bước 3          | FR-01                            |
+| Exception Flow B          | FR-05, ER-02                     |
+| BR1.1                     | VR-01                            |
+
+---
 
 ## 1. Yêu Cầu Chức Năng (Functional Requirements)
 
-Mỗi mục dưới đây có 3 tầng: **Requirement** (ngôn ngữ nghiệp vụ, dành cho PM) → **System Behavior** (dành cho BA/Tester) → **Implementation Reference** (chi tiết kỹ thuật, chỉ dành cho Dev — không bao giờ xuất hiện ở 2 tầng phía trên).
+Mỗi Functional Requirement được mô tả theo 3 tầng, từ dễ hiểu đến chi tiết kỹ thuật:
+
+1. **Requirement**: mô tả hệ thống cần đáp ứng điều gì bằng ngôn ngữ nghiệp vụ.
+2. **System Behavior**: mô tả hệ thống xử lý như thế nào để đáp ứng Requirement.
+3. **Implementation Reference**: thông tin kỹ thuật để Dev tham chiếu khi triển khai.
+
+`Implementation Reference` chỉ chứa thông tin kỹ thuật và **không được đưa ngược lên Requirement hoặc System Behavior**.
 
 ### FR-01: [tên ngắn gọn mô tả hành vi nghiệp vụ]
-- **Requirement:** [hành vi hệ thống bằng ngôn ngữ nghiệp vụ, không dùng tên framework/class/method]
-- **System Behavior:** [hệ thống xử lý như thế nào — điều kiện, thứ tự kiểm tra]
-- **Traced UC Ref:** Main Flow #3
-- **Classification:** [Gap | Assumption | Decision | Deviation — bỏ dòng này nếu là một fact đơn thuần]
-- **Implementation Reference:** [file:line / class / method]
+
+* **Requirement:**
+  [hành vi hệ thống bằng ngôn ngữ nghiệp vụ, không dùng tên framework/class/method]
+
+* **System Behavior:**
+  [hệ thống xử lý như thế nào — điều kiện, thứ tự kiểm tra]
+
+* **Traced UC Ref:** Main Flow #3
+
+* **Classification:**
+  [Gap | Assumption | Decision | Deviation — bỏ dòng này nếu là một fact đơn thuần]
+
+* **Implementation Reference:**
+  [file:line / class / method — 1 câu, không diễn giải dài; Dev đọc code trực tiếp khi cần chi tiết hơn]
 
 <!-- lặp lại FR-02, FR-03, ... theo cùng cấu trúc trên -->
 
+---
+
 ## 2. Yêu Cầu Phi Chức Năng (Non-Functional Requirements)
 
+Phần này mô tả các yêu cầu không trực tiếp thuộc nghiệp vụ chức năng, ví dụ như performance hoặc security.
+
 ### NFR-01: [tên ngắn]
-- **Requirement:** [ngôn ngữ nghiệp vụ — ví dụ: yêu cầu về performance/security]
-- **System Behavior:** [cách yêu cầu này được thực thi, bằng ngôn ngữ đơn giản]
-- **Traced UC Ref:** BR3.1
-- **Classification:** [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
-- **Implementation Reference:** [file:line / class / method]
+
+* **Requirement:**
+  [ngôn ngữ nghiệp vụ — ví dụ: yêu cầu về performance/security]
+
+* **System Behavior:**
+  [cách yêu cầu này được thực thi, bằng ngôn ngữ đơn giản]
+
+* **Traced UC Ref:** BR3.1
+
+* **Classification:**
+  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
+
+* **Implementation Reference:**
+  [file:line / class / method]
+
+---
 
 ## 3. Quy Tắc Nghiệp Vụ → Quy Tắc Kiểm Tra Hợp Lệ (Business Rules → Validation Rules)
 
+Phần này chuyển các Business Rules trong UC Spec thành Validation Rules mà hệ thống thực hiện.
+
 ### VR-01: [tên ngắn]
-- **Requirement:** [ví dụ: "Tên Tag phải là duy nhất trong số các Tag đang active."]
-- **System Behavior:** [ví dụ: "Hệ thống kiểm tra tên Tag với toàn bộ Tag đang active trước khi lưu."]
-- **Error Response:** HTTP 422 (Validation Error) — "[thông báo hiển thị cho người dùng]"
-- **Traced UC BR:** BR1.1
-- **Classification:** [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
-- **Implementation Reference:** [ví dụ: `Rule::unique(...)` trong `StoreTagRequest`]
+
+* **Requirement:**
+  [ví dụ: "Tên Tag phải là duy nhất trong số các Tag đang active."]
+
+* **System Behavior:**
+  [ví dụ: "Hệ thống kiểm tra tên Tag với toàn bộ Tag đang active trước khi lưu."]
+
+* **Error Response:**
+  HTTP 422 (Validation Error) — "[thông báo hiển thị cho người dùng]"
+
+* **Traced UC BR:** BR1.1
+
+* **Classification:**
+  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
+
+* **Implementation Reference:**
+  [ví dụ: `Rule::unique(...)` trong `StoreTagRequest`]
+
+---
 
 ## 4. Xử Lý Ngoại Lệ & Lỗi (Exception & Error Handling)
 
+Phần này mô tả các trường hợp hệ thống không thể tiếp tục xử lý theo Main Flow, bao gồm điều kiện xảy ra, cách hệ thống phản hồi và thông báo trả về.
+
 ### ER-01: [điều kiện kích hoạt, bằng ngôn ngữ nghiệp vụ]
-- **Requirement:** [ví dụ: "Chỉ người dùng có quyền CREATE mới được tạo Tag."]
-- **System Behavior:** [ví dụ: "Request bị từ chối vì người gọi không có quyền cần thiết."]
-- **Error Response:** HTTP 403 (Forbidden) — "[thông báo hiển thị cho người dùng]"
-- **Traced Exception Flow:** Exception Flow B
-- **Classification:** [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
-- **Implementation Reference:** [error code/class/middleware hiện có]
+
+* **Requirement:**
+  [ví dụ: "Chỉ người dùng có quyền CREATE mới được tạo Tag."]
+
+* **System Behavior:**
+  [ví dụ: "Request bị từ chối vì người gọi không có quyền cần thiết."]
+
+* **Error Response:**
+  HTTP 403 (Forbidden) — "[thông báo hiển thị cho người dùng]"
+
+* **Traced Exception Flow:** Exception Flow B
+
+* **Classification:**
+  [Gap | Assumption | Decision | Deviation — bỏ nếu là fact đơn thuần]
+
+* **Implementation Reference:**
+  [error code/class/middleware hiện có]
+
+---
 
 ## 5. Kịch Bản Kiểm Thử Chấp Nhận (Acceptance Test Scenarios)
+
+Phần này mô tả các kịch bản mà Tester sử dụng để xác nhận hệ thống đáp ứng các yêu cầu đã được định nghĩa.
+
 ### AT-01: [Tên kịch bản] (Main Flow)
-- **Given** ...
-- **When** ...
-- **Then** ...
-- **Requirement Coverage:** FR-01, FR-03
+
+* **Given** ...
+* **When** ...
+* **Then** ...
+* **Requirement Coverage:** FR-01, FR-03
 
 ### AT-02: [Tên kịch bản] (Exception Flow B)
-- **Given** ...
-- **When** ...
-- **Then** ...
-- **Requirement Coverage:** VR-01, ER-01
+
+* **Given** ...
+* **When** ...
+* **Then** ...
+* **Requirement Coverage:** VR-01, ER-01
+
+---
 
 ## 6. Bối Cảnh Hệ Thống Hiện Có (Existing System Context)
 
+Phần này giúp người đọc hiểu nhanh các khu vực liên quan trong hệ thống hiện tại.
+
+Không đưa chi tiết triển khai sâu vào đây. Các thông tin kỹ thuật chi tiết phải được đặt trong **Implementation Reference** của từng item tương ứng.
+
 ### 6.1 Tổng Quan Các Khu Vực Hệ Thống (System Areas Summary)
-Chỉ tóm tắt — chi tiết triển khai sâu hơn thuộc về mục **Implementation Reference** của từng item ở trên, không đặt ở đây.
+
+Chỉ tóm tắt các khu vực có liên quan.
 
 | Khu vực (Area) | Tóm tắt (Summary) |
-|---|---|
-| API | ... |
-| Model | ... |
-| Validation | ... |
-| Migration | ... |
-| Test | ... |
+| -------------- | ----------------- |
+| API            | ...               |
+| Model          | ...               |
+| Validation     | ...               |
+| Migration      | ...               |
+| Test           | ...               |
 
 ### 6.2 Bảng Thuật Ngữ / Ánh Xạ Thuật Ngữ (Glossary / Term Mapping)
-Mỗi `Tech Reference:` được dùng trong Mục 1–4 phải có một dòng tương ứng ở đây — một nơi duy nhất để tra thuật ngữ nghiệp vụ ánh xạ sang cái gì trong code, thay vì phải lục từng item. Chỉ đưa vào các thuật ngữ đã được PM xác nhận ý nghĩa nghiệp vụ (Decision) hoặc giá trị thô chưa được PM xác nhận nhưng đã gắn nhãn tương ứng — không bao giờ đoán ý nghĩa.
 
-| Thuật Ngữ Nghiệp Vụ (Business Term) | Tham Chiếu Kỹ Thuật (Technical Reference) | Classification |
-|---|---|---|
-| [ví dụ: "trạng thái mặc định PENDING"] | `TagStatusEnum::PENDING` | Decision (PM xác nhận ngày [date]) / Assumption (chưa xác nhận) |
+Mỗi `Tech Reference:` được sử dụng trong Mục 1–4 phải có một dòng tương ứng tại đây.
+
+Mục đích là tạo **một nơi duy nhất để tra cứu** mối liên hệ giữa thuật ngữ nghiệp vụ và Technical Reference trong code, thay vì phải tìm lại từng item.
+
+Chỉ đưa vào bảng:
 
-### 6.3 Giao Diện Với Hệ Thống Ngoài (External System Interfaces) *(tùy chọn — chỉ có khi UC này tích hợp với hệ thống bên ngoài UI/DB của app, ví dụ third-party API, webhook, message queue)*
-UC Spec chỉ mô tả luồng UI/nghiệp vụ, không mô tả hợp đồng tích hợp bên ngoài — mục này ghi lại các tích hợp đó nếu có. Bỏ hẳn mục này nếu UC không có giao diện bên ngoài nào.
+* Thuật ngữ đã được PM xác nhận ý nghĩa nghiệp vụ thông qua `Decision`.
+* Giá trị thô chưa được PM xác nhận nhưng đã được gắn `Classification` tương ứng.
 
-| Giao diện (Interface) | Chiều (Direction) | Protocol/Format | Ghi chú (Note) |
-|---|---|---|---|
-| [ví dụ: Payment Gateway API] | Outbound | REST/JSON | ... |
+Không tự suy đoán ý nghĩa nghiệp vụ.
+
+| Thuật Ngữ Nghiệp Vụ (Business Term)    | Tham Chiếu Kỹ Thuật (Technical Reference) | Classification                                                  |
+| --------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------- |
+| [ví dụ: "trạng thái mặc định PENDING"] | `TagStatusEnum::PENDING`                  | Decision (PM xác nhận ngày [date]) / Assumption (chưa xác nhận) |
+
+### 6.3 Giao Diện Với Hệ Thống Ngoài (External System Interfaces)
+
+*(Tùy chọn — chỉ có khi UC này tích hợp với hệ thống bên ngoài UI/DB của app, ví dụ third-party API, webhook, message queue)*
+
+UC Spec chủ yếu mô tả luồng UI và nghiệp vụ. Nếu chức năng có giao tiếp với hệ thống bên ngoài, thông tin tích hợp được ghi nhận tại đây.
+
+Nếu UC không có giao diện bên ngoài thì bỏ hẳn mục này.
+
+| Giao diện (Interface)        | Chiều (Direction) | Protocol/Format | Ghi chú (Note) |
+| ----------------------------- | ------------------ | ---------------- | -------------- |
+| [ví dụ: Payment Gateway API] | Outbound           | REST/JSON        | ...            |
+
+---
 
 ## 7. Giả Định / Điểm Thiếu / Quyết Định / Sai Khác (Assumptions / Gaps / Decisions / Deviations)
-Chỉ những item được gắn nhãn Gap / Assumption / Decision / Deviation mới xuất hiện ở đây — một fact đơn thuần là trạng thái mặc định (không gắn nhãn) của mọi item ở trên và không lặp lại trong bảng này.
+
+Chỉ các item được gắn nhãn `Gap`, `Assumption`, `Decision` hoặc `Deviation` mới xuất hiện tại đây.
+
+Các fact đơn thuần không cần đưa vào bảng này vì đó là trạng thái mặc định của các item trong Mục 1–4.
 
 | Loại (Type) | Item | Cách xử lý (Resolution) |
-|---|---|---|
+| ----------- | ---- | ----------------------- |
+
+---
 
 ## 8. Nhật Ký Quyết Định (Decision Log)
-[Câu hỏi đã đặt → quyết định/câu trả lời nhận được → ngày. Các Gap chưa giải quyết vẫn phải được liệt kê ở đây, không bao giờ bị bỏ qua âm thầm.]
+
+Đây là bảng tra cứu ngắn gọn, giúp tìm ngược từ ID quyết định đến người chốt, ngày chốt và nội dung chính.
+
+Không cần diễn giải lại đầy đủ câu hỏi và câu trả lời vì chi tiết đã được ghi tại `Classification` của item tương ứng trong Mục 1–4.
+
+| ID    | Người chốt | Ngày         | Tóm tắt                                                     |
+| ----- | ---------- | ------------ | ----------------------------------------------------------- |
+| OQ-xx | PM/BA      | [YYYY-MM-DD] | [1 dòng — chi tiết đầy đủ xem tại item tương ứng ở Mục 1–4] |
+
+Quy tắc:
+
+* `OQ-xx` / `D-xx` đã có câu trả lời thì ghi tại đây.
+* Gap chưa được giải quyết vẫn phải ghi tại Mục 7.
+* Không đưa Gap chưa có quyết định vào Decision Log.
+
+---
 
 ## 9. Nhật Ký Thay Đổi (Change Log)
-| Ngày (Date) | Ticket | Thay đổi (Change) | Ghi chú (Note) |
-|---|---|---|---|
-| [YYYY-MM-DD] | — | Tạo lần đầu từ UC Spec v{N} | |
+
+| Ngày (Date)  | Ticket | Thay đổi (Change)           | Ghi chú (Note) |
+| ------------ | ------ | --------------------------- | -------------- |
+| [YYYY-MM-DD] | —      | Tạo lần đầu từ UC Spec v{N} |                |