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

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,15 +16,14 @@ 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:
 - 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.
 
 ---
 
@@ -36,7 +35,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 +63,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]
@@ -80,28 +90,52 @@ 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/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.
+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]
+
+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.
 
 ---
 
@@ -133,17 +167,35 @@ 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).
 
 ---
 
 ## 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,14 +208,14 @@ 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]
 - **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 -->
 
@@ -223,11 +275,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.
@@ -243,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 |
@@ -271,10 +329,19 @@ 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
   → 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).
@@ -283,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.
 
 ---
 
@@ -299,8 +366,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 +380,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 +395,10 @@ 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** 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

@@ -0,0 +1,282 @@
+# Template Yêu Cầu Hệ Thống (System Requirement) — Phiên bản v1
+
+Đâ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
+
+---
+
+## 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)
+
+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                            |
+
+---
+
+## 1. Yêu Cầu Chức Năng (Functional Requirements)
+
+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 — 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]
+
+---
+
+## 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`]
+
+---
+
+## 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ó]
+
+---
+
+## 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
+
+### 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)
+
+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 các khu vực có liên quan.
+
+| 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 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:
+
+* 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.
+
+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ỉ 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)
+
+Đâ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} |                |