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

package/bin/aiflow.js

@@ -22,6 +22,7 @@ const { record }      = require('../scripts/telemetry/record');
 const { updateTaskGateState } = require('../scripts/task');
 const scaffoldPlaywrightCommand = require('../scripts/scaffold-playwright');
 const docsBranchCommand = require('../scripts/docs-branch');
+const ticketWriterCommand = require('../scripts/ticket-writer');
 const semver = require('semver');
 const { execSync: execSyncChild, spawnSync } = require('child_process');
 
@@ -211,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"
@@ -238,6 +240,61 @@ Exit codes:
         }
     });
 
+// ── backlog-projects ─────────────────────────────────────────
+program
+    .command('backlog-projects')
+    .description('List Backlog projects in the configured space, and which one is the default for manually-created tasks')
+    .option('--json', 'output as JSON (for headless callers, e.g. the VS Code extension)')
+    .action((options) => {
+        useCommand.listBacklogProjectsCommand(options);
+    });
+
+// ── backlog-set-default-project ──────────────────────────────
+program
+    .command('backlog-set-default-project <id> <key>')
+    .description('Set the default Backlog project for tasks created manually (ak use --manual)')
+    .action((id, key) => {
+        useCommand.setDefaultBacklogProjectCommand(id, key);
+    });
+
+// ── jira-projects ─────────────────────────────────────────────
+program
+    .command('jira-projects')
+    .description('List Jira projects visible to the configured account, and the default for task-creation')
+    .option('--json', 'output as JSON (for headless callers, e.g. the VS Code extension)')
+    .action((options) => {
+        useCommand.listJiraProjectsCommand(options);
+    });
+
+// ── jira-set-default-project ─────────────────────────────────
+program
+    .command('jira-set-default-project <key>')
+    .description('Set the default Jira project for tasks created from Meeting Minutes/QnA (ingest-data Gate 3)')
+    .action((key) => {
+        useCommand.setDefaultJiraProjectCommand(key);
+    });
+
+// ── tasks (Vấn đề 5 — sinh task từ feedback/meeting minutes) ──
+const tasksCmd = program.command('tasks').description('Turn an AI-proposed, PM-approved task list into real tickets (ingest-data Gate 3)');
+
+tasksCmd
+    .command('create-tickets <file>')
+    .description('Create Backlog/Jira tickets from a JSON task list — see scripts/ticket-writer.js for the input shape')
+    .option('--json', 'machine-readable output only')
+    .action((file, options) => {
+        ticketWriterCommand.createTicketsCommand(file, options);
+    });
+
+// ── credentials ───────────────────────────────────────────────
+const credentialsCmd = program.command('credentials').description('Manage supplementary credentials (WRITE keys, default projects) not covered by `ak init --adapter`');
+
+credentialsCmd
+    .command('set <key> <value>')
+    .description(`Save a credential value (allowed keys: ${ticketWriterCommand.SETTABLE_CREDENTIAL_KEYS.join(', ')})`)
+    .action((key, value) => {
+        ticketWriterCommand.setCredentialCommand(key, value);
+    });
+
 // ── prompt ────────────────────────────────────────────────────
 program
     .command('prompt [type]')
@@ -528,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:`));
@@ -554,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') {
@@ -562,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/rules/output-language.md

@@ -0,0 +1,36 @@
+# Ngôn ngữ Output — Auto-detect theo Input
+
+> File này là quy tắc dùng chung cho **tất cả** các skill trong `custom/skills/` (BA, Dev, QA, ML) có sinh file markdown output (requirement, plan, test-analysis, checklist, testcase, report, review, UC Spec, v.v.).
+> Mọi skill sinh markdown output PHẢI đọc file này trước khi viết, thay cho việc mặc định cố định tiếng Anh hoặc tiếng Việt.
+
+## Quy tắc
+
+Ngôn ngữ của output PHẢI khớp với ngôn ngữ của input — không dùng một ngôn ngữ mặc định cố định cho mọi task.
+
+**Xác định ngôn ngữ input theo thứ tự ưu tiên** (dùng nguồn đầu tiên có sẵn):
+
+1. Tester/dev chỉ định rõ ngôn ngữ output (ví dụ: "viết bằng tiếng Anh giúp tôi") → dùng đúng ngôn ngữ đó, bỏ qua các bước dưới.
+2. Title + description của ticket đang xử lý — từ `.aiflow/context/current.json` (fetch qua Backlog/Jira, hoặc nhập qua `ak use --manual`).
+3. Nếu skill đang mở rộng/tiếp nối một tài liệu đã có sẵn (UC Spec, System Requirement, plan, testcase set của gate trước) và không có ticket text mới — dùng ngôn ngữ của tài liệu đó.
+
+**Kết luận:**
+- Input chủ yếu là **tiếng Việt** (có dấu, từ vựng tiếng Việt) → viết **toàn bộ** output bằng tiếng Việt: heading, mô tả, tóm tắt, câu hỏi clarify, nội dung bảng, v.v.
+- Ngược lại (tiếng Anh hoặc ngôn ngữ khác) → **mặc định tiếng Anh**.
+
+Nếu một task có nhiều gate (Gate 1 → Gate N) hoặc nhiều phase, ngôn ngữ được xác định **một lần** ở bước đầu tiên (đọc ticket/input) và giữ nguyên xuyên suốt các gate/phase sau, trừ khi tester/dev đổi ý.
+
+## Không đổi ngôn ngữ (giữ nguyên bất kể input)
+
+- Code, command, file path, tên biến/hàm/class/API.
+- Table column headers / field keys mang tính cấu trúc, dùng để tham chiếu chéo giữa các gate (ví dụ `TC_ID`, `Priority`, `Status`, `Gate N`) — theo quy ước hiện có ở `custom/skills/test-skills/rules/qa-writing-standards.md`.
+- Từ khóa điều khiển flow: `APPROVED`, `RETEST`, tên skill, tên file/thư mục chuẩn (`test-analysis.md`, `checklist.md`, ...).
+- Ticket ID, YAML frontmatter keys.
+
+## Cách trích dẫn quy tắc này trong một SKILL.md
+
+Thêm 1 dòng ngắn ngay gần bước xác định output đầu tiên của skill:
+
+```
+Output language: auto-detect từ ticket/task input — xem `custom/rules/output-language.md`
+(input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+```

package/custom/skills/automation-testing/SKILL.md

@@ -235,5 +235,5 @@ Xem report:
 
 - **Gate trước khi sinh code** (Phase 2) là bắt buộc — tránh sinh sai hàng loạt.
 - **Selector phải đến từ DOM thật** (Phase 3) — đây là lý do tồn tại của skill này.
-- Viết test case, tên test, comment bằng **tiếng Việt** cho khớp draft của tester.
+- Tên test, comment viết theo ngôn ngữ của draft test case của tester (xem `custom/rules/output-language.md`) — draft tiếng Việt → tiếng Việt, draft tiếng Anh → tiếng Anh.
 - Nếu app yêu cầu đăng nhập trước, hỏi tester credentials test (đừng hardcode tài khoản thật).

package/custom/skills/ba-skills/skill-ba-build-business-rules-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA bóc tách, chuẩn hóa và đặc tả các quy tắc nghiệp vụ (Business Rules - BR) của hệ thống một cách chặt chẽ nhất. Các quy tắc nghiệp vụ được định nghĩa chi tiết tại đây sẽ là căn cứ trực tiếp để lập trình viên viết code logic (backend/frontend) và kiểm thử viên viết các kịch bản kiểm thử (Test Cases), đảm bảo bao phủ toàn bộ các trường hợp biên và ngoại lệ.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Các loại Business Rules phổ biến:**
   - *Validation Rules (Quy tắc kiểm tra dữ liệu):* Bao gồm kiểm tra rỗng (Required), kiểm tra định dạng (Format - Regex, Email, số điện thoại), kiểm tra độ dài/giới hạn (Length/Range), và kiểm tra ràng buộc chéo giữa các trường (Dependency validation - ví dụ: Ngày kết thúc phải sau Ngày bắt đầu).

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

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và cấu trúc hóa các yêu cầu thô được cung cấp bởi khách hàng hoặc các stakeholders. Mục tiêu là phân tách rõ ràng giữa các thông tin thực tế (Facts) và các giả định (Assumptions), phát hiện các khoảng trống nghiệp vụ (Gaps), và tạo cơ sở cho việc lập danh sách câu hỏi làm rõ (Q&A) cũng như dự thảo spec ban đầu.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Tư duy phân tích (Analytical Thinking):** Khả năng chia nhỏ một yêu cầu lớn thành các luồng nghiệp vụ nhỏ và các thành phần cấu thành.
 - **Phân biệt Fact vs. Assumption:**
@@ -30,14 +32,19 @@ Kỹ năng này giúp Business Analyst (hoặc Agent) quét, đọc hiểu và c
     - 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-mermaid-flowchart-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA chuyển đổi các đặc tả luồng nghiệp vụ văn bản (Main flow, Alternative flows, Exception flows) thành một sơ đồ hoạt động trực quan (Activity Diagram) sử dụng mã nguồn Mermaid. Sơ đồ này giúp lập trình viên nắm bắt luồng đi tổng thể của hệ thống một cách tức thì và giúp kiểm thử viên xác minh các nhánh rẽ của kịch bản.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Cấu trúc biểu đồ Flowchart trong Mermaid:**
   - Khai báo hướng biểu đồ: Dùng `graph TD` (Top-Down - từ trên xuống) hoặc `graph LR` (Left-to-Right - từ trái sang phải). Đối với quy trình nghiệp vụ phần mềm, khuyến nghị dùng `graph TD`.

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

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và chuyên nghiệp để gửi tới khách hàng/stakeholders nhằm làm rõ các khoảng trống nghiệp vụ (Gaps). Đồng thời, hướng dẫn cách tiếp nhận câu trả lời để cập nhật tài liệu phân tích một cách nhất quán, tránh hiểu sai hoặc tự ý giả định thông tin.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Kỹ năng giao tiếp bằng văn bản (Written Communication):** Sử dụng câu từ ngắn gọn, lịch sự, đi thẳng vào vấn đề.
 - **Kỹ thuật đặt câu hỏi mở và đóng:**
@@ -12,15 +14,24 @@ Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và
 
 ## 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)
@@ -28,7 +39,10 @@ Kỹ năng này giúp BA thiết kế các câu hỏi rõ ràng, khách quan và
 - [ ] 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/ba-skills/skill-ba-ui-prototype-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này hướng dẫn BA thiết kế và hiện thực hóa giao diện người dùng (UI mockup/prototype) dưới dạng mã nguồn HTML/CSS tự chứa (self-contained). Prototype giúp khách hàng hình dung trực quan luồng đi của màn hình, đồng thời giúp lập trình viên và kiểm thử viên xác định chính xác cấu trúc trang, ID của các phần tử và vị trí hiển thị lỗi.
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **HTML5 Semantic Tags:** Sử dụng các thẻ ngữ nghĩa như `<header>`, `<main>`, `<section>`, `<nav>`, `<form>`, `<input>`, `<button>`, `<label>` để trang web có cấu trúc chuẩn SEO và dễ kiểm thử.
 - **Vanilla CSS Layouts:** Thành thạo Flexbox và CSS Grid để dựng bố cục nhanh chóng, đáp ứng tốt trên các kích thước màn hình khác nhau (Responsive).

package/custom/skills/ba-skills/skill-ba-write-uc-spec-v1.md

@@ -3,6 +3,8 @@
 ## 1. Mục đích (Purpose)
 Kỹ năng này giúp BA chuyển hóa toàn bộ các thông tin yêu cầu nghiệp vụ đã được thống nhất sau quá trình Q&A thành một tài liệu Đặc tả Use Case (Use Case Spec) hoàn chỉnh. Tài liệu này là "nguồn sự thật duy nhất" (Single Source of Truth) giúp đội ngũ Dev lập trình chính xác và đội ngũ Test thiết kế toàn bộ kịch bản kiểm thử (Test Cases/Scripts).
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/task input — xem `custom/rules/output-language.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh).
+
 ## 2. Kiến thức cần có (Prerequisite Knowledge)
 - **Cấu trúc Use Case chuẩn:** Hiểu rõ các thành phần của một Use Case Spec bao gồm: Thông tin chung, Mô tả màn hình, Mô tả thành phần UI, Luồng hoạt động (Activity Flow) và Quy tắc nghiệp vụ (Business Rules).
 - **Cách mô tả Luồng xử lý (Flow):** 

package/custom/skills/coverage-check/SKILL.md

@@ -93,6 +93,8 @@ Consolidate toàn bộ TCs (sau khi apply actions) vào **1 file duy nhất**:
 
 Lưu `test-plan/test-cases/final-testcases.md`:
 
+Ngôn ngữ output: auto-detect theo ngôn ngữ của ticket/testcase input — xem `custom/rules/output-language.md` và `custom/skills/test-skills/rules/qa-writing-standards.md` (input tiếng Việt → output tiếng Việt; ngược lại mặc định tiếng Anh; tiêu đề cột bảng vẫn giữ tiếng Anh).
+
 ```markdown
 # Final Test Cases — [Feature Name]
 

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

@@ -1,6 +1,6 @@
 ---
 name: create-system-requirement
-description: Bridges UC Spec (BA, Gate 4) to Dev — investigates source code and translates the UC into System Requirement (Functional/Non-Functional Requirements, Business Rules → Validation Rules, Exception/Error Handling, Acceptance Tests). Runs once per functionId per UC Spec version, BEFORE the first coding ticket. Blocks Gate 1 (`read-study-requirement`) if missing or out of sync with the current UC Spec version.
+description: Bridges UC Spec (BA, Gate 4) to Dev — investigates source code and translates the UC into System Requirement (Functional/Non-Functional Requirements, Business Rules → Validation Rules, Exception/Error Handling, Acceptance Tests). Runs once per functionId per UC Spec version, ideally BEFORE the first coding ticket. Gate 1 (`read-study-requirement`) warns (non-blocking) if this is missing or out of sync with the current UC Spec version — this skill is how DEV closes that gap.
 keywords: system requirement, uc spec, functionId, trace, acceptance test, exception handling, business rule, matching, version sync
 ---
 
@@ -21,9 +21,10 @@ keywords: system requirement, uc spec, functionId, trace, acceptance test, excep
 
 **Hand-off from coding Gate 1 Pre-flight** (`read-study-requirement`, Step 0) when:
 - No `System-Requirement_v*.md` exists yet for this `functionId`, **or**
-- The existing one's `UC-Spec-Version` header does not match the UC Spec's current version.
+- 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`.
 
-Either condition → **the coding Gate 1 session is cancelled.** Tell DEV: start a new task with `ak use`, pick **"📐 Create System Requirement"** at the Task type prompt, run it through both gates to APPROVED, then resume the original ticket.
+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.
 
 ---
 
@@ -58,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.
 
@@ -72,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.
 
@@ -121,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) |
 |---|---|
@@ -129,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 |
@@ -179,6 +251,8 @@ Save to `AK-Docs/02.BA-Specs/00.Requirements/[functionId]/System-Requirement_v{N
 | [YYYY-MM-DD] | — | Initial creation from UC Spec v{N} | |
 ```
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ---
 
 ### Step 7: Present for Approval [Gate 2]
@@ -198,11 +272,12 @@ Coverage:
   Open Gaps:                [N]  ← must be 0 to approve
 
 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 unlock
-    coding Gate 1 for tickets on this functionId
+  → 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
 
-⚠️  Coding Gate 1 for this functionId stays cancelled until this task is APPROVED.
+⚠️  Until this task is APPROVED, coding Gate 1 for this functionId will keep
+    showing a non-blocking warning (it does not cancel).
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
@@ -225,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) |
@@ -245,4 +320,11 @@ This does not bump `System-Requirement-Version` — the version stays tied to th
 - ✅ **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.
 - ✅ **MUST** carry the mandatory `UC-Spec-Version` header on the master file.
-- ✅ **MUST** block/cancel Gate 1 until this skill reaches APPROVED, when triggered by the Gate 1 Pre-flight check.
+- ✅ **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/deploy-model/SKILL.md

@@ -73,6 +73,8 @@ Update the model card drafted at Gate 4 with:
 
 The model card is the primary audit document for the deployed model.
 
+Output language: auto-detect from the ticket/task input — see `custom/rules/output-language.md` (Vietnamese input → Vietnamese output; otherwise English).
+
 ### 6. Create the PR
 
 Invoke `superpowers:requesting-code-review`. Open a PR that includes: serving code, model card, monitoring plan, and any pipeline changes. Link the ticket. Reference the eval report and the registered artifact version in the PR description.