@longph2102/v-flow 1.5.0

package/skills/specify/bugfix-analyst/SKILL.md

@@ -0,0 +1,296 @@
+---
+name: bugfix-analyst
+description: "Hướng dẫn Bugfix Analyst Agent phân tích bug theo 3-behavior model (Current/Expected/Unchanged), tìm root cause, và thiết kế 3-tier test plan. Agent PHẢI đọc skill này khi /v.bugfix được gọi."
+trigger: "Khi /v.bugfix được gọi"
+phase: "S.1"
+used_by:
+  - /v.bugfix
+hooks:
+  pre_analysis: "Scan codebase → trace execution path → xác định root cause hypothesis"
+  post_analysis: "Verify 3-behavior model đầy đủ, 3-tier test plan có mapping matrix"
+---
+
+# Bugfix Analyst — Phân Tích Bug Có Cấu Trúc
+
+> ⚠️ Đây là **Skill bắt buộc** cho Bugfix Analyst Agent.
+> QUAN TRỌNG: Phải document đủ **3 loại behavior**. Thiếu "Unchanged Behavior" → regression risk cao.
+>
+> → Xem `gotchas.md` cho lỗi phổ biến khi phân tích bug.
+> → Xem `examples/good/` cho mẫu bugfix.md chuẩn.
+> → Xem `examples/bad/` cho anti-patterns cần tránh.
+> → Xem `config.json` để customize (min_unchanged, confidence_threshold).
+
+---
+
+## Khi nào KHÔNG cần skill này
+
+- Bug đơn giản, rõ ràng, ≤ 5 files → dùng `/v.quickfix` (không cần formal analysis)
+- Production incident P1/P2 → dùng `/v.hotfix` (speed > structure)
+- Feature mới → dùng `/v.specify` (không phải bugfix)
+
+---
+
+## 3-Behavior Model — Core Concept
+
+> 💡 Đây là concept QUAN TRỌNG NHẤT. Mọi bugfix analysis đều xoay quanh 3 loại behavior.
+> Agent tự quyết depth dựa trên severity và complexity của bug.
+
+### Tại sao cần 3 behaviors?
+
+Hầu hết regression khi fix bug xảy ra vì developer:
+1. ❌ Chỉ focus vào "cái gì sai" → fix xong break cái khác
+2. ❌ Không document "cái gì ĐÚNG phải giữ nguyên" → không ai biết regression xảy ra
+
+3-Behavior Model buộc agent phải suy nghĩ **cả 3 chiều**:
+
+```
+🔴 Current Behavior (BUG-B)    — Cái gì ĐANG SAI?
+🟢 Expected Behavior (BUG-E)   — Cái gì PHẢI ĐÚNG sau fix?
+🛡️ Unchanged Behavior (BUG-U)  — Cái gì KHÔNG ĐƯỢC THAY ĐỔI?
+```
+
+### EARS Notation cho Bugfix
+
+Áp dụng EARS notation (cross-ref `ears-writer` skill) với từ khóa bugfix-specific:
+
+| Behavior Type | EARS Template | Prefix |
+|---------------|---------------|--------|
+| **Current (Defect)** | `Khi [điều kiện], hệ thống [hành vi sai hiện tại]` | BUG-B |
+| **Expected (Correct)** | `Khi [điều kiện], hệ thống phải [hành vi đúng]` | BUG-E |
+| **Unchanged (Protect)** | `Khi [điều kiện], hệ thống phải TIẾP TỤC [hành vi giữ nguyên]` | BUG-U |
+
+---
+
+## Đặc Thù Và Quy Ước
+
+> 💡 Phần này chứa thông tin Agent thường bỏ sót hoặc làm sai.
+
+### 1. BUG-B và BUG-E phải là cặp đối xứng
+
+- Mỗi BUG-B (defect) PHẢI có đúng 1 BUG-E (expected) tương ứng
+- ❌ 3 BUG-B + 1 BUG-E → không rõ E nào fix B nào
+- ✅ BUG-B01 ↔ BUG-E01, BUG-B02 ↔ BUG-E02
+
+### 2. BUG-U ít nhất 2 items
+
+- Nghĩ về behaviors **liên quan** nhưng **không bị ảnh hưởng** bởi fix
+- Hỏi: "Nếu tôi fix X, behavior nào ở gần X có thể bị ảnh hưởng?"
+- Đọc code callers/dependents → infer unchanged behaviors
+
+### 3. Mỗi behavior = 1 assertion cụ thể
+
+- ❌ "Hệ thống phải TIẾP TỤC hoạt động bình thường"
+- ✅ "Khi user nhập email hợp lệ, hệ thống phải TIẾP TỤC chấp nhận và lưu với response 200"
+
+### 4. Measurable — có thể verify bằng test
+
+- Mỗi behavior phải viết được test case tương ứng
+- Nếu không test được → behavior quá vague
+
+### 5. Từ cấm trong behaviors
+
+| Từ cấm | Vấn đề | Thay bằng |
+|--------|--------|-----------|
+| "nên", "should" | Không bắt buộc | "phải", "must" |
+| "nhanh", "fast" | Không measurable | "trong vòng 200ms" |
+| "hợp lý", "reasonable" | Mơ hồ | Số cụ thể |
+| "có thể", "can" | Description, không phải assertion | "phải" |
+| "bình thường" | Vague | Mô tả behavior cụ thể |
+
+---
+
+## Root Cause Analysis — Quy Trình
+
+> 💡 Agent PHẢI scan code trước khi viết root cause. Không đoán mò.
+
+### Step 1: Thu thập thông tin
+
+```
+1. Đọc reproduction steps từ user
+2. Tìm logs/error messages liên quan
+3. Xác định input → output mong đợi vs thực tế
+```
+
+### Step 2: Scan codebase
+
+```
+1. Tìm entry point (API route, UI handler, event listener)
+2. Trace execution path — follow data flow từ input → bug location
+3. Đọc code xung quanh bug location — context 20-30 dòng
+4. Kiểm tra related tests — đã có test cover case này chưa?
+5. Kiểm tra git blame — code này thay đổi gần đây?
+```
+
+### Step 3: Xác định root cause
+
+```
+Root cause PHẢI trả lời được 2 câu hỏi:
+1. "Dòng code nào / logic nào gây ra bug?"
+2. "Tại sao code đó sai?" (thiếu validation, logic error, race condition, etc.)
+```
+
+### Confidence Level
+
+| Level | Criteria | Action |
+|-------|----------|--------|
+| **High** | Trace exact line, reproduce 100%, evidence rõ ràng | → Proceed to implement |
+| **Medium** | Hypothesis hợp lý, nhiều suspect, chưa reproduce 100% | → Proceed nhưng ghi cảnh báo |
+| **Low** | Chưa rõ exact location, cần debug thêm | → DỪNG, recommend debug session |
+
+---
+
+## 3-Tier Test Plan — Thiết Kế
+
+### Tier 1: Bug Reproducible (Red 🔴)
+
+**Mục đích**: Confirm bug tồn tại — test PHẢI FAIL trước khi fix.
+
+| Aspect | Giá trị |
+|--------|---------|
+| **Input** | Reproduction steps từ BUG-B* |
+| **Assert** | Current (wrong) behavior KHÔNG xảy ra |
+| **Trước fix** | ❌ FAIL (confirm bug exists) |
+| **Sau fix** | ✅ PASS |
+| **ID Convention** | TC-R01, TC-R02, ... |
+
+### Tier 2: Bug Fixed (Green 🟢)
+
+**Mục đích**: Confirm fix hoạt động — test PHẢI PASS sau khi fix.
+
+| Aspect | Giá trị |
+|--------|---------|
+| **Input** | Same scenario từ BUG-E* |
+| **Assert** | Expected (correct) behavior |
+| **Trước fix** | ❌ FAIL |
+| **Sau fix** | ✅ PASS |
+| **ID Convention** | TC-G01, TC-G02, ... |
+
+### Tier 3: No Regression (Protect 🛡️)
+
+**Mục đích**: Confirm unchanged behaviors vẫn đúng — PHẢI PASS cả trước và sau fix.
+
+| Aspect | Giá trị |
+|--------|---------|
+| **Input** | Scenarios từ BUG-U* |
+| **Assert** | Unchanged behavior vẫn đúng |
+| **Trước fix** | ✅ PASS |
+| **Sau fix** | ✅ PASS |
+| **ID Convention** | TC-P01, TC-P02, ... |
+
+### Mapping Matrix (bắt buộc trong bugfix.md)
+
+| Behavior | Test Tier | Test ID | Trước fix | Sau fix |
+|----------|-----------|---------|-----------|---------|
+| BUG-B01 | T1 (Red) | TC-R01 | ❌ FAIL | ✅ PASS |
+| BUG-E01 | T2 (Green) | TC-G01 | ❌ FAIL | ✅ PASS |
+| BUG-U01 | T3 (Protect) | TC-P01 | ✅ PASS | ✅ PASS |
+| BUG-U02 | T3 (Protect) | TC-P02 | ✅ PASS | ✅ PASS |
+
+---
+
+## Scope Analysis
+
+### Xác định files cần thay đổi
+
+```
+1. Từ root cause → file(s) chứa bug
+2. Từ fix approach → file(s) cần modify
+3. Từ test plan → test file(s) cần tạo/update
+4. TỔNG files giới hạn (nếu > 10 → cân nhắc escalate)
+```
+
+### Xác định constraints
+
+```
+1. Đọc context.md → No-Go Zones
+2. Từ BUG-U* → infer modules phải giữ nguyên
+3. Liệt kê explicit: "File X KHÔNG được thay đổi vì Y"
+```
+
+---
+
+## V-Flow Integration Points
+
+- **context.md** → No-Go Zones, tech constraints
+- **constitution.md** → Naming conventions, patterns
+- **ears-writer skill** → EARS notation reference cho behaviors
+- **tdd-driver skill** → Phase B.1 implement sẽ dùng 3-tier tests từ bugfix.md
+- **adversarial-reviewer skill** → Phase R.1 review dùng 3-tier checklist
+- **bugfix.md** → Output chính (thay vì spec.md)
+- **_session.md** → Append trace entry `[BF]`
+- **.flow-state.yaml** → Init `project_type: "bugfix"`
+
+---
+
+## Output — bugfix.md Structure
+
+```markdown
+# Bugfix — [BUG-ID] [Mô tả ngắn]
+
+**Severity**: P1 | P2 | P3 | P4
+**Reporter**: [Tên/source]
+**Affected Module**: [module/domain]
+**Spec Version**: v1.0
+**Date**: [YYYY-MM-DD]
+
+## 1. Bug Report
+### Reproduction Steps
+### Environment
+
+## 2. Bugfix Analysis (3-Behavior Model)
+### 2.1 Current Behavior (Defect) 🔴
+### 2.2 Expected Behavior (Correct) 🟢
+### 2.3 Unchanged Behavior (Regression Prevention) 🛡️
+
+## 3. Root Cause Analysis
+### Hypothesis
+### Affected Code
+### Why It Happened
+
+## 4. Scope
+### Files cần thay đổi
+### Constraints
+### No-Go Check
+
+## 5. Test Plan (3-Tier)
+### T1: Bug Reproducible (Red 🔴)
+### T2: Bug Fixed (Green 🟢)
+### T3: No Regression (Protect 🛡️)
+### Mapping Matrix
+
+## 6. Acceptance Criteria
+
+## 7. Routing
+```
+
+---
+
+## Checklist Trước Khi Submit bugfix.md
+
+```
+[ ] 3-Behavior Model đầy đủ:
+    [ ] ≥1 BUG-B (defect) — mô tả cụ thể, measurable
+    [ ] ≥1 BUG-E (expected) — đối xứng 1:1 với từng BUG-B
+    [ ] ≥2 BUG-U (unchanged) — behaviors liên quan phải giữ nguyên
+[ ] Root Cause Analysis:
+    [ ] Có hypothesis với evidence (file + line)
+    [ ] Confidence level xác định (high/medium/low)
+    [ ] Nếu confidence = low → DỪNG, recommend debug
+[ ] Scope:
+    [ ] Files cần thay đổi listed
+    [ ] Constraints listed
+    [ ] No-Go check done (context.md)
+[ ] Test Plan 3-Tier:
+    [ ] T1 (Red): ≥1 test reproduce bug
+    [ ] T2 (Green): ≥1 test verify fix
+    [ ] T3 (Protect): ≥2 tests regression prevention
+    [ ] Mapping matrix đầy đủ
+[ ] Acceptance Criteria: ≥3 ACs cover cả 3 behavior types
+[ ] Không dùng từ cấm: "nên", "nhanh", "hợp lý", "có thể", "bình thường"
+```
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho lỗi phổ biến khi phân tích bug — cập nhật liên tục.

package/skills/specify/bugfix-analyst/config.json

@@ -0,0 +1,41 @@
+{
+  "setup_questions": [
+    {
+      "id": "min_unchanged",
+      "question": "Số Unchanged Behaviors (BUG-U) tối thiểu phải document?",
+      "type": "number",
+      "default": 2,
+      "description": "Tối thiểu 2 BUG-U để đảm bảo regression prevention có ý nghĩa."
+    },
+    {
+      "id": "confidence_threshold",
+      "question": "Confidence level tối thiểu để proceed implement?",
+      "options": ["high", "medium", "low"],
+      "default": "medium",
+      "description": "high = chỉ proceed khi chắc chắn. medium = proceed kèm cảnh báo. low = DỪNG, cần debug thêm."
+    },
+    {
+      "id": "max_scope_files",
+      "question": "Số files thay đổi tối đa trước khi escalate?",
+      "type": "number",
+      "default": 10,
+      "description": "Nếu scope > N files → cân nhắc escalate sang /v.specify full pipeline."
+    },
+    {
+      "id": "design_phase",
+      "question": "Bắt buộc Phase 2 (Fix Design)?",
+      "options": ["required", "optional", "auto"],
+      "default": "auto",
+      "description": "required = luôn tạo design.md. optional = skip nếu root cause rõ. auto = tự quyết dựa trên complexity."
+    }
+  ],
+  "hooks": {
+    "pre_analysis": "Scan codebase → trace execution path → build root cause hypothesis",
+    "post_analysis": "Verify 3-behavior model đầy đủ, mapping matrix complete, append _session.md"
+  },
+  "memory": {
+    "file": "bugfix-history.log",
+    "format": "[date] | [bug_id] | [severity] | [confidence] | [behaviors_b] | [behaviors_e] | [behaviors_u] | [tests_t1] | [tests_t2] | [tests_t3] | [verdict]",
+    "purpose": "Track bugfix quality — dùng cho /v.metrics và /v.retrospective"
+  }
+}

package/skills/specify/bugfix-analyst/examples/bad/common-mistakes.md

@@ -0,0 +1,71 @@
+# Bad Examples — Bugfix Analysis Anti-Patterns
+
+---
+
+❌ **Unchanged Behavior quá generic**:
+```
+### Unchanged Behavior 🛡️
+- BUG-U01: Hệ thống phải TIẾP TỤC hoạt động bình thường
+```
+→ Vấn đề: "Hoạt động bình thường" không test được. Không rõ behavior cụ thể nào phải giữ.
+→ Fix: Mô tả chính xác behavior: "Khi user nhập email hợp lệ không có khoảng trắng, hệ thống phải TIẾP TỤC chấp nhận với response 200"
+
+---
+
+❌ **Root Cause = Symptom**:
+```
+### Root Cause
+- Root Cause: API trả về lỗi 500
+- Confidence: high
+```
+→ Vấn đề: 500 là symptom, không phải root cause. Tại sao 500? SQL error? Null pointer? Timeout?
+→ Fix: "SQL query không escape ký tự `'` trong field name, gây syntax error tại user_repository.dart:42"
+
+---
+
+❌ **BUG-B và BUG-E không đối xứng**:
+```
+### Current Behavior 🔴
+- BUG-B01: Form chấp nhận email sai format
+- BUG-B02: Form cho phép submit khi field trống
+- BUG-B03: Error message không hiện
+
+### Expected Behavior 🟢  
+- BUG-E01: Form phải validate đúng
+```
+→ Vấn đề: 3 defects nhưng chỉ 1 expected behavior. Không rõ BUG-E01 fix bug nào.
+→ Fix: BUG-B01 ↔ BUG-E01, BUG-B02 ↔ BUG-E02, BUG-B03 ↔ BUG-E03 (mapping 1:1)
+
+---
+
+❌ **Thiếu Unchanged Behavior hoàn toàn**:
+```
+## Bugfix Analysis
+### Current Behavior 🔴
+- BUG-B01: ...
+### Expected Behavior 🟢
+- BUG-E01: ...
+(không có section Unchanged)
+```
+→ Vấn đề: Thiếu regression prevention. Fix có thể break behaviors liên quan.
+→ Fix: LUÔN có ≥2 BUG-U. Hỏi: "Code nào call function bị fix?" → Infer unchanged behaviors.
+
+---
+
+❌ **Test plan chỉ có T2 (Green)**:
+```
+## Test Plan
+- [ ] Test verify email validation hoạt động đúng
+- [ ] Test verify form submit thành công
+```
+→ Vấn đề: Chỉ test fix hoạt động. Không test bug reproduce (T1) và không test regression (T3).
+→ Fix: Phải có cả 3 tiers: T1 (reproduce bug) + T2 (verify fix) + T3 (no regression).
+
+---
+
+❌ **Scope creep — fix nhiều bug trong 1 analysis**:
+```
+# Bugfix — Email validation + Password strength + Login redirect
+```
+→ Vấn đề: 3 bug khác nhau trong 1 bugfix.md. Scope quá lớn, regression risk cao.
+→ Fix: 1 bugfix.md = 1 bug. Tạo bugfix riêng cho mỗi bug hoặc dùng /v.quickfix cho bug nhỏ.

package/skills/specify/bugfix-analyst/examples/good/email-validation-bugfix.md

@@ -0,0 +1,53 @@
+# Good Example — Email Validation Bugfix
+
+## Bugfix Analysis (3-Behavior Model)
+
+### 2.1 Current Behavior (Defect) 🔴
+- **BUG-B01**: Khi user nhập email có khoảng trắng đầu/cuối (vd: " user@test.com "),
+  hệ thống chấp nhận và lưu email chứa khoảng trắng vào database
+- **BUG-B02**: Khi user nhập email " user@test.com " và sau đó đăng nhập với "user@test.com",
+  hệ thống báo "Email không tồn tại" vì so sánh exact match
+
+### 2.2 Expected Behavior (Correct) 🟢
+- **BUG-E01**: Khi user nhập email có khoảng trắng đầu/cuối,
+  hệ thống phải trim khoảng trắng trước khi validate và lưu "user@test.com" (đã trim)
+- **BUG-E02**: Khi user nhập email có khoảng trắng và sau đó đăng nhập với email không khoảng trắng,
+  hệ thống phải authenticate thành công (vì email đã được trim khi lưu)
+
+### 2.3 Unchanged Behavior (Regression Prevention) 🛡️
+- **BUG-U01**: Khi user nhập email hợp lệ không có khoảng trắng (vd: "user@test.com"),
+  hệ thống phải TIẾP TỤC chấp nhận và lưu bình thường với response 200
+- **BUG-U02**: Khi user nhập email không hợp lệ (thiếu @, domain sai, vd: "user@", "user"),
+  hệ thống phải TIẾP TỤC từ chối với error "Email không hợp lệ" và response 400
+- **BUG-U03**: Khi user nhập các field khác (name, phone),
+  hệ thống phải TIẾP TỤC validate theo rules hiện tại, không bị ảnh hưởng bởi fix email
+
+---
+
+## Root Cause Analysis
+
+### Hypothesis
+- **Root Cause**: Hàm `validateEmail()` trong `lib/validators/email_validator.dart:28`
+  validate format nhưng KHÔNG trim whitespace trước khi validate và lưu
+- **Confidence**: high
+- **Evidence**: Code line 28: `return emailRegex.hasMatch(input)` — `input` chưa được `.trim()`
+
+### Affected Code
+| File | Line(s) | Mô tả vấn đề |
+|------|---------|---------------|
+| `lib/validators/email_validator.dart` | L28 | `hasMatch(input)` thiếu `.trim()` |
+| `lib/repositories/user_repository.dart` | L45 | `save(email)` lưu email raw, chưa trim |
+
+---
+
+## Test Plan (3-Tier) — Mapping Matrix
+
+| Behavior | Test Tier | Test ID | Trước fix | Sau fix |
+|----------|-----------|---------|-----------|---------|
+| BUG-B01 | T1 (Red) | TC-R01 | ❌ FAIL | ✅ PASS |
+| BUG-B02 | T1 (Red) | TC-R02 | ❌ FAIL | ✅ PASS |
+| BUG-E01 | T2 (Green) | TC-G01 | ❌ FAIL | ✅ PASS |
+| BUG-E02 | T2 (Green) | TC-G02 | ❌ FAIL | ✅ PASS |
+| BUG-U01 | T3 (Protect) | TC-P01 | ✅ PASS | ✅ PASS |
+| BUG-U02 | T3 (Protect) | TC-P02 | ✅ PASS | ✅ PASS |
+| BUG-U03 | T3 (Protect) | TC-P03 | ✅ PASS | ✅ PASS |

package/skills/specify/bugfix-analyst/gotchas.md

@@ -0,0 +1,51 @@
+# Gotchas — Bugfix Analyst
+
+> Cập nhật liên tục khi Agent gặp edge case mới.
+> Mỗi lỗi lặp lại 2 lần → BẮT BUỘC thêm vào đây.
+
+---
+
+## Anti-Patterns
+
+1. ❌ **Unchanged Behavior quá generic** — "Hệ thống phải TIẾP TỤC hoạt động bình thường"
+   - **Fix**: Mô tả CỤ THỂ: "Khi user nhập email hợp lệ, hệ thống phải TIẾP TỤC chấp nhận và lưu với response 200"
+   - **Hậu quả**: T3 test không viết được → regression không bị phát hiện.
+
+2. ❌ **Root Cause = Symptom** — "Root cause: API trả 500"
+   - **Fix**: Đó là symptom. Root cause: "SQL query không escape ký tự đặc biệt trong field `name`, gây SQL syntax error tại `user_repository.dart:42`"
+   - **Hậu quả**: Fix symptom (wrap try-catch) → bug vẫn tồn tại, chỉ bị che.
+
+3. ❌ **Skip T3 tests** — "Chắc không break gì" → skip regression tests
+   - **Fix**: T3 LUÔN có ≥2 tests. Đây là **giá trị chính** của bugfix flow.
+   - **Hậu quả**: Fix gây regression → phải hotfix → vòng lặp chi phí.
+
+4. ❌ **Fix symptom thay vì root cause** — Thêm try-catch wrap error → "hết lỗi 500"
+   - **Fix**: Trace đến root cause thực sự. Try-catch chỉ là band-aid.
+   - **Signal**: Nếu fix chỉ là wrap/suppress error → almost certainly wrong.
+
+5. ❌ **BUG-B và BUG-E không đối xứng** — 3 BUG-B nhưng chỉ 1 BUG-E
+   - **Fix**: Mỗi BUG-B PHẢI có đúng 1 BUG-E tương ứng. Mapping 1:1.
+   - **Hậu quả**: Không rõ fix nào cho bug nào → confusion khi implement.
+
+6. ❌ **Quên scan codebase** — Viết root cause dựa trên guess, không trace code
+   - **Fix**: PHẢI scan code trước khi viết root cause. Evidence = file + line range.
+   - **Hậu quả**: Root cause sai → fix sai → bug vẫn còn.
+
+7. ❌ **Scope creep silent** — Fix 1 bug nhưng "tiện thể" fix 3 bug khác
+   - **Fix**: 1 bugfix.md = 1 bug. Các bug khác → tạo bugfix riêng hoặc quickfix.
+   - **Hậu quả**: Scope lớn → review khó → regression risk tăng.
+
+8. ❌ **Quên context.md / constitution.md** — Phân tích bug mà không check constraints
+   - **Fix**: LUÔN check No-Go Zones + constitution patterns trước khi propose fix.
+   - **Hậu quả**: Fix vi phạm No-Go Zone → bị block ở implement.
+
+---
+
+## Edge Cases
+
+- ✅ Root cause không tìm được → Ghi confidence = "Low", recommend pairing/debug session. KHÔNG implement khi low confidence.
+- ✅ Bug ảnh hưởng nhiều module (> 10 files) → Escalate sang `/v.specify` full pipeline.
+- ✅ Bug 5-10 files → Có thể tiếp tục nhưng ghi warning vào bugfix.md.
+- ✅ Bug đã fix trước đó nhưng regression → Đọc git history, document fix cũ trong Root Cause. T3 PHẢI cover case fix cũ gây regression.
+- ✅ Unchanged behavior khó xác định → Hỏi: "Code nào call/depend function bị fix?" → Infer BUG-U từ callers/dependents.
+- ✅ Bug chỉ reproduce trên specific environment → Document environment rõ ràng, flag trong bugfix.md.

package/skills/specify/ears-writer/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ears-writer
+description: "Hướng dẫn BA Agent viết requirements theo EARS notation chính xác. Agent PHẢI đọc skill này trước khi viết bất kỳ requirement nào trong spec.md."
+trigger: "Khi viết hoặc review requirements trong spec.md"
+phase: "S.1"
+used_by:
+  - /v.specify
+  - /v.ba-critic
+---
+
+# EARS Writer — Viết Requirements Đúng Chuẩn
+
+> ⚠️ Đây là **Skill bắt buộc** cho BA Agent khi viết requirements.
+> Đọc trước khi viết bất kỳ REQ nào. Không có EARS → spec mơ hồ, không testable.
+>
+> → Xem `gotchas.md` cho Anti-patterns phổ biến.
+> → Xem `examples/good/` và `examples/bad/` cho ví dụ thực tế.
+> → Xem `config.json` để customize EARS settings (language, ID style).
+> → Chạy `.v-flow/skills/specify/ears-writer/scripts/check-ears-compliance.sh <spec.md>` để validate tự động.
+
+---
+
+## Khi nào KHÔNG cần skill này
+
+- Viết mô tả feature tổng quan (không phải requirement)
+- Viết user story dạng "As a... I want... So that..." (dùng ở 1.1 Mô tả, không phải §3 Requirements)
+- Viết acceptance criteria (AC là con của REQ, không phải REQ)
+
+---
+
+## 4 Templates EARS
+
+Mỗi requirement thuộc ĐÚNG 1 loại. Chọn loại dựa trên bản chất yêu cầu:
+
+| Type | Keyword khởi đầu | Template | Signal nhận biết |
+|------|-------------------|----------|-----------------|
+| **Ubiquitous** | `phải` | `Hệ thống phải <action>` | Luôn đúng, không phụ thuộc event |
+| **Event-driven** | `Khi` | `Khi <trigger>, hệ thống phải <action>` | Có sự kiện rõ ràng kích hoạt |
+| **State-driven** | `Trong khi` | `Trong khi <state>, hệ thống phải <action>` | Áp dụng SUỐT thời gian ở trạng thái |
+| **Optional** | `Nếu` | `Nếu <condition>, hệ thống phải <action>` | Có điều kiện tiên quyết |
+
+### Cách chọn đúng loại
+
+```
+Yêu cầu luôn đúng? ───────────────────── Ubiquitous (REQ-U)
+Có sự kiện trigger? ──────────────────── Event-driven (REQ-E)  
+Áp dụng suốt 1 trạng thái? ───────────── State-driven (REQ-S)
+Chỉ áp dụng khi condition thỏa? ──────── Optional (REQ-O)
+```
+
+### ID Convention
+
+| Prefix | Loại | Ví dụ |
+|--------|------|-------|
+| REQ-U | Ubiquitous | REQ-U01, REQ-U02 |
+| REQ-E | Event-driven | REQ-E01, REQ-E02 |
+| REQ-S | State-driven | REQ-S01, REQ-S02 |
+| REQ-O | Optional | REQ-O01, REQ-O02 |
+
+---
+
+## Đặc thù và Quy ước Nội bộ
+
+> 💡 Đây là phần **QUAN TRỌNG NHẤT** — những gì LLM thường sai khi viết EARS.
+
+### 1. Mỗi REQ = 1 action duy nhất
+- ❌ "Hệ thống phải validate input và lưu vào DB"
+- ✅ Tách thành REQ-U01 (validate) + REQ-E01 (lưu DB)
+- **Lý do**: 1 REQ → 1 test case → 1 task. Trộn lẫn = trace mất.
+
+### 2. Acceptance Criteria ngay dưới REQ
+- Mỗi REQ phải có ≥1 AC dạng checkbox `- [ ] ...`
+- AC phải **measurable** — có số cụ thể hoặc boolean outcome
+
+### 3. Security requirements luôn có ít nhất 1 REQ-U
+- Feature có auth/data → phải có REQ-U cho security
+- VD: REQ-U01: "Hệ thống phải hash password bằng bcrypt trước khi lưu"
+
+### 4. Error handling = REQ riêng
+- Happy path: REQ-E01 (POST valid → 201)
+- Error path: REQ-E02 (POST invalid → 400 + details)
+- Đừng nhồi error vào REQ-E01
+
+### 5. Từ ngữ cấm trong requirements
+Grep spec output trước khi submit — nếu tìm thấy bất kỳ từ nào, requirement SAI:
+
+| Từ cấm | Vấn đề | Thay bằng |
+|--------|--------|----------|
+| "nên", "should" | Không bắt buộc → không testable | "phải", "must" |
+| "nhanh", "fast" | Không measurable | "trong vòng 200ms" |
+| "dễ dùng", "user-friendly" | Chủ quan → không testable | Mô tả behavior cụ thể |
+| "hợp lý", "reasonable" | Mơ hồ | Số cụ thể |
+| "có thể", "can" | Feature description, không phải requirement | "phải" |
+| "v.v.", "etc." | Incomplete specification | Liệt kê hết |
+
+---
+
+## Mapping EARS → Downstream Agents
+
+> 💡 Mỗi loại REQ gợi ý implementation pattern cho các Agent phía sau:
+
+| REQ Type | Plan Agent nên | Test Agent nên | Implement Agent nên |
+|----------|---------------|---------------|-------------------|
+| REQ-U | Always-on component, middleware, interceptor | Unit test (always true — test mọi entry point) | Core module, no conditional logic |
+| REQ-E | Event handler, controller action, callback | Event-triggered test (given trigger → expect action) | Handler function, route handler |
+| REQ-S | State management, state machine, lifecycle | State-based test (while in state → verify behavior) | Stateful component, BLoC, StateNotifier |
+| REQ-O | Conditional logic, feature flag, guard | Condition branch test (if condition → expect, else → expect different) | if/guard clause, optional adapter |
+
+---
+
+## Checklist Trước Khi Submit Spec
+
+```
+[ ] Mỗi requirement có ID đúng convention (REQ-U/E/S/O + số)
+[ ] Mỗi requirement bắt đầu bằng keyword EARS đúng loại
+[ ] Mỗi requirement chỉ có 1 action chính
+[ ] Mọi số liệu đều cụ thể (thời gian, kích thước, số lượng)
+[ ] Mỗi requirement có ≥1 Acceptance Criteria
+[ ] Không có từ cấm: "nên", "nhanh", "dễ dùng", "hợp lý", "có thể", "v.v."
+[ ] Có ≥1 REQ-U cho security (nếu feature involve auth/data)
+[ ] Error cases có REQ riêng (tách khỏi happy path)
+[ ] Không có REQ nào vi phạm No-Go Zones (kiểm tra context.md)
+```
+
+---
+
+## Gotchas
+
+→ Xem `gotchas.md` cho danh sách lỗi phổ biến — cập nhật liên tục khi Agent mắc lỗi mới.

package/skills/specify/ears-writer/config.json

@@ -0,0 +1,20 @@
+{
+  "setup_questions": [
+    {
+      "id": "language",
+      "question": "Requirements viết bằng ngôn ngữ nào?",
+      "options": ["vi", "en", "mixed"],
+      "default": "vi"
+    },
+    {
+      "id": "id_style",
+      "question": "REQ ID style?",
+      "options": ["ears-prefixed", "sequential"],
+      "default": "ears-prefixed",
+      "description": "ears-prefixed = REQ-U01, REQ-E01. sequential = REQ-001, REQ-002."
+    }
+  ],
+  "hooks": {
+    "post_spec": "Scan spec.md → kiểm tra từ cấm, EARS compliance, ID uniqueness"
+  }
+}

package/skills/specify/ears-writer/examples/bad/common-mistakes.md

@@ -0,0 +1,17 @@
+❌ "User có thể đăng nhập vào hệ thống bằng email và password"
+→ Vấn đề: Feature description, không phải EARS requirement. Thiếu keyword, thiếu AC.
+
+❌ "Hệ thống nên validate input trước khi lưu"
+→ Vấn đề: "Nên" = optional behavior → không testable. Dùng "phải".
+
+❌ "REQ-001: Hệ thống phải validate input và lưu vào DB và gửi email xác nhận"
+→ Vấn đề: 3 actions trong 1 REQ. Tách thành 3 REQs riêng.
+
+❌ "Hệ thống phải nhanh và dễ sử dụng"
+→ Vấn đề: "Nhanh" và "dễ sử dụng" không measurable. Thay bằng số cụ thể.
+
+❌ "REQ-E01: Hệ thống phải hash password"
+→ Vấn đề: Dùng prefix Event-driven (E) nhưng nội dung là Ubiquitous (U). Sai loại.
+
+❌ "Khi user login, hệ thống phải xử lý hợp lý"
+→ Vấn đề: "Hợp lý" = mơ hồ. Mô tả CHÍNH XÁC behavior expected.