@relipa/ai-flow-kit 0.2.0 → 0.2.1

package/custom/skills/ba-skills/skill-ba-qna-v1.md

@@ -28,6 +28,11 @@ Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem
   - Điền cột Mức độ ảnh hưởng (🔴 Blocking / 🟡 Non-blocking) đã gắn ở Bước 2.
 - **Bước 4: Nhận phản hồi và Cập nhật (Process Responses):**
   - Khi nhận được câu trả lời: Đọc kỹ để đảm bảo câu trả lời đã giải quyết triệt để câu hỏi.
+  - Ghi nhận đầy đủ 3 cột theo dõi phản hồi cho mỗi câu đã trả lời:
+    - **Người trả lời** — mặc định tự lấy từ `git config user.email` (chạy `git config user.email`, fallback `git config user.name` nếu email trống) của người đang thao tác trong phiên hiện tại; nếu BA chỉ định rõ người trả lời khác (ví dụ trả lời hộ khách hàng, hoặc người phản hồi không phải chính người đang chat) thì dùng giá trị BA nhập, không tự lấy git config.
+    - **Ngày trả lời** — tự động lấy theo ngày giờ hệ thống hiện tại (không hỏi lại BA), định dạng `dd/mm/yyyy`.
+    - **Nguồn** — luôn hỏi BA nhập tay (ví dụ: "Khách hàng", "Nội bộ team", "Team Marketing", "Team Dev"...); không tự suy đoán hoặc đặt giá trị mặc định.
+    Câu hỏi còn **Open** để trống cả 3 cột này (`—`).
   - Đã rõ ràng → đánh dấu **Confirmed**, cập nhật thông tin đó trực tiếp vào tài liệu phân tích hiện tại, xóa marker `[PENDING - QA-ID]` liên quan nếu có.
   - Chưa rõ ràng / khách hàng chưa trả lời được ngay:
     - 🟡 Non-blocking → giữ **Open** (deferred), tiếp tục các câu khác/gate tiếp theo bình thường, ghi marker `[PENDING - QA-ID]` tại vị trí nội dung liên quan trong tài liệu.
@@ -42,6 +47,7 @@ Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem
 - [ ] Mỗi câu hỏi đã có nhãn Mức độ ảnh hưởng (🔴 Blocking / 🟡 Non-blocking) chưa?
 - [ ] Số lượng câu hỏi có phản ánh đúng độ phức tạp thực tế của yêu cầu, không bị gò về một số cố định không?
 - [ ] Đã cập nhật đúng và đầy đủ tất cả câu trả lời của khách hàng vào tài liệu phân tích chưa? (Không bỏ sót bất kỳ điểm chốt nào).
+- [ ] Mỗi câu hỏi **Confirmed** đã điền đủ Người trả lời, Ngày trả lời, Nguồn chưa?
 - [ ] Mọi nội dung phụ thuộc câu hỏi còn Open đã có marker `[PENDING - QA-ID]` tại đúng vị trí, chưa bị tự suy diễn để lấp đầy?
 
 ## 5. Output mong đợi (Expected Output)

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

@@ -16,7 +16,7 @@ keywords: system requirement, uc spec, functionId, trace, acceptance test, excep
 
 `create-system-requirement` is its own **task type** — 2 gates, selectable in the "Task type:" prompt of `ak use` (or auto-detected by `aiflow prompt "..."` — see `scripts/detect.js`). It is not invoked inline from within a coding ticket's session; it runs as its own task, tied to the `functionId` (not to a coding ticket).
 
-- **Gate 1** = Steps 0–4 below (resolve UC Spec, investigate source code, draft, Q&A until every Gap is Confirmed).
+- **Gate 1** = Steps 0–4 below (resolve UC Spec, investigate source code, draft, 1-1 traceability audit, Q&A until every Gap is Confirmed).
 - **Gate 2** = Steps 5–7 below (split decision, write output, present for APPROVED).
 
 **Hand-off from coding Gate 1 Pre-flight** (`read-study-requirement`, Step 0) when:
@@ -36,7 +36,7 @@ Any of these → coding Gate 1 shows a ⚠️ non-blocking warning and **continu
 
 0. `git status --porcelain` → clean tree → `git pull --ff-only`; dirty tree → skip pull, notify DEV (same rule as `read-study-requirement` Step 1.0).
 1. Resolve `functionId` from `.aiflow/context/current.json` (or ask DEV once if absent).
-2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version). **Not found → STOP.** Tell DEV the UC Spec must exist and be BA-signed-off before System Requirement can be created — this skill never fabricates a UC.
+2. Locate the current UC Spec: `AK-Docs/02.BA-Specs/04.UC-Specs/[functionId]/UC-Spec_v{N}.md` (highest non-archived version). **Not found → STOP.** Tell DEV the UC Spec must exist and be PM-signed-off before System Requirement can be created — this skill never fabricates a UC.
 3. Check `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v*.md`:
    - **None exists** → Mode = `CREATE` (go to Step 1).
    - **Exists, `UC-Spec-Version` matches current UC Spec version** → nothing to do — this task is not needed; tell DEV the coding Gate 1 (`read-study-requirement`) can proceed directly.
@@ -64,6 +64,17 @@ Same methodology as `read-study-requirement` Step 1 (steps 4–5), reused here:
 
 This step exists so System Requirement reflects what the system *can actually do today*, not just what the UC Spec says in the abstract.
 
+#### Token/session cost control (investigate once, not once per rule)
+
+This is the single most expensive step in the whole skill — most of the session budget goes here, not into drafting. The cost driver is almost always **re-opening the same file repeatedly**, once per Business Rule/Flow step, instead of investigating the module once and reusing the findings. Apply these levers, in priority order:
+
+1. **GitNexus MCP first, always** — if `.mcp.json` has a `gitnexus` entry, `context()`/`query()`/`impact()` replace multi-file manual reads for that area entirely. Do not fall back to manual `grep`/`Read` for a module GitNexus already covers.
+2. **Delegate the exploration itself to `Explore` sub-agents when GitNexus is unavailable or doesn't cover an area** — spawn one `Explore` agent per concern (e.g. one for "checkout controller + transaction boundaries", one for "cart/pricing repository", one for "frontend checkout flow"), run them in parallel, and have each return a condensed finding (file:line + 1–2 sentence behavior note per item) — not raw file contents. This keeps the bulk of the raw file reading inside disposable sub-agent context instead of the main session's context, which is the actual lever that controls session-token cost, independent of which model is running the main skill.
+3. **Investigate per module/concern, not per Business Rule.** Read/query "the checkout transaction flow" once as a whole, then answer 10 Business Rules from that one pass — do not re-open `OrderController.php` from scratch for each BR that happens to touch it.
+4. **Keep a running Investigation Notes table** (UC ref → file:line → 1-line finding) as you go, built from GitNexus/Explore output. Step 3 drafting must read from this table, not trigger a fresh file read per FR/VR/ER item. Only re-open a file if the table doesn't already answer the question at hand.
+
+Two ways to spend the resulting savings, not to skip investigation: (a) let a cheaper/faster model draft Sections 1–5 from a *smaller, denser* Investigation Notes table instead of raw exploration noise, or (b) reinvest the savings into the Step 3.5 traceability audit below, which is where the Opus/Sonnet quality gap in practice tends to show up (missed edge cases), not in prose quality.
+
 ---
 
 ### Step 3: Draft Content — Translate UC → System Requirement [Gate 1]
@@ -82,10 +93,10 @@ For every row in the UC Spec's Main Flow, Alternative/Exception Flows, and Busin
 
 Every item is a stack of layers, each aimed at a different reader — write each layer, don't blend them:
 
-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/BA must be able to read this layer alone and understand what the system does.
+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."
    - ❌ `permission_handle()` → ✅ "Only users with CREATE permission can create Tags."
-   - 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 BA 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.
+   - 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.
@@ -96,12 +107,28 @@ Classify every item as **Gap** (missing entirely) / **Assumption** (inferred, un
 
 ---
 
+### Step 3.5: Traceability Verification — 1-1 Gap Audit [Gate 1]
+
+Step 3 asks for a traced source on every item *while drafting*, but drafting under time/token pressure is not a reliable substitute for actually checking. Run this as a separate, explicit pass over the finished draft — using Section 0 (Traceability Matrix) as the working artifact — before opening Q&A in Step 4. This is a checklist walk, not a re-investigation; it should be cheap.
+
+**Direction A — UC Spec → System Requirement (coverage: did we forget anything?):** Walk every row of the UC Spec read in Step 1 — each Main/Alternative/Exception Flow step, each Business Rule, each NFR, each Pre/Post-Condition — and confirm the Traceability Matrix lists at least one FR/NFR/VR/ER against it.
+- Listed → leave as is.
+- Missing → **Gap — Missing Coverage.** Add a row to Section 7 tagged `Gap` citing the UC reference, and add it to the Step 4 Q&A queue. Do not invent an item just to fill the matrix cell, and do not quietly drop the row.
+
+**Direction B — System Requirement → UC Spec (grounding: did we invent anything?):** Walk every FR/NFR/VR/ER/AT item drafted in Sections 1–5 and re-check its `Traced UC Ref`/`Traced UC BR`/`Requirement Coverage` line against the actual UC Spec text from Step 1 (not from memory of having read it).
+- Traces to real content → leave as is.
+- Doesn't trace to anything that's actually there (invented, or drifted onto an unrelated UC item) → **Gap — Unsupported Item.** Either correct the trace to the right UC reference, or if truly ungrounded, remove the item and note why in Section 7/Change Log.
+
+Record the result as two counts — `UC items matched: X/Y` and `Unsupported items removed: Z` — and carry them into the Gate 2 prompt (Step 7). Any finding from this pass is a Gap and follows the same hard rule as Step 4 below: **do not proceed to Gate 2 while it's unresolved** — either resolve it via Q&A or get an explicit DEV/PM acknowledgement that it's accepted as a known, tracked gap (never a silent pass-through).
+
+---
+
 ### Step 4: Clarify via Q&A (ask until Confirmed) [Gate 1]
 
-- Ask **one question at a time**, prioritizing unresolved Assumptions/Gaps from Step 3.
-- **Do not run `aiflow task next` into Gate 2 while any Gap remains unresolved.** This is the hard rule from proposal #7 — no fabrication, no "reasonable default" for missing UC content. If DEV genuinely cannot answer (needs BA), stop and record it as an unresolved Gap in Section 7 rather than guessing.
+- Ask **one question at a time**, prioritizing unresolved Assumptions/Gaps from Step 3 and any coverage/grounding Gaps surfaced by Step 3.5.
+- **Do not run `aiflow task next` into Gate 2 while any Gap remains unresolved.** This is the hard rule from proposal #7 — no fabrication, no "reasonable default" for missing UC content. If DEV genuinely cannot answer (needs PM), stop and record it as an unresolved Gap in Section 7 rather than guessing.
 - Do NOT invoke `superpowers:brainstorming` (same reason as `read-study-requirement`: its terminal state bypasses this gate's approval).
-- All Gaps Confirmed → present a short Gate 1 summary, wait for DEV to run `aiflow task next` before continuing to Step 5.
+- All Gaps Confirmed (including Step 3.5's) → present a short Gate 1 summary, wait for DEV to run `aiflow task next` before continuing to Step 5.
 
 ---
 
@@ -140,10 +167,11 @@ Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N
 ## Executive Summary
 - **Purpose:** [1 sentence — what this document covers and why it exists]
 - **Implementation status:** [e.g. Not started / In progress / Matches UC Spec v{N}]
+- **Traceability coverage (from Step 3.5 audit):** [X]/[Y] UC Spec items have a matching System Requirement item · [Z] unsupported item(s) removed
 - **Key deviations from UC Spec:** [bullet list of Deviation-tagged items, or "None identified"]
-- **Action needed from BA:** [bullet list of unresolved Gaps/Assumptions needing BA input, or "None — ready for Dev handoff"]
+- **Action needed from PM:** [bullet list of unresolved Gaps/Assumptions needing PM input, or "None — ready for Dev handoff"]
 
-> This section alone should give PM/BA the full picture in about 30 seconds — everything below is supporting detail for BA/Tester/Dev.
+> This section alone should give PM the full picture in about 30 seconds — everything below is supporting detail for BA/Tester/Dev.
 
 ---
 
@@ -156,7 +184,7 @@ Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N
 
 ## 1. Functional Requirements
 
-Each item below is layered: **Requirement** (business language, for PM/BA) → **System Behavior** (for BA/Tester) → **Implementation Reference** (for Dev, technical detail only — never appears in the layers above it).
+Each item below is layered: **Requirement** (business language, for PM) → **System Behavior** (for BA/Tester) → **Implementation Reference** (for Dev, technical detail only — never appears in the layers above it).
 
 ### FR-01: [short business-behavior title]
 - **Requirement:** [system behavior in business language, no framework/class/method names]
@@ -223,11 +251,11 @@ Summary only — deeper implementation detail belongs in each item's **Implement
 | Test | ... |
 
 ### 6.2 Glossary / Term Mapping
-Every `Tech Reference:` used in Sections 1–4 gets one row here — a single place to look up what a business term maps to in code, instead of hunting through every item. Only include terms with a BA-confirmed business meaning (Decision) or the BA-unconfirmed raw value tagged accordingly — never a guessed meaning.
+Every `Tech Reference:` used in Sections 1–4 gets one row here — a single place to look up what a business term maps to in code, instead of hunting through every item. Only include terms with a PM-confirmed business meaning (Decision) or the PM-unconfirmed raw value tagged accordingly — never a guessed meaning.
 
 | Business Term | Technical Reference | Classification |
 |---|---|---|
-| [e.g. "default status PENDING"] | `TagStatusEnum::PENDING` | Decision (BA-confirmed [date]) / Assumption (unconfirmed) |
+| [e.g. "default status PENDING"] | `TagStatusEnum::PENDING` | Decision (PM-confirmed [date]) / Assumption (unconfirmed) |
 
 ### 6.3 External System Interfaces *(optional — include only if this UC integrates with a system outside the app's own UI/DB, e.g. third-party API, webhook, message queue)*
 The UC Spec describes UI/business flow, not external integration contracts — capture those here when they exist. Omit this subsection entirely if the UC has no external interface.
@@ -271,6 +299,11 @@ Coverage:
   Validation Rules:        [N]   Exception Handling: [N]
   Open Gaps:                [N]  ← must be 0 to approve
 
+Traceability Audit (Step 3.5):
+  UC Spec items matched 1-1:   [X]/[Y]
+  Unsupported items removed:   [Z]
+  ⚠️  [N] unresolved gap(s) from this audit — see Section 7   (omit this line if 0)
+
 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
@@ -299,8 +332,9 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 
 | Concern | Handled by |
 |---|---|
-| Source code investigation methodology | `read-study-requirement` Step 1 pattern (reused inline) / GitNexus MCP |
+| Source code investigation methodology | `read-study-requirement` Step 1 pattern (reused inline) / GitNexus MCP / `Explore` sub-agents (Step 2 cost-control) |
 | Gap/Assumption/Decision/Deviation classification | This skill (inline, Step 3 — output-only convention, distinct from `read-study-requirement` Step 1.75's Fact/Assumption/Gap) |
+| 1-1 traceability audit (UC ↔ System Requirement) | This skill (inline, Step 3.5 — separate from Step 3's while-drafting tracing) |
 | Q&A loop (one question at a time, no fabrication) | This skill (inline) |
 | UC Spec structure/content | `skill-ba-uc-template-v1.md` (read-only reference, never edited by this skill) |
 | Split decision | This skill (Step 5) |
@@ -312,10 +346,12 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 ## Mandatory Rules
 
 - ❌ **DO NOT** create System Requirement content that isn't traced to the UC Spec or a DEV-confirmed answer — no invented Functional Requirements, error messages, or NFR numbers.
-- ❌ **DO NOT** proceed to Step 5 while any Gap is unresolved.
+- ❌ **DO NOT** proceed to Step 5 while any Gap is unresolved — this includes Step 3.5's traceability-audit Gaps, not just Step 3/Step 4's.
+- ✅ **MUST** run Step 3.5's 1-1 traceability audit (both directions — UC→SR coverage and SR→UC grounding) before Q&A closes; report its counts in the Step 7 Gate 2 prompt so DEV/PM see explicit match numbers, not just a claim of completeness.
+- ❌ **DO NOT** re-investigate a file from scratch for every Business Rule that touches it (Step 2) — investigate per module/concern once, keep an Investigation Notes table, and prefer GitNexus MCP or `Explore` sub-agent delegation over serial multi-file reads in the main session.
 - ❌ **DO NOT** split into multiple files unless a Step 5 threshold is actually met — default is one file.
 - ❌ **DO NOT** split to paper over a UC Spec that bundles multiple independent use cases — escalate to BA instead.
-- ❌ **DO NOT** run this skill if the UC Spec isn't BA-signed-off yet — this skill never substitutes for missing UC Spec content.
+- ❌ **DO NOT** run this skill if the UC Spec isn't PM-signed-off yet — this skill never substitutes for missing UC Spec content.
 - ❌ **DO NOT** bump `System-Requirement-Version` independently of the UC Spec version.
 - ✅ **MUST** read the full UC Spec (Step 1) before drafting anything.
 - ✅ **MUST** investigate source code (Step 2) before drafting Exception/Error Handling or Existing System Context.
@@ -325,6 +361,6 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 - ✅ **MUST** keep the HTTP status code in every `Error Response` line, paired with a friendly label and the user-facing message (e.g. `HTTP 422 (Validation Error) — "..."`) — never drop the code for readability.
 - ✅ **MUST** tag each Acceptance Test with its `Requirement Coverage` (the FR/VR/ER IDs it exercises).
 - ❌ **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 BA has confirmed it — reference the raw technical value in `Implementation Reference` and tag it `Assumption` or `Gap` until confirmed.
+- ❌ **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** 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.

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

@@ -0,0 +1,128 @@
+# 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ó.
+
+---
+
+# 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
+
+---
+
+## 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"]
+
+
+---
+
+## 0. Ma trận truy vết (Traceability Matrix)
+| 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 |
+
+## 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).
+
+### 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]
+
+<!-- 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)
+
+### 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]
+
+## 3. Quy Tắc Nghiệp Vụ → Quy Tắc Kiểm Tra Hợp Lệ (Business Rules → Validation Rules)
+
+### 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`]
+
+## 4. Xử Lý Ngoại Lệ & Lỗi (Exception & Error Handling)
+
+### 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ó]
+
+## 5. Kịch Bản Kiểm Thử Chấp Nhận (Acceptance Test Scenarios)
+### AT-01: [Tên kịch bản] (Main Flow)
+- **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
+
+## 6. Bối Cảnh Hệ Thống Hiện Có (Existing System Context)
+
+### 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.
+
+| Khu vực (Area) | Tóm tắt (Summary) |
+|---|---|
+| 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) |
+
+### 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.
+
+| 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.
+
+| 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.]
+
+## 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} | |

package/custom/skills/impact-analysis/SKILL.md

@@ -1,106 +1,106 @@
----
-name: impact-analysis
-description: Analyze the impact scope when modifying logic or the database to ensure system-wide safety.
-keywords: impact, refactor, breaking change, scope
----
-
-# Impact Analysis
-
-## When mandatory to run
-
-- Modifying **Core Services / shared utilities** used in many places
-- Changing **database schema** (add/rename/drop column, table)
-- Changing **API response structure** (rename field, remove field)
-- Changing **interfaces / contracts** between modules
-- After fixing a bug — to ensure the fix doesn't break other parts
-
----
-
-## Analysis Process
-
-### Step 1: Find all usage (Dependency Map)
-
-**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
-```
-impact("ClassName")    → structured blast radius: callers, dependents, risk score
-detect_changes()       → reads current git diff, maps changed lines → affected symbols
-```
-- Use `impact()` when you know the class/function name being modified.
-- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
-- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
-
-**Fallback — grep manually** (if GitNexus not configured):
-```bash
-# Find all files importing/calling the class/function being modified
-grep -r "ClassName\|functionName\|methodName" --include="*.php" .
-grep -r "ClassName\|functionName\|methodName" --include="*.java" .
-grep -r "ClassName\|functionName\|methodName" --include="*.ts" .
-
-# Check which routes/controllers trigger this service
-grep -r "ServiceName" app/Http/Controllers/
-```
-
-List all:
-- Controllers / Routes calling it directly
-- Jobs / Commands / Events calling it indirectly
-- Tests mocking/stubbing this class
-- Frontend components calling related APIs
-
-### Step 2: Evaluate each aspect
-
-| Aspect | Checkpoint questions |
-|-----------|---------------------|
-| **Database / Cache** | Which queries are affected by schema changes? Which cache keys need flushing? |
-| **Background Jobs** | Which Crons / Queues call this logic? Will they break? |
-| **Import / Export** | Do bulk data flows use this field/logic? |
-| **Permissions** | Are API / UI permission checks sufficient after the change? |
-| **API / Mobile** | Will JSON responses lose fields? Do mobile clients need updates? |
-| **Tests** | Which tests will fail? Which mocks/stubs need updating? |
-
-### Step 3: Classify impact level
-
-| Level | Definition | Action |
-|-----|-----------|-----------|
-| 🟢 Low | Only 1 file, no dependencies | Proceed |
-| 🟡 Medium | 2–5 files, tests need updates | Review carefully before merging |
-| 🔴 High | 6+ files, API breaking change, DB migration | Discuss with the team first |
-| ⛔ Critical | Affects payment, auth, data integrity | Tech Lead review mandatory |
-
-### Step 4: Export report
-
-**Report structure:**
-
-```
-## Impact Analysis: [Change Name]
-
-**Level:** 🟡 Medium
-
-### Impact Scope
-- [File/Class A] — [reason for impact]
-- [File/Class B] — [reason for impact]
-
-### Breaking changes
-- [Describe breaking change if any]
-
-### Tests to check after merge
-- [ ] [Test case / screen 1]
-- [ ] [Test case / screen 2]
-- [ ] [Job/Command to test run]
-
-### Notes for QA
-[Specific points QA should pay attention to]
-```
-
-Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
-
----
-
-## Completion Checklist
-
-- [ ] Found all dependencies using grep/IDE search
-- [ ] Checked Jobs, Events, and Crons
-- [ ] Checked API response structure
-- [ ] Checked tests
-- [ ] Determined impact level (Low/Medium/High/Critical)
-- [ ] Wrote impact report
-- [ ] Notified the team if High/Critical
+---
+name: impact-analysis
+description: Analyze the impact scope when modifying logic or the database to ensure system-wide safety.
+keywords: impact, refactor, breaking change, scope
+---
+
+# Impact Analysis
+
+## When mandatory to run
+
+- Modifying **Core Services / shared utilities** used in many places
+- Changing **database schema** (add/rename/drop column, table)
+- Changing **API response structure** (rename field, remove field)
+- Changing **interfaces / contracts** between modules
+- After fixing a bug — to ensure the fix doesn't break other parts
+
+---
+
+## Analysis Process
+
+### Step 1: Find all usage (Dependency Map)
+
+**Preferred — If GitNexus MCP is available** (`.mcp.json` has `gitnexus` entry):
+```
+impact("ClassName")    → structured blast radius: callers, dependents, risk score
+detect_changes()       → reads current git diff, maps changed lines → affected symbols
+```
+- Use `impact()` when you know the class/function name being modified.
+- Use `detect_changes()` when starting Gate 4 review — it auto-detects what changed from git diff without needing to specify names.
+- One call replaces all grep commands below. Proceed directly to Step 2 with the result.
+
+**Fallback — grep manually** (if GitNexus not configured):
+```bash
+# Find all files importing/calling the class/function being modified
+grep -r "ClassName\|functionName\|methodName" --include="*.php" .
+grep -r "ClassName\|functionName\|methodName" --include="*.java" .
+grep -r "ClassName\|functionName\|methodName" --include="*.ts" .
+
+# Check which routes/controllers trigger this service
+grep -r "ServiceName" app/Http/Controllers/
+```
+
+List all:
+- Controllers / Routes calling it directly
+- Jobs / Commands / Events calling it indirectly
+- Tests mocking/stubbing this class
+- Frontend components calling related APIs
+
+### Step 2: Evaluate each aspect
+
+| Aspect | Checkpoint questions |
+|-----------|---------------------|
+| **Database / Cache** | Which queries are affected by schema changes? Which cache keys need flushing? |
+| **Background Jobs** | Which Crons / Queues call this logic? Will they break? |
+| **Import / Export** | Do bulk data flows use this field/logic? |
+| **Permissions** | Are API / UI permission checks sufficient after the change? |
+| **API / Mobile** | Will JSON responses lose fields? Do mobile clients need updates? |
+| **Tests** | Which tests will fail? Which mocks/stubs need updating? |
+
+### Step 3: Classify impact level
+
+| Level | Definition | Action |
+|-----|-----------|-----------|
+| 🟢 Low | Only 1 file, no dependencies | Proceed |
+| 🟡 Medium | 2–5 files, tests need updates | Review carefully before merging |
+| 🔴 High | 6+ files, API breaking change, DB migration | Discuss with the team first |
+| ⛔ Critical | Affects payment, auth, data integrity | Tech Lead review mandatory |
+
+### Step 4: Export report
+
+**Report structure:**
+
+```
+## Impact Analysis: [Change Name]
+
+**Level:** 🟡 Medium
+
+### Impact Scope
+- [File/Class A] — [reason for impact]
+- [File/Class B] — [reason for impact]
+
+### Breaking changes
+- [Describe breaking change if any]
+
+### Tests to check after merge
+- [ ] [Test case / screen 1]
+- [ ] [Test case / screen 2]
+- [ ] [Job/Command to test run]
+
+### Notes for QA
+[Specific points QA should pay attention to]
+```
+
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
+---
+
+## Completion Checklist
+
+- [ ] Found all dependencies using grep/IDE search
+- [ ] Checked Jobs, Events, and Crons
+- [ ] Checked API response structure
+- [ ] Checked tests
+- [ ] Determined impact level (Low/Medium/High/Critical)
+- [ ] Wrote impact report
+- [ ] Notified the team if High/Critical