@relipa/ai-flow-kit 0.2.0-beta.1 → 0.2.0

package/bin/aiflow.js

@@ -212,7 +212,8 @@ program
 Examples:
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10"
   $ ak fetch-links "https://company.backlog.com/view/PROJ-10#comment-456"
-  $ ak fetch-links "https://company.backlog.com/document/98765"          Backlog Document (ingest-data)
+  $ ak fetch-links "https://company.backlog.com/document/0193b335c62173de9547bab5dd0b5324"          Backlog Document (ingest-data)
+  $ ak fetch-links "https://company.backlog.com/document/PROJ/e/0193b335c62173de9547bab5dd0b5324"   Backlog Document share link (newer format)
   $ ak fetch-links "https://company.backlog.com/alias/wiki/1234"         Backlog Wiki (ingest-data)
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10"
   $ ak fetch-links "https://company.atlassian.net/browse/PROJ-10?focusedCommentId=789"
@@ -584,13 +585,14 @@ function checkAndInstallAiflowGlobal() {
 // ── gate (telemetry for gate workflow events) ─────────────────
 program
     .command('gate <number> <action>')
-    .description('Log a gate workflow event (start|approved) — called by AI during gate workflow')
+    .description('Log a gate workflow event (start|approved|skip) — called by AI during gate workflow')
     .option('--ticket <id>', 'ticket ID')
     .option('--ai-tool <tool>', 'AI tool name')
+    .option('--reason <text>', 'why this gate was skipped (only used with action=skip)')
     .action((number, action, options) => {
         const gateNum = parseInt(number);
         if (isNaN(gateNum) || gateNum < 1 || gateNum > 5) return;
-        if (!['start', 'approved'].includes(action)) return;
+        if (!['start', 'approved', 'skip'].includes(action)) return;
 
         if (action === 'start') {
             console.log(chalk.cyan(`\n  [aiflow] Gate ${gateNum} environment check:`));
@@ -610,7 +612,7 @@ program
 
         // Keep task-state.json currentGate in sync (silent — never blocks the AI)
         if (ticketId) {
-            updateTaskGateState(ticketId, gateNum, action).catch(() => {});
+            updateTaskGateState(ticketId, gateNum, action, { reason: options.reason }).catch(() => {});
         }
 
         if (action === 'approved') {
@@ -618,6 +620,8 @@ program
             console.log(chalk.yellow(`  Pro-Tip: To avoid context pollution, it's recommended to start a fresh chat session.`));
             console.log(chalk.gray(`  Run: aiflow task next${ticketId ? ` --ticket ${ticketId}` : ''} to save progress,`));
             console.log(chalk.gray(`  then open a NEW chatbox and type "continue".\n`));
+        } else if (action === 'skip') {
+            console.log(chalk.cyan(`\n  Gate ${gateNum} skipped${options.reason ? `: ${options.reason}` : ''}`));
         }
     });
 

package/custom/skills/ba-skills/skill-ba-initial-analysis-template-v1.md

@@ -22,9 +22,11 @@ Mẫu tài liệu này được sử dụng để trình bày kết quả phân
 
 ## 5. Bảng Phân Tích Khoảng Trống & Giả Định (Gap & Assumption Analysis)
 
-| # | Tính năng/Luồng nghiệp vụ | Hiện trạng mô tả thô | Khoảng trống (Gap) / Sự mơ hồ phát hiện | Giả định của BA (Assumption) | Đề xuất giải pháp / Q&A ID tương ứng |
-| :-: | :--- | :--- | :--- | :--- | :--- |
-| 1 | *Ví dụ: Nhập Password* | *Mật khẩu được che giấu* | *Có nút show/hide mật khẩu hay không? Đăng nhập sai bao nhiêu lần thì khóa?* | *Mặc định không hiển thị nút show/hide. Cho phép nhập sai tối đa 5 lần.* | *Xem Q&A_01* |
-| 2 | | | | | |
+*Chỉ liệt kê các Gap còn **Open** (chưa Confirmed) — Gap đã Confirmed được tích hợp thẳng vào mục 1-4 phía trên, không giữ lại ở bảng này. Cột Mức độ ảnh hưởng: 🔴 Blocking (chặn gate tiếp theo) / 🟡 Non-blocking (được phép defer, có marker `[PENDING - QA-ID]`).*
 
-*Lưu ý: Bảng này là cơ sở quan trọng nhất để tạo ra danh sách câu hỏi Q&A chuẩn xác cho khách hàng.*
+| # | Tính năng/Luồng nghiệp vụ | Hiện trạng mô tả thô | Khoảng trống (Gap) / Sự mơ hồ phát hiện | Giả định của BA (Assumption) | Mức độ ảnh hưởng | Đề xuất giải pháp / Q&A ID tương ứng |
+| :-: | :--- | :--- | :--- | :--- | :-: | :--- |
+| 1 | *Ví dụ: Nhập Password* | *Mật khẩu được che giấu* | *Có nút show/hide mật khẩu hay không? Đăng nhập sai bao nhiêu lần thì khóa?* | *Chưa có giả định — cần khách hàng xác nhận số lần khóa vì ảnh hưởng luồng chính* | 🔴 Blocking | *Xem [PENDING - QA-01]* |
+| 2 | *Ví dụ: Thông báo lỗi* | *Không nêu rõ text lỗi* | *Text thông báo lỗi cụ thể là gì?* | *Tạm dùng text mặc định, có thể đổi sau* | 🟡 Non-blocking | *Xem [PENDING - QA-02]* |
+
+*Lưu ý: Bảng này là cơ sở quan trọng nhất để tạo ra danh sách câu hỏi Q&A chuẩn xác cho khách hàng. Số dòng phải phản ánh đúng số Gap thực tế tìm được — không rút gọn cho "gọn tài liệu" nếu vẫn còn Gap chưa được hỏi.*

package/custom/skills/ba-skills/skill-ba-initial-analysis-v1.md

@@ -32,14 +32,19 @@ Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem
     - Nếu để trống thì hệ thống xử lý thế nào? Có thông báo lỗi gì không?
     - Có quy tắc nghiệp vụ (Business rules) ngầm định nào không?
     - Luồng thay thế (Alternative flows) hoặc luồng lỗi (Exception flows) là gì?
+
+  Số lượng Gap tìm được phải tăng theo độ phức tạp thực tế của yêu cầu — KHÔNG dừng lại khi "cảm thấy đủ" hoặc đã đạt một số lượng quen thuộc (ví dụ 5-6 điểm) nếu còn trường/luồng/actor chưa được đối chiếu hết qua 4 câu hỏi trên. Với yêu cầu nhiều màn hình/nhiều actor/tích hợp hệ thống khác, quét từng màn hình/actor riêng biệt rồi tổng hợp, không gộp tắt.
+  Với mỗi Gap, gắn nhãn mức độ ảnh hưởng ngay: 🔴 **Blocking** (ảnh hưởng cấu trúc dữ liệu, luồng chính, phân quyền/bảo mật, hoặc quyết định khó đảo ngược) hoặc 🟡 **Non-blocking** (chi tiết UI/text, giá trị mặc định có thể đổi sau, luồng hiếm gặp).
 - **Bước 4: Soạn dự thảo Kết quả phân tích ban đầu:**
-  Áp dụng template phân tích ban đầu (`skill-ba-initial-analysis-template-v1.md`) để điền thông tin và lập bảng Gap/Assumption.
+  Áp dụng template phân tích ban đầu (`skill-ba-initial-analysis-template-v1.md`) để điền thông tin và lập bảng Gap/Assumption, kèm cột Mức độ ảnh hưởng cho mỗi Gap.
 
 ## 4. Checklist kiểm tra (Checklist for Verification)
 - [ ] Đã xác định rõ Mục tiêu hệ thống/chức năng chưa? (Hệ thống giải quyết bài toán gì?)
 - [ ] Đã làm rõ tất cả các Tác nhân (Actors) tham gia chưa?
 - [ ] Đã bóc tách hết các trường thông tin (Inputs) được liệt kê trong tài liệu thô chưa?
 - [ ] Đã ghi nhận rõ ràng danh sách các điểm mơ hồ hoặc thiếu thông tin dưới dạng **Gap/Assumption** chưa?
+- [ ] Số lượng Gap tìm được có phản ánh đúng độ phức tạp thực tế (nhiều màn hình/actor/luồng → nhiều Gap hơn), không bị gò về một số cố định không?
+- [ ] Mỗi Gap đã có nhãn Mức độ ảnh hưởng (🔴 Blocking / 🟡 Non-blocking) chưa?
 - [ ] Không tự tiện bổ sung các tính năng ngoài phạm vi yêu cầu của khách hàng khi chưa có thảo luận/Q&A.
 
 ## 5. Output mong đợi (Expected Output)

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

@@ -6,16 +6,17 @@ Mẫu tài liệu dùng để trình bày danh sách câu hỏi Q&A và theo dõ
 
 # Tài liệu Q&A: [Tên Chức Năng]
 
-*Tài liệu này dùng để theo dõi các vấn đề nghiệp vụ cần làm rõ giữa đội ngũ dự án và khách hàng. Trạng thái bao gồm: **Open** (Đang chờ phản hồi), **Confirmed** (Đã thống nhất).*
+*Tài liệu này dùng để theo dõi các vấn đề nghiệp vụ cần làm rõ giữa đội ngũ dự án và khách hàng. Trạng thái bao gồm: **Open** (Đang chờ phản hồi), **Confirmed** (Đã thống nhất). Mức độ ảnh hưởng: 🔴 **Blocking** (chưa trả lời thì không thể tiến gate tiếp theo), 🟡 **Non-blocking** (có thể defer, output sẽ giữ marker `[PENDING - QA-ID]` tại vị trí liên quan).*
 
 ## Danh sách câu hỏi Q&A
 
-| ID | Chức năng / Màn hình | Nội dung yêu cầu hiện tại | Câu hỏi / Điểm chưa rõ | Đề xuất giải pháp (Options) | Câu trả lời của Khách hàng | Trạng thái |
-| :-: | :--- | :--- | :--- | :--- | :--- | :-: |
-| **QA-01** | *Đăng nhập* | *Có text link đổi mật khẩu* | *Text link này sẽ dẫn sang URL cụ thể nào? Hệ thống tự sinh OTP gửi mail hay chuyển sang màn nhập email?* | *- Option A: Chuyển sang URL `/forgot-password` để nhập Email nhận link reset.<br>- Option B: Hiển thị popup nhập SĐT nhận OTP.* | *Khách hàng phản hồi: Chọn Option A, link URL là `/forgot-password`* | **Confirmed** |
-| **QA-02** | | | | | | **Open** |
+| ID | Chức năng / Màn hình | Nội dung yêu cầu hiện tại | Câu hỏi / Điểm chưa rõ | Đề xuất giải pháp (Options) | Mức độ ảnh hưởng | Câu trả lời của Khách hàng | Trạng thái |
+| :-: | :--- | :--- | :--- | :--- | :-: | :--- | :-: |
+| **QA-01** | *Đăng nhập* | *Có text link đổi mật khẩu* | *Text link này sẽ dẫn sang URL cụ thể nào? Hệ thống tự sinh OTP gửi mail hay chuyển sang màn nhập email?* | *- Option A: Chuyển sang URL `/forgot-password` để nhập Email nhận link reset.<br>- Option B: Hiển thị popup nhập SĐT nhận OTP.* | 🔴 Blocking | *Khách hàng phản hồi: Chọn Option A, link URL là `/forgot-password`* | **Confirmed** |
+| **QA-02** | *Đăng nhập* | *Thông báo lỗi khi sai mật khẩu* | *Câu chữ thông báo lỗi cụ thể là gì?* | *- Option A: "Email hoặc mật khẩu không đúng."<br>- Option B: Ý kiến khác...* | 🟡 Non-blocking | *Chưa trả lời — khách hàng cần hỏi lại team Marketing* | **Open** |
 
 ---
 ## Lịch sử cập nhật tài liệu
 *Sau mỗi lần nhận phản hồi, BA cập nhật bảng trên và ghi nhận lịch sử tại đây:*
 - **Ngày [dd/mm/yyyy]:** Nhận phản hồi lần 1 từ khách hàng cho câu hỏi QA-01. Cập nhật trạng thái sang **Confirmed** và chỉnh sửa tài liệu Phân tích bản đầu tương ứng.
+- **Ngày [dd/mm/yyyy]:** QA-02 (🟡 Non-blocking) vẫn **Open** — BA đã xác nhận tiếp tục sang gate kế tiếp, đánh dấu `[PENDING - QA-02]` trong Analysis tại mục thông báo lỗi đăng nhập.

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

@@ -14,15 +14,24 @@ Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem
 
 ## 3. Quy trình thực hiện (Step-by-step Process)
 - **Bước 1: Chuyển đổi Gap thành câu hỏi Q&A:**
-  Từ danh sách khoảng trống phát hiện ở bước Phân tích ban đầu, chuyển mỗi dòng thành một câu hỏi Q&A cụ thể.
-- **Bước 2: Chuẩn hóa câu hỏi theo mẫu `@skill-ba-qna-template-v1.md`:**
+  Từ danh sách khoảng trống phát hiện ở bước Phân tích ban đầu, chuyển mỗi dòng thành một câu hỏi Q&A cụ thể. Số lượng câu hỏi phải phản ánh đúng số Gap thực tế — không tự giới hạn theo một số cố định (ví dụ luôn dừng ở 5-6 câu) bất kể yêu cầu đơn giản hay phức tạp. Nếu phát sinh Gap mới trong lúc soạn câu hỏi (đọc kỹ hơn thấy còn điểm mơ hồ), bổ sung ngay câu hỏi mới, không bỏ qua để "gọn danh sách".
+- **Bước 2: Gắn nhãn mức độ ảnh hưởng (Blocking/Non-blocking):**
+  Trước khi chuẩn hóa câu hỏi, gắn nhãn:
+  - 🔴 **Blocking** — ảnh hưởng cấu trúc dữ liệu, luồng chính (happy path), phân quyền/bảo mật, hoặc quyết định kiến trúc khó đảo ngược sau khi code.
+  - 🟡 **Non-blocking** — chi tiết UI/text, giá trị mặc định có thể đổi sau, alternative/exception flow hiếm gặp.
+  Nhãn này quyết định câu hỏi có bắt buộc phải Confirmed trước khi qua gate tiếp theo hay được phép defer.
+- **Bước 3: Chuẩn hóa câu hỏi theo mẫu `@skill-ba-qna-template-v1.md`:**
   - Xác định phân vùng nghiệp vụ (Module/Screen).
   - Trích dẫn yêu cầu hiện tại (Current Status/Requirement).
   - Nêu rõ vấn đề mơ hồ.
   - Đưa ra các giải pháp đề xuất (Options) cùng giả định của BA.
-- **Bước 3: Nhận phản hồi và Cập nhật (Process Responses):**
-  - Khi nhận được câu trả lời từ khách hàng: Đọc kỹ để đảm bảo câu trả lời đã giải quyết triệt để câu hỏi. Nếu câu trả lời vẫn chưa rõ ràng, tiếp tục duy trì trạng thái "Open" và hỏi lại ở version tiếp theo.
-  - Nếu đã rõ ràng: Đánh dấu "Resolved" và 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 (`Kết quả phân tích(n).md`).
+  - Đ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.
+  - Đã 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.
+    - 🔴 Blocking → giữ **Open** nhưng cảnh báo rõ cho BA lý do đây là blocking và hệ quả nếu bỏ qua trước khi cho phép gate tiếp theo tiến hành; không tự hạ nhãn xuống Non-blocking để né cảnh báo.
   - Ghi nhận lịch sử thay đổi để Dev/Test nắm được lý do thay đổi logic.
 
 ## 4. Checklist kiểm tra (Checklist for Verification)
@@ -30,7 +39,10 @@ Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem
 - [ ] Câu hỏi có sử dụng từ ngữ trung lập, không mang tính áp đặt ý kiến chủ quan của BA không?
 - [ ] Có đưa ra các phương án gợi ý (Option A, Option B...) cho các vấn đề phức tạp để khách hàng dễ lựa chọn không?
 - [ ] Các thuật ngữ viết tắt trong câu hỏi có được giải thích rõ không?
+- [ ] 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 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)
 - File danh sách câu hỏi Q&A định dạng markdown, cấu trúc thống nhất dựa theo `@skill-ba-qna-template-v1.md`, đặt tên theo chuẩn: `QnA-Log_v(m).md` trong thư mục `02.BA-Specs/02.QnA/[functionId]/`.

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

@@ -59,7 +59,8 @@ Same methodology as `read-study-requirement` Step 1 (steps 4–5), reused here:
 - Find modules/files that implement or would implement this UC's Main Flow (existing feature being extended, or nearest analogous feature for a new one).
 - **If GitNexus MCP available:** `gitnexus: query()` / `gitnexus: context()` for the relevant area — same token-saving shortcut as `read-study-requirement`.
 - Identify **existing error-handling conventions** (error code format, message structure, exception class hierarchy) — the Exception & Error Handling section (Step 4 below) must reuse these, not invent a new convention.
-- Identify **existing data model / API surface** touched by this UC (tables, DTOs, endpoints) — feeds Section 6 of the output.
+- Identify **existing data model / API surface** touched by this UC (tables, DTOs, endpoints) — feeds Section 6.1 of the output.
+- Identify whether this UC integrates with any system **outside** the app's own UI/DB (third-party API, webhook, message queue, etc.) — the UC Spec won't describe this since it's UI/flow-focused; if found, feeds Section 6.3. If there's none, skip Section 6.3 entirely rather than leaving it as empty boilerplate.
 
 This step exists so System Requirement reflects what the system *can actually do today*, not just what the UC Spec says in the abstract.
 
@@ -73,18 +74,32 @@ For every row in the UC Spec's Main Flow, Alternative/Exception Flows, and Busin
 - **Non-Functional Requirements** — from BR3-type rules (security, authz) or explicit constraints in the UC Spec / ticket context; do not invent performance/scale numbers that aren't stated anywhere — mark as Gap and ask instead.
 - **Business Rules → Validation Rules** — translate each BR into a concrete system-level rule, cross-referenced with the existing pattern found in Step 2 (or flagged if no existing pattern applies).
 - **Exception & Error Handling** — one per Exception Flow, using the error-handling convention found in Step 2.
-- **Acceptance Test Scenarios** — Given/When/Then, at least one per Main Flow outcome + one per Alternative/Exception Flow. This is the concrete deliverable requested by proposal #1 (acceptance tests generated from the spec, not copied from the ticket).
+- **Acceptance Test Scenarios** — Given/When/Then, at least one per Main Flow outcome + one per Alternative/Exception Flow. This is the concrete deliverable requested by proposal #1 (acceptance tests generated from the spec, not copied from the ticket). Tag each scenario with the Requirement IDs it exercises (**Requirement Coverage**) so QA can trace AT → FR/VR/ER without re-reading the whole document.
 
 **`RESYNC` mode:** diff the new UC Spec version against the previous one section by section; carry forward unchanged items, mark changed/removed items, draft new items only for the delta. Never silently drop an item without noting why in the Change Log.
 
-Classify every item as **Fact** (explicit in UC Spec or confirmed in code) / **Assumption** (inferred, unconfirmed) / **Gap** (missing entirely) — same convention as `read-study-requirement` Step 1.75.
+#### 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:
+
+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.
+   - ❌ `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.
+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.
+
+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.
 
 ---
 
 ### 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 open item in Section 8 rather than guessing.
+- **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.
 - 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.
 
@@ -122,6 +137,16 @@ 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}]
+- **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"]
+
+> This section alone should give PM/BA the full picture in about 30 seconds — everything below is supporting detail for BA/Tester/Dev.
+
+---
+
 ## 0. Traceability Matrix
 | UC Reference (Flow / BR) | System Requirement Item(s) |
 |---|---|
@@ -130,49 +155,95 @@ Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N
 | BR1.1 | VR-01 |
 
 ## 1. Functional Requirements
-| ID | Requirement | Traced UC Ref | Type |
-|---|---|---|---|
-| FR-01 | ... | Main Flow #3 | Fact |
+
+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).
+
+### 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]
+
+<!-- repeat FR-02, FR-03, ... in the same block format -->
 
 ## 2. Non-Functional Requirements
-| ID | Requirement | Traced UC Ref | Type |
-|---|---|---|---|
-| NFR-01 | ... | BR3.1 | Fact |
+
+### NFR-01: [short title]
+- **Requirement:** [business language — e.g. performance/security expectation]
+- **System Behavior:** [how it's enforced, in plain language]
+- **Traced UC Ref:** BR3.1
+- **Classification:** [Gap | Assumption | Decision | Deviation — omit if plain fact]
+- **Implementation Reference:** [file:line / class / method]
 
 ## 3. Business Rules → Validation Rules
-| ID | System-level Rule | Traced UC BR | Existing Code Pattern |
-|---|---|---|---|
-| VR-01 | ... | BR1.1 | [file:line] |
+
+### VR-01: [short title]
+- **Requirement:** [e.g. "Tag name must be unique among active Tags."]
+- **System Behavior:** [e.g. "The system checks the Tag name against all active Tags before saving."]
+- **Error Response:** HTTP 422 (Validation Error) — "[user-facing message]"
+- **Traced UC BR:** BR1.1
+- **Classification:** [Gap | Assumption | Decision | Deviation — omit if plain fact]
+- **Implementation Reference:** [e.g. `Rule::unique(...)` in `StoreTagRequest`]
 
 ## 4. Exception & Error Handling
-| ID | Trigger Condition | System Behavior | Traced Exception Flow | Error Convention Used |
-|---|---|---|---|---|
-| ER-01 | ... | ... | Exception Flow B | [existing error code/class] |
+
+### ER-01: [trigger condition, in business language]
+- **Requirement:** [e.g. "Only users with CREATE permission can create Tags."]
+- **System Behavior:** [e.g. "The request is rejected because the caller lacks the required permission."]
+- **Error Response:** HTTP 403 (Forbidden) — "[user-facing message]"
+- **Traced Exception Flow:** Exception Flow B
+- **Classification:** [Gap | Assumption | Decision | Deviation — omit if plain fact]
+- **Implementation Reference:** [existing error code/class/middleware]
 
 ## 5. Acceptance Test Scenarios
 ### AT-01: [Scenario] (Main Flow)
 - **Given** ...
 - **When** ...
 - **Then** ...
+- **Requirement Coverage:** FR-01, FR-03
 
 ### AT-02: [Scenario] (Exception Flow B)
-...
+- **Given** ...
+- **When** ...
+- **Then** ...
+- **Requirement Coverage:** VR-01, ER-01
 
 ## 6. Existing System Context
-### Related Modules / Files
-| File | Role | Current Behavior |
-|---|---|---|
 
-### Data / API Impact
-| Entity / Endpoint | Change Type | Note |
+### 6.1 System Areas Summary
+Summary only — deeper implementation detail belongs in each item's **Implementation Reference** above, not here.
+
+| Area | Summary |
+|---|---|
+| API | ... |
+| Model | ... |
+| Validation | ... |
+| Migration | ... |
+| 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.
+
+| Business Term | Technical Reference | Classification |
 |---|---|---|
+| [e.g. "default status PENDING"] | `TagStatusEnum::PENDING` | Decision (BA-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.
+
+| Interface | Direction | Protocol/Format | Note |
+|---|---|---|---|
+| [e.g. Payment Gateway API] | Outbound | REST/JSON | ... |
+
+## 7. Assumptions / Gaps / Decisions / Deviations
+Only items tagged Gap / Assumption / Decision / Deviation land here — a plain fact is the default, unmarked state of every item above and is not repeated in this table.
 
-## 7. Facts / Assumptions / Gaps
 | Type | Item | Resolution |
 |---|---|---|
 
-## 8. Open Questions Log
-[Question asked → answer received → date. Unresolved Gaps stay listed here, never silently dropped.]
+## 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.)]
 
 ## 9. Change Log
 | Date | Ticket | Change | Note |
@@ -229,7 +300,7 @@ 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 |
-| Fact/Assumption/Gap classification | This skill (inline, same convention as `read-study-requirement` Step 1.75) |
+| 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) |
 | 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) |
@@ -250,3 +321,10 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 - ✅ **MUST** investigate source code (Step 2) before drafting Exception/Error Handling or Existing System Context.
 - ✅ **MUST** carry the mandatory `UC-Spec-Version` header on the master file.
 - ✅ **MUST** surface a ⚠️ non-blocking warning (never a cancel) from the Gate 1 Pre-flight check until this skill reaches APPROVED.
+- ✅ **MUST** write the `Requirement` and `System Behavior` layer of every FR/NFR/VR/ER item in business language — no framework, class, or method names (those belong only in `Implementation Reference`).
+- ✅ **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.
+- ✅ **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/ingest-data/SKILL.md

@@ -16,7 +16,7 @@ keywords: ingest data, comtor, brse, pm workflow, meeting minutes, qna log, conf
 | Input | Cách xử lý |
 |---|---|
 | Backlog ticket link (`/view/PROJ-N`) hoặc comment (`#comment-N`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
-| Backlog Document link (`/document/{id}` hoặc `/alias/document/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "document" \| "document-comment", ... }`. ⚠️ API Document của Nulab còn mới (2026) — nếu lệnh trả lỗi HTTP 404, báo lại cho người dùng, đây là dấu hiệu endpoint cần điều chỉnh, không phải lỗi ở phía bạn. |
+| Backlog Document link (`/document/{id}`, `/alias/document/{id}`, hoặc share link mới `/document/{PROJECT_KEY}/e/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "document" \| "document-comment", ... }`. Đã xác nhận hoạt động live (2026-08-06) cho document body (`title`/`content`). ⚠️ Fetch comment trên Document (`document-comment`) vẫn chưa xác minh trên space thật — nếu lệnh trả lỗi HTTP 404 hoặc `content` rỗng, báo lại cho người dùng, đây là dấu hiệu endpoint/field cần điều chỉnh, không phải lỗi ở phía bạn. |
 | Backlog Wiki link (`/alias/wiki/{id}`) | `ak fetch-links "<url>"` → JSON `{ sourceType: "wiki", ... }` |
 | Jira ticket/comment link | `ak fetch-links "<url>"` → JSON `{ sourceType: "ticket" \| "comment", ... }` |
 | SharePoint link (`*.sharepoint.com`) | `ak fetch-links "<url>"` → `{ sourceType: "unsupported", reason: "sharepoint-not-configured" }`. **Không có connector** (cần Microsoft Graph API + OAuth, xem PM Workflow doc "Vấn đề 4" — chưa làm POC). Hiển thị `message` trong JSON cho người dùng, và đề nghị: "Paste trực tiếp nội dung comment/tài liệu vào chat, mình sẽ dùng luôn." |
@@ -130,20 +130,44 @@ Nếu người dùng yêu cầu sửa (thêm/bớt ý, đổi log đích, sửa
 
 **Không phải mọi entry đều sinh ra task.** Trước khi đề xuất bất kỳ task nào, tự hỏi: nội dung này có yêu cầu một hành động cụ thể (thay đổi spec, code, test, tài liệu...) hay chỉ là thông tin tham khảo/FYI (cập nhật tiến độ, thông tin không đổi hành vi hệ thống, trả lời một câu hỏi đã đóng)?
 
-- **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi dừng, không hỏi thêm, không chạy `ak gate 3 start`.
+- **Chỉ là tham khảo** → hiển thị: `ℹ️ Nội dung này không phát sinh task — chỉ lưu làm tài liệu tham khảo. Gate 3 kết thúc.` rồi chạy `ak gate 3 skip --ticket [ticket-id] --reason "<1 câu lý do>"` (không cần `ak gate 3 start` trước) và dừng, không hỏi thêm. Việc này đóng gate đúng cách — dashboard (ai-flow-ex) hiển thị "⏭ Gate 3 skipped — \<lý do\>" thay vì để task treo mãi ở trạng thái "sẵn sàng chạy Gate 3".
 - **Có hành động cụ thể** → tiếp tục Bước 3. Khi không chắc (ví dụ nội dung vừa có FYI vừa có 1 ý cần sửa code) — nghiêng về đề xuất task cho phần cần hành động, bỏ qua phần FYI, không tự bịa task cho phần không rõ.
 
+**Riêng khi nguồn là `Confirmations-Log`** (khách hàng CHỐT chính thức 1 thay đổi requirement) — đây là trường hợp dễ đề xuất thiếu task nhất nếu chỉ dựa vào Action items viết sẵn trong nội dung (vd chỉ thấy 1 bug fix được nêu tên, bỏ sót toàn bộ phần spec/testcase phát sinh từ chính rule vừa chốt). Trước khi sang Bước 3, tự chạy qua đủ checklist tối thiểu sau — không hiển thị checklist này cho PM, chỉ dùng để tự rà soát không bỏ sót:
+
+1. **UC Spec** — functionId này đã có UC Spec chưa, và rule vừa chốt đã phản ánh trong Spec chưa? Chưa → task `spec`.
+2. **System Requirement** — chỉ cần nếu có task `coding` theo sau (Gate 1 coding sẽ tự chặn nếu System Requirement thiếu/lệch version, xem `CLAUDE.md` pre-check) → task `system-requirement`.
+3. **Impact analysis** — thay đổi có đủ phức tạp/rủi ro (ảnh hưởng nhiều module/feature khác, hoặc PM cần thấy effort/scope trước khi giao việc) để cần 1 tài liệu đánh giá riêng, tách khỏi Gate 1 coding không? Cần → task `impact-analysis`.
+4. **Coding** — có thay đổi hành vi hệ thống cần code không? Cần → task `coding` (tách thành nhiều task nhỏ nếu phạm vi lớn, mỗi task 1 title riêng).
+5. **Data migration/backfill** — rule mới có áp dụng hồi tố lên dữ liệu đã tồn tại không (khác với chỉ áp dụng từ nay về sau)? Có → thêm 1 task `coding` **riêng** cho việc migration/backfill, không gộp chung với task coding chính (2 rủi ro/effort khác nhau, cần review riêng).
+6. **Create/Update testcase** — cần → task `test`.
+7. **Execute test** — cần → task `execute-test`.
+
+Không phải mục nào cũng luôn có (case rule chỉ áp dụng tương lai thì mục 5 = không cần) — nhưng phải đi qua đủ 7 mục và có lý do trước khi kết luận không cần, không bỏ qua mục nào chỉ vì nội dung entry không viết thành Action item rõ ràng.
+
 ### 5.3 Bước 3 — Đề xuất danh sách task
 
 Mỗi task gồm:
 
 | Trường | Ghi chú |
 |---|---|
-| `type` | `spec` (tạo/update UC Spec) · `coding` · `test` · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
+| `type` | `spec` (tạo/update UC Spec) · `system-requirement` (tạo/update System Requirement) · `impact-analysis` (đánh giá phạm vi ảnh hưởng, tách riêng khỏi Gate 1 coding) · `coding` (bao gồm cả migration/backfill, tách task riêng nếu cần) · `test` (tạo/update testcase) · `execute-test` (thực thi testcase có sẵn) · `other` (update tài liệu không thuộc BA/QA/Dev, vd Rules) |
 | `title` | Ngắn, hành động rõ (vd "Cập nhật flow OTP theo feedback khách — tăng thời hạn 30s → 90s") |
-| `track` | BA / Dev / QA — để PM biết ai sẽ nhận task này |
+| `track` | BA / Dev / QA / Analyst — để PM biết ai sẽ nhận task này |
 | `description` | Theo đúng template mục 6.1 `PM Workflow_v1.0.md`: |
 
+Mỗi `type` map thẳng vào 1 task type có sẵn khi người nhận chạy `ak use TICKET-XXX` (không cần Gate workflow mới — xem `scripts/use.js` cho danh sách đầy đủ):
+
+| `type` task | Task type chọn ở `ak use` |
+|---|---|
+| `spec` | 📋 Create Spec |
+| `system-requirement` | 📐 Create System Requirement |
+| `impact-analysis` | 📊 Impact Analysis |
+| `coding` | 🐛 Bug Fix / ✨ Feature / 🔄 Refactor (tuỳ nội dung task) |
+| `test` | ✅ Create TestCase |
+| `execute-test` | ▶️ Execute Test |
+| `other` | Không map task type nào — tuỳ nội dung, người nhận tự xử lý ngoài Gate workflow |
+
 ```text
 ## Nội dung task
 [Mô tả task do AI đề xuất]
@@ -190,37 +214,61 @@ Check LOCAL trước, chỉ hỏi khi thật sự chưa biết (Vấn đề 5.1)
 2. Đã có → dùng luôn, hiển thị rõ cho PM biết đang dùng project nào + nguồn (đã lưu từ lần trước).
 3. Chưa có → hiển thị danh sách project vừa fetch được, PM chọn 1 → lưu lại bằng `ak backlog-set-default-project <id> <key>` hoặc `ak jira-set-default-project <key>` — để lần sau không hỏi lại.
 
+### 5.6b Bước 6b — Ticket cha (chỉ hỏi khi danh sách có ≥ 2 task)
+
+Nếu danh sách chỉ có 1 task, không có gì để gộp — coi `parentTicket.mode = "none"` và bỏ qua bước này.
+
+Nếu ≥ 2 task, hỏi đúng 1 câu:
+
+```text
+Gộp N task này dưới 1 ticket cha?
+1. Tạo mới ticket cha
+2. Dùng ticket cha có sẵn — cho biết ticket ID
+3. Không cần ticket cha
+```
+
+- **(1)** → hỏi PM 1 tiêu đề ngắn cho ticket cha (gợi ý: dùng lại "Tổng quan nội dung thay đổi" đã soạn cho task `spec` ở Bước 3, nếu có; không có thì tự tóm tắt 1 câu). `parentTicket = { "mode": "create", "title": "...", "description": "..." }`.
+- **(2)** → PM nhập ticket ID có sẵn. `parentTicket = { "mode": "existing", "existingId": "<ID do PM nhập>" }`. Việc xác minh ticket đó có tồn tại thật diễn ra ở Bước 7 (khi gọi `ak tasks create-tickets`) — không tự coi là đúng trước khi có kết quả lệnh.
+- **(3)** → `parentTicket = { "mode": "none" }`.
+
+⚠️ **Chưa xác minh trên instance thật:** liên kết cha-con cần Backlog project đã bật tính năng phân cấp issue (Subtasking), hoặc Jira project hỗ trợ field `parent` trực tiếp (rõ nhất với project dạng team-managed; company-managed có thể cần issue type `Subtask` riêng — chưa test). Nếu Bước 7 báo lỗi `parent-create-failed`/`parent-not-found`, hoặc 1 task con lỗi do gán parent thất bại — hiển thị nguyên lỗi cho PM, hỏi PM muốn: thử lại với ticket cha khác, tiếp tục tạo các ticket con không gắn parent (`mode: "none"`), hay dừng lại để PM xử lý cấu hình Backlog/Jira trước.
+
 ### 5.7 Bước 7 — Tạo ticket
 
 1. Ghi danh sách task đã duyệt ra 1 file JSON tạm (vd `.aiflow/tmp/tasks-[ticketId].json`), đúng shape mà `ak tasks create-tickets` đọc (xem `scripts/ticket-writer.js`):
    ```json
    {
      "target": "backlog",
+     "parentTicket": { "mode": "create", "title": "...", "description": "..." },
      "tasks": [
        { "type": "coding", "title": "...", "description": "..." }
      ]
    }
    ```
+   `parentTicket` lấy nguyên từ kết quả Bước 6b (bỏ field này hoặc `{"mode": "none"}` nếu không gộp ticket cha).
 2. Chạy `ak tasks create-tickets <file> --json`.
 3. Đọc kết quả JSON trả về:
    - `{"error":"missing-write-credentials", "field": "...", "message": "..."}` → **đây không phải lỗi hệ thống** — hiển thị đúng `message` cho PM, hỏi PM nhập giá trị key ngay trong hội thoại (dùng luôn khung chat làm nơi PM "nhập & submit"), nhận giá trị → chạy `ak credentials set <field> "<giá trị PM vừa nhập>"` → chạy lại bước 2 (retry đúng 1 lần; nếu vẫn lỗi, báo PM key có thể sai/chưa đủ quyền, không tự thử lại vô hạn).
    - `{"error":"missing-project", ...}` → quay lại Bước 6 (chưa xác định được project).
-   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng; task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
+   - `{"error":"parent-not-found", "message": "..."}` → ticket cha PM cung cấp ở Bước 6b (2) không tồn tại/không đọc được — báo PM, quay lại Bước 6b để nhập ID khác hoặc chọn phương án khác.
+   - `{"error":"parent-create-failed", "message": "..."}` → tạo ticket cha thất bại (thường do project chưa hỗ trợ phân cấp issue) — hiển thị nguyên lỗi, hỏi PM có muốn tạo lại không gắn ticket cha (`mode: "none"`) hay dừng lại.
+   - Thành công (`ok: true`) → mỗi task có `ticketId` + `url` riêng, có thêm `parent` (ticket cha vừa tạo/dùng, nếu có); task nào `ok: false` (lỗi phía Backlog/Jira, vd thiếu field) → báo rõ cho PM, các task khác đã tạo vẫn giữ nguyên (không rollback).
 
 ### 5.8 Bước 8 — Ghi ngược liên kết + đóng Gate
 
-1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng:
+1. Append vào cuối đúng entry gốc (Meetings-Log/QnA-Log/Confirmations-Log) 1 dòng, kèm ticket cha nếu có:
    ```text
-   → Tasks created: TICKET-101 (coding), TICKET-102 (test)
+   → Tasks created: TICKET-100 (parent), TICKET-101 (coding), TICKET-102 (test)
    ```
    Việc sửa file này đi qua đúng branch đang dùng ở Gate 2 (không tạo MR riêng — gộp vào cùng thay đổi, hoặc nếu MR đã mở/merge thì tạo 1 commit nhỏ tiếp theo trên cùng branch/1 MR mới tuỳ trạng thái branch lúc đó).
 2. Hiển thị tổng kết:
    ```text
    ✅ GATE 3 DONE — Đã tạo N/N ticket trên [Backlog/Jira]:
+     - Ticket cha: TICKET-100 — <url>  (bỏ dòng này nếu không gộp ticket cha)
      - TICKET-101 (coding) — <url>
      - TICKET-102 (test) — <url>
    → Dev/QA chạy `ak use TICKET-XXX` trên từng ticket để bắt đầu Gate tương ứng (Coding/QA workflow hiện có).
    ```
 3. Run: `ak gate 3 approved --ticket [ticket-id]`.
 
-> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` khi bắt đầu Bước 1 (bỏ qua nếu Bước 2 kết luận không cần task — không start gate cho trường hợp "chỉ tham khảo"). Run `ak gate 3 approved --ticket [ticket-id]` khi Bước 8 xong.
+> **Telemetry:** Run `ak gate 3 start --ticket [ticket-id]` khi bắt đầu Bước 1 (bỏ qua nếu Bước 2 kết luận không cần task — không start gate cho trường hợp "chỉ tham khảo"). Run `ak gate 3 approved --ticket [ticket-id]` khi Bước 8 xong, HOẶC `ak gate 3 skip --ticket [ticket-id] --reason "..."` khi Bước 2 kết luận không cần task (thay cho việc không đóng gate — xem Bước 2).