ai-developer-skill-os 9.1.1 → 9.3.0

package/.agents/skills/qk-product-specification/SKILL.md

@@ -1,9 +1,9 @@
----
+---
 # ── Identity ───────────────────────────────────────────────
 name: qk-product-specification
-version: 9.1.0
+version: 9.2.0
 status: experimental
-description: "Product thinking (Idea → Requirement → Acceptance criteria → Technical spec)."
+description: "Product thinking (Idea → Requirement → Acceptance criteria → Technical spec). Dùng skill này khi user nhắc đến: viết spec, phân tích yêu cầu, acceptance criteria, prd, đặc tả kỹ thuật, user story, làm rõ yêu cầu — kể cả khi chỉ nói 'tôi có ý tưởng làm tính năng X'."
 platforms: [antigravity, claude-code, cursor, windsurf, kilo-code]
 
 # ── V9: Classification ─────────────────────────────────────
@@ -23,11 +23,15 @@ complexity:
     has_external_dependency: false
     has_breaking_change: false
 
-triggers:
-  - "viết spec"
-  - "phân tích yêu cầu"
-  - "ý tưởng sản phẩm"
-  - "acceptance criteria"
+triggers:
+  - "viết spec"
+  - "phân tích yêu cầu"
+  - "acceptance criteria"
+  - "prd"
+  - "đặc tả kỹ thuật"
+  - "user story"
+  - "làm rõ yêu cầu"
+
 
 # ── V8: References ─────────────────────────────────────────
 workflow: spec-driven-development
@@ -71,28 +75,6 @@ verification:
   required: true
   strategy: feature
 
-lifecycle:
-  promotion_gate:
-    requirements:
-      tests:
-        minimum_pass_rate: 0.95
-      usage:
-        minimum_runs: 20
-      conflicts:
-        zero_boundary_violation: true
-      evidence:
-        required:
-          - evaluation_report
-          - usage_history
-          - boundary_audit
-  demotion_gate:
-    triggers:
-      - repeated_failure
-      - boundary_violation
-      - outdated_reference
-    action:
-      change_status: "stable -> experimental"
-
 selection:
   priority: medium
   confidence_threshold: 0.80
@@ -115,402 +97,91 @@ token_budget:
   max_shell_commands: 0
   stop_early: true
 
-exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
+exit_codes: [SUCCESS, BLOCKED, FAILED, PARTIAL]
 ---
 
-# qk-product-specification — Product Specifier
+# qk-product-specification — Product & Technical Specifier
 
 > **Language rule:** Code, identifiers, file names → English. Explanations, summaries → Vietnamese.
 
-## Memory Workflow
-
-### 0. Self-Init Protocol (Khởi Tạo Bộ Nhớ Local & Gitignore)
-- Trước khi tra cứu hoặc lưu trữ tri thức, BẮT BUỘC kiểm tra sự tồn tại của thư mục `.ai-local/` tại gốc dự án:
-  - **Tự động tạo mới:** Nếu `.ai-local/` chưa tồn tại, AI phải tự động tạo cấu trúc thư mục `.ai-local/knowledge/` (và file `index.yaml` nếu cần thiết) cùng `.ai-local/candidates/`. Tuyệt đối không ngưng chạy hay hỏi ý kiến người dùng về thao tác khởi tạo tiêu chuẩn này.
-  - **Bảo mật Gitignore:** BẮT BUỘC kiểm tra file `.gitignore` của dự án, nếu chưa có dòng `.ai-local/` thì phải tự động thêm vào để tuyệt đối bảo mật tri thức cá nhân và tránh lộ lọt lên Git.
-
----
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Pattern (vd: định dạng Acceptance Criteria, cấu trúc PRD).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Thỏa thuận Product Spec hoặc cấu trúc requirement mới.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .ai-local/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Ghi chú thảo luận ý tưởng thô ban đầu.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
-
-
-
-### Pre-flight Retrieve (Trước khi thực thi)
-- Trước các task có tính lặp lại, debug, refactor, kiến trúc hoặc rủi ro cao:
-  bắt buộc tra cứu:
-  - `.agents/knowledge/index.yaml` (Shared Project Knowledge)
-  - `.ai-local/knowledge/index.yaml` (Private Local Knowledge)
-
-- Ưu tiên sử dụng các Knowledge đang có trạng thái `Active` thuộc:
-  - Architecture
-  - Hard Bug
-  - Convention
-  - Pattern
-  - Tech Debt Pattern
-  - 👉 *Domain Focus:* Convention / Pattern (vd: định dạng Acceptance Criteria, cấu trúc PRD).
-
-- Memory chỉ đóng vai trò **Navigator (bản đồ chỉ đường)**.
-  Không được xem Memory là Source of Truth.
-  Luôn xác minh lại bằng source code, configuration và trạng thái hiện tại của dự án trước khi áp dụng.
-
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Thỏa thuận Product Spec hoặc cấu trúc requirement mới.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Ghi chú thảo luận ý tưởng thô ban đầu.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Thỏa thuận Product Spec hoặc cấu trúc requirement mới.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Ghi chú thảo luận ý tưởng thô ban đầu.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
-
-### Learning Flow (AI tự học có kiểm soát)
-- Trong quá trình làm việc, AI được phép tự phát hiện và tạo **Candidate Memory** khi nhận thấy:
-  - Hard Bug có khả năng tái diễn.
-  - Pattern làm việc lặp lại trong dự án.
-  - Convention hoặc quy tắc kiến trúc mới.
-  - Quyết định Architecture quan trọng.
-  - Tech Debt Pattern hoặc Code Smell có tính hệ thống.
-  - 👉 *Domain Harvest:* Thỏa thuận Product Spec hoặc cấu trúc requirement mới.
-
-- Candidate Memory chỉ là bản nháp quan sát, chưa phải tri thức chính thức.
-- Candidate Memory có thể lưu tạm tại: `.ai-local/candidates/`
-- AI không được tự động Promote Candidate Memory thành Project Knowledge.
-
----
-
-### Post-flight Harvest (Đề xuất → Phê duyệt)
-Sau khi hoàn thành task:
-- AI đánh giá các Candidate Memory đã tạo.
-- Nếu phát hiện tri thức có giá trị tái sử dụng:
-  - Đề xuất người dùng xem xét.
-  - Gửi yêu cầu phê duyệt thông qua:
-    - `/learn`
-    - `qk-project-memory`
-- Chỉ sau khi được phê duyệt, Candidate Memory mới được chuyển thành Knowledge chính thức:
-
-```
-.ai-local/candidates/  ──(Approve)──>  .agents/knowledge/index.yaml
-```
-
-- Project Knowledge phải được xem như tài sản kỹ thuật của dự án:
-  - Có thể review, cập nhật, loại bỏ và có lịch sử thay đổi.
-
----
-
-### Ignore (Không đưa vào Memory)
-Không lưu:
-- Trace log của một session đơn lẻ.
-- Temporary debugging data.
-- Output của một lần chạy test/scan.
-- Report health tạm thời của một đợt kiểm tra.
-- Lỗi nhỏ chỉ xảy ra một lần.
-- Thông tin không có khả năng tái sử dụng.
-- 👉 *Domain Ignore:* Ghi chú thảo luận ý tưởng thô ban đầu.
-
----
-
-### Golden Rule
-> **AI được phép học, nhưng không được tự quyết định tri thức chính thức.**
-> **AI quan sát → Đề xuất → Con người phê duyệt → Dự án tiến hóa.**
-
----
----
----
----
-
+Chịu trách nhiệm chuyển hóa các ý tưởng kinh doanh còn mơ hồ thành bản đặc tả kỹ thuật chi tiết (Technical Specification & PRD) hoàn chỉnh: **User Problem → User Stories → Acceptance Criteria (Given-When-Then) → Technical Constraints & Edge Cases**.
+
+---
+
 ## Preconditions
-- [ ] Tuân thủ workflow `spec-driven-development`.
 
-## Scope
-- Tiếp nhận Idea ban đầu từ user, thực hiện phân tích yêu cầu (Requirement Analysis).
-- Xác định và làm rõ ranh giới của tính năng.
-- Lên danh sách Acceptance Criteria (Tiêu chí nghiệm thu). **BẮT BUỘC có Security Acceptance Criteria để phòng ngừa rủi ro theo R-SEC-04 (Zero-Trust).**
-- Đóng gói thành Technical Spec (đặc tả kỹ thuật) để chuẩn bị cho quá trình code (Plan & Implementation).
+Trước khi viết đặc tả kỹ thuật, AI BẮT BUỘC kiểm tra:
 
-## Non-Goals
-- ❌ Provide implementation outside of Product Thinking & Requirements scope
-- ❌ Override explicit user directives without explanation
-- ❌ Guess ambiguous requirements without asking
+- [ ] Xác định đối tượng người dùng cuối (User persona) và bài toán kinh doanh cần giải quyết.
+- [ ] Đọc `.agents/DEV_PROFILE.md` để hiểu kiến trúc tổng quan và các ràng buộc công nghệ sẵn có.
+- [ ] Kiểm tra xem ý tưởng có mục tiêu đầu ra (Success metric / KPI) cụ thể chưa.
+- [ ] Nếu ý tưởng hoàn toàn không có mục đích sử dụng rõ ràng:
+  → **EXIT: BLOCKED**
+  → Báo cáo user câu hỏi định hình mục tiêu trước khi lập tài liệu spec.
 
-## Priority Order
+---
 
-| Priority | Task | Skip Threshold |
-|----------|------|----------------|
-| P1 | Core Product Thinking & Requirements analysis and decision making | Never |
-| P2 | Validation of existing patterns | Budget < 30% |
-| P3 | Detailed documentation generation | Budget < 50% |
-| P4 | Edge case exploration | Budget < 70% |
+## Scope
 
-## Workflow
+✅ Skill này làm:
+- Viết User Stories theo chuẩn: "As a [role], I want to [action], so that [benefit]".
+- Thiết lập Acceptance Criteria (AC) theo định dạng BDD Given/When/Then.
+- Liệt kê Edge Cases, Empty States, Error States, Permission constraints.
+- Phác thảo Data Model sơ bộ và các API endpoints cần có để phục vụ kỹ sư triển khai.
+- Chế độ hoạt động: **Read-Only / Documentation Output** (không can thiệp vào code).
 
-### Phase 1 — Context Loading
-**Steps:**
-1. Read existing configuration and requirements related to Product Thinking & Requirements.
-2. Check for missing preconditions.
+❌ Skill này KHÔNG làm:
+- Trực tiếp triển khai mã nguồn (→ chuyển giao cho `qk-feature-delivery`).
+- Nghiên cứu thị trường sâu, định giá sản phẩm (Pricing) hay marketing strategy.
+- Thiết kế UI Mockup chi tiết (→ `qk-ui-builder`).
 
-**Decision:**
-```
-IF context is clear
-  → Confidence: HIGH → go to Phase 2
-ELSE
-  → EXIT: BLOCKED — ask user
-```
+---
 
-### Phase 2 — Analysis & Strategy
-**Steps:**
-1. Analyze the current state against Product Thinking & Requirements best practices.
-2. Formulate strategy or audit report based on findings.
+## Execution Steps
 
-**Decision:**
+### Step 1 — Problem Framing & Persona Identification
 ```
-IF strategy/audit is complete
-  → Confidence: HIGH → go to Phase 3
-ELSE IF minor gaps exist
-  → Confidence: MEDIUM → proceed with assumptions noted
+Inputs:  Ý tưởng thô từ user
+Actions:
+  - Xác định ai là người hưởng lợi trực tiếp từ tính năng.
+  - Phân tách bài toán cốt lõi (Core problem) khỏi các mong muốn phụ (Nice-to-haves).
+Output: Problem statement & User personas
 ```
 
-### Phase 3 — Finalization
-**Steps:**
-1. Generate final report or configuration.
-2. Prepare handoff data for subsequent skills.
-
-## Confidence Model
-
-| Level | Condition | Action |
-|-------|-----------|--------|
-| HIGH | All preconditions met, context fully understood | Proceed directly |
-| MEDIUM | Some context missing but safe defaults exist | Proceed and note assumptions |
-| LOW | Core requirements missing | EXIT: BLOCKED |
-
-## Severity (for findings)
-
-| Level | Definition |
-|-------|-----------|
-| CRITICAL | Severe violation of Product Thinking & Requirements principles |
-| HIGH | Significant risk or technical debt |
-| MEDIUM | Suboptimal pattern but functional |
-| LOW | Minor style or documentation issue |
-
-## Evidence Format
-
+### Step 2 — Story Mapping & Scope Boundary
 ```
-[SEVERITY] Context/File
-Issue:      [what was found]
-Confidence: HIGH
-Recommendation: [actionable advice]
+Inputs:  Problem statement
+Actions:
+  - Chia nhỏ tính năng thành các User Stories độc lập, có thể bàn giao trong từng sprint.
+  - Phân loại rõ ràng: In-Scope (Làm ngay) vs Out-of-Scope (Giai đoạn sau).
+Output: User stories & Scope fence
 ```
 
-## Retry Policy
+### Step 3 — Acceptance Criteria & Edge Cases Definition
 ```
-Task fails due to missing context
-  └─ Ask user for clarification
-       ├─ Provided → Retry Phase 1
-       └─ Not provided → EXIT: BLOCKED
+Inputs:  User stories
+Actions:
+  - Viết Acceptance Criteria rõ ràng cho từng story (Given/When/Then).
+  - Định nghĩa các trường hợp biên: Dữ liệu quá lớn, mất mạng, token hết hạn, quyền truy cập bị từ chối.
+Output: Verification criteria
 ```
 
-## Escalation Rules
-
+### Step 4 — Technical Blueprint Hand-off
 ```
-BLOCKED: Missing critical context for Product Thinking & Requirements
-Missing:
-  - [Specific requirement]
-Questions:
-  1. Bạn có thể cung cấp thêm thông tin về yêu cầu này không?
-  2. Mục tiêu chính của bạn là gì?
-Recommended Assumptions: none
+Inputs:  Stories, AC, DEV_PROFILE.md
+Actions:
+  - Phác thảo kiến trúc kỹ thuật dự kiến: Entity fields, API route patterns.
+  - Tổng hợp thành file markdown đặc tả (Spec Markdown Document) sẵn sàng chuyển giao cho kỹ sư.
+Exit: SUCCESS
 ```
 
-## Handoff Contract
+---
 
-### Consumes
-```json
-{
-  "from": "user or qk-orchestrator",
-  "required_fields": ["context"],
-  "optional_fields": ["existing_config"]
-}
-```
+## Prompt Template
 
-### Produces
-```json
-{
-  "to": "user or downstream skill",
-  "output_fields": ["strategy_report", "exit_code"]
-}
 ```
-
-## Exit Codes
-
-| Code | Meaning | When |
-|------|---------|------|
-| SUCCESS | Product Thinking & Requirements task completed successfully | Strategy/audit generated |
-| PARTIAL | Task completed with assumptions | Medium confidence |
-| BLOCKED | Missing context | Cannot proceed |
-| FAILED | Critical conflict or error | Unresolvable constraint |
+Ý tưởng:     [Mô tả tính năng hoặc ý tưởng của bạn]
+Đối tượng:   [Ai sẽ dùng tính năng này — admin / user thông thường / khách vãng lai]
+Mục đích:    [Giải quyết vấn đề gì, mang lại giá trị gì]
+Ràng buộc:   [Thời hạn, không được đụng vào phần nào của hệ thống]
+```