spec-lite 1.2.2 → 1.3.1

package/skills/spec-test/SKILL.md

@@ -0,0 +1,365 @@
+---
+name: spec-test
+description: Tạo test.md cho một integration bằng cách mechanical derive Test Scenarios + Test Cases từ Flows/US/AC/VR/FAC trong frd.md. Auto-cascade lên feature/{F-XXX}/tsd.md. Role QC, song song với /spec-tech (DEV) — cả hai chỉ phụ thuộc spec.md approved.
+---
+
+# spec-test
+
+## Overview
+
+Tạo `test.md` cho một integration trong `specs/integrations/{slug}/`.
+
+`test.md` là verification design ở integration level — định nghĩa **how to verify** rằng integration đáp ứng `spec.md`. Nội dung gồm Test Strategy (per integration) + Changes blocks cascade lên feature `tsd.md` (Test Spec Document).
+
+**Hai artifact tách bạch:**
+- `specs/integrations/{slug}/test.md` — integration-level, ephemeral, PR record bất biến sau approve (single-word naming như `spec.md` / `tech.md` / `plan.md`).
+- `specs/main/feature/{F-XXX}-{slug}/tsd.md` — feature-level, persistent canonical artifact (3-letter naming như `frd.md` / `fdd.md`). TC content cuối cùng nằm ở đây.
+
+**Role:** QC. Song song với `/spec-tech` (DEV role). Cả hai chỉ phụ thuộc `spec.md` approved — không có thứ tự bắt buộc giữa chúng.
+
+**Cốt lõi:** agent **mechanical derive** TC từ frd.md (mỗi Flow → TS, mỗi US/AC → Functional TC, mỗi VR → Validation TC positive+negative, mỗi FAC → Feature AC TC). Agent KHÔNG sáng tạo TC ngoài frd — phần đó là QC thêm tay khi review.
+
+## When to Use
+
+- `spec.md` đã được approve → bắt đầu thiết kế verification
+- Bổ sung `test.md` cho integration đã có spec.md/tech.md nhưng chưa có test.md
+
+## When NOT to Use
+
+- `spec.md` chưa có hoặc chưa approve → chạy `/spec-new` trước
+- Integration có `features: []` (không touch feature nào) → `test.md` không áp dụng vì component-level `tsd.md` không tồn tại trong kit này (xem `templates/main/feature/tsd-template.md` — component contract verify gián tiếp qua feature TC + unit test trong code). Verification cho integration thuần component → đặt trong tech.md hoặc phase Verification của plan.md.
+- Chỉ muốn cập nhật `test.md` đã có → edit file trực tiếp
+
+---
+
+## Process
+
+### Bước 1: Xác định integration
+
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là số thứ tự (`2`, `002`) hoặc slug (`002-implement-todo`)
+- Quét `specs/integrations/*/spec.md`, tìm integration khớp với argument
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy integration khớp với "{argument}". Kiểm tra lại tên hoặc số thứ tự.
+- Nếu tìm thấy → dùng integration đó, bắt đầu luôn
+
+**Nếu không có ARGUMENT:**
+
+Quét `specs/integrations/`. Liệt kê **tất cả** integrations có `spec.md`, đánh dấu những cái đã có `test.md`:
+
+```
+Integrations:
+
+  [1] 001-implement-auth    — Implement Auth             spec✓ test✓
+  [2] 002-implement-todo    — Implement Todo Management  spec✓ test—
+
+Chọn số integration:
+```
+
+Nếu không có integration nào → thông báo:
+> Chưa có integration nào. Hãy chạy `/spec-new` trước.
+
+Nếu integration đã có `test.md` → hỏi trước khi tiếp tục:
+> `test.md` đã tồn tại cho integration này. Tiếp tục sẽ ghi đè. Tiếp tục không?
+
+---
+
+### Bước 1b: Gate check
+
+Đọc frontmatter của `specs/integrations/{slug}/spec.md`.
+
+**Check 1 — spec.md phải approved:**
+
+Nếu `status` **không phải** `approved`:
+
+> ⛔ `spec.md` của integration **{slug}** chưa được approve (status hiện tại: `{status}`).
+>
+> `/spec-test` cần spec.md approved vì cascade frd.md (nguồn của TC) chỉ apply sau khi approve.
+>
+> Để tiếp tục:
+> 1. Review `specs/integrations/{slug}/spec.md`
+> 2. Approve (đổi `status: draft` → `status: approved`)
+>
+> Sau đó chạy lại `/spec-test`.
+
+**Dừng hoàn toàn.**
+
+**Check 2 — features non-empty:**
+
+Đọc `features:` trong frontmatter. Nếu `[]`:
+
+> ⛔ Integration **{slug}** không touch feature nào (`features: []`).
+>
+> `/spec-test` cascade lên `feature/{F-XXX}/tsd.md` — không áp dụng cho integration thuần component.
+> Component contract được verify gián tiếp qua feature TC + unit test trong code (xem `templates/main/feature/tsd-template.md`).
+>
+> Đặt verification cho integration này trong:
+> - `tech.md > Implementation Notes` — verification approach
+> - `plan.md > Verification phase` — test tasks cụ thể
+>
+> Không có gì để làm với `/spec-test`. Dừng.
+
+Nếu cả 2 check pass → tiếp tục Bước 2.
+
+---
+
+### Bước 2: Load context
+
+Load các file sau:
+
+- `specs/integrations/{slug}/spec.md` — đọc toàn bộ + frontmatter (`features`)
+- `specs/main/feature/{F-XXX}-{slug}/frd.md` — cho mỗi feature trong frontmatter `features` (source của TC — bắt buộc tồn tại vì cascade từ spec.md đã apply)
+- `specs/main/feature/{F-XXX}-{slug}/tsd.md` — cho mỗi feature trong frontmatter `features` (nếu tồn tại — cần để diff và assign next ID)
+- `specs/integrations/{slug}/tech.md` — đọc nếu tồn tại (optional, dùng để hint environment / data set / NFR perf threshold)
+
+Tóm tắt context:
+
+```
+TÔI HIỂU:
+- Integration: {title}
+- Features touched: {từ frontmatter — F-XXX, ...}
+- Mỗi feature có trong frd.md:
+  - F-XXX: {N} Flows, {M} US ({K} AC), {P} VR, {Q} FAC
+- tsd.md hiện tại:
+  - F-XXX: tồn tại — max(TS)=NNN, max(TC)=MMM   (cho operation=update)
+  - F-YYY: chưa tồn tại                          (cho operation=create)
+- tech.md: {tồn tại / chưa — nếu có thì có hint gì cho env/data/perf}
+```
+
+Nếu frd.md của feature nào không tồn tại → báo lỗi và dừng (lỗi cascade từ spec.md trước đó):
+> ⛔ `specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại nhưng feature có trong `features:` của spec.md. Cascade từ spec.md có thể đã fail. Kiểm tra lại.
+
+---
+
+### Bước 3: Auto-derive draft
+
+**Nguyên tắc:** agent derive **1:1 mechanically** từ frd.md. KHÔNG sáng tạo TC ngoài frd. Phần creative (extra edge cases, exploratory testing) thuộc về QC khi review.
+
+#### 3.1 ID assignment
+
+Với mỗi feature trong `features:`:
+
+- Đọc `feature/{F-XXX}/tsd.md` hiện tại (nếu có) để lấy `max(TS-F{NNN}-seq)` và `max(TC-F{NNN}-seq)`
+- ID mới = `max(seq) + 1`, format 3 chữ số
+- TC dùng **chung sequence** cho Functional / Validation / Feature AC — không reset theo loại
+- ID **stable** — không tái sử dụng khi [REMOVE], không renumber khi [MODIFY]
+- Operation=create (tsd.md chưa tồn tại) → bắt đầu từ `001`
+
+#### 3.2 Derivation rules
+
+Áp dụng cho mỗi feature, sinh ra Changes block tương ứng:
+
+**A. Test Scenarios** — mỗi Flow trong `frd.md > User Flows` → 1 Test Scenario.
+
+- TS ID mới = `TS-F{NNN}-{next_seq}`
+- Flow ref: `frd.md > Flow {N}: {name}`
+- Preconditions: derive từ điểm bắt đầu của Mermaid flow
+- Postconditions: derive từ điểm kết thúc happy
+- Paths: liệt kê happy + mỗi edge case trong Mermaid
+- Test cases: list các TC ID sẽ cover TS này (cross-reference TC sinh ở bước B/D)
+
+**B. Functional Test Cases** — mỗi AC trong mỗi US → 1 Functional TC.
+
+- TC ID mới = `TC-F{NNN}-{next_seq}`
+- Type: `Functional — positive` (mặc định cho AC happy), `Functional — negative` nếu AC mô tả nhánh fail
+- Priority: derive từ US Priority (xem 3.3)
+- Covers: `US-{F_ID}-{seq}`, `AC-{F_ID}-{seq}`
+- Scenario: TS ID của Flow tương ứng (nếu AC nằm trong flow)
+- Preconditions/Steps/Expected: dịch 1:1 từ Given/When/Then của AC
+
+**C. Validation Test Cases** — mỗi VR → tối thiểu 2 TC.
+
+- 1 positive: input hợp lệ → accept
+- 1+ negative: mỗi nhánh fail là 1 TC riêng (vd VR "email format" → 1 case missing `@`, 1 case missing domain, 1 case có space). Agent infer các nhánh fail từ rule text.
+- TC ID mới = `TC-F{NNN}-{next_seq}` (chung sequence với Functional)
+- Form bảng theo template gốc
+- Covers: `VR-{F_ID}-{seq}`
+- Priority: P1 mặc định (xem 3.3)
+
+**D. Feature AC Test Cases** — mỗi FAC → 1 Feature AC TC.
+
+- TC ID mới = `TC-F{NNN}-{next_seq}`
+- Type: derive từ nhóm FAC (`e2e` / `consistency` / `NFR` / `data & migration`) — đọc context FAC để phân loại
+- Priority: theo bảng ở 3.3
+- Covers: `FAC-{F_ID}-{seq}`
+- Spans: list US IDs mà FAC liên quan (nếu FAC e2e)
+- Preconditions/Steps/Expected: dịch 1:1 từ Given/When/Then của FAC
+
+**E. Traceability Matrix** — row per frd item:
+
+- 1 row per Flow → cover by TS
+- 1 row per US → cover by TC (Functional)
+- 1 row per Story AC → cover by TC (Functional)
+- 1 row per VR → cover by TC (Validation, list tất cả positive + negative)
+- 1 row per FAC → cover by TC (Feature AC)
+- Mọi item phải có cover ✅ (vì derive 1:1). Nếu agent không thể derive một item nào → đánh dấu ❌ + ghi lý do ở Gaps section, KHÔNG silent skip.
+
+#### 3.3 Priority defaults
+
+Mọi TC đều có priority deterministic. QC override khi review (Bước 4).
+
+**TC cover US/AC** — inherit từ US Priority:
+
+| US Priority (frd) | TC Priority |
+| --- | --- |
+| Must | P0 |
+| Should | P1 |
+| Could | P2 |
+
+**TC cover VR** — inherit max priority của các US trong `Refs` column của VR. Nếu Refs trống → P1 default.
+
+**TC cover FAC** — theo nhóm FAC:
+
+| FAC group | TC Priority |
+| --- | --- |
+| End-to-end liên story | P0 |
+| Cross-story consistency | P1 |
+| NFR — security / data integrity | P0 |
+| NFR — performance / a11y / i18n / browser | P1 |
+| Data & migration | P0 |
+
+#### 3.4 Diff vs current tsd.md
+
+Với feature có tsd.md hiện tại (operation=update):
+
+- Item đã có TC cover → KHÔNG sinh TC mới, giữ nguyên TC cũ
+- Item trong frd nhưng chưa có TC cover → sinh TC mới với marker `[NEW]`
+- TC hiện tại cover item đã bị xóa khỏi frd (orphan) → đánh dấu `[REMOVE]` + ghi lý do (vd: "AC-F001-005 không còn trong frd")
+- Item trong frd đã đổi nội dung mà TC cũ không còn match (vd AC đổi expected outcome) → đánh dấu TC cũ là `[MODIFY {field}]` với field cụ thể
+
+Agent compute diff tự động — KHÔNG hỏi user "field nào đã đổi"; đọc 2 file rồi đối chiếu.
+
+**No-delta case:** nếu diff giữa frd hiện tại và tsd.md hiện tại = empty cho 1 feature (frd không thêm/đổi item nào mà tsd chưa cover) → **bỏ Changes block của feature đó hoàn toàn**, ghi `no-op` trong Cascade Summary để minh bạch.
+
+#### 3.5 Placeholders cần QC fill
+
+Agent **không suy đoán** các field sau, dùng placeholder rõ ràng để QC điền ở Bước 4:
+
+| Field | Placeholder | Vì sao agent không tự fill |
+| --- | --- | --- |
+| Environments table | Row mặc định: `dev / staging / prod-like` với `data set: TBD`, `mục đích: TBD` | Phụ thuộc setup CI/CD và availability — QC owns |
+| Test Data table | Row `{TBD — fixture}` cho mỗi seed/boundary dataset agent thấy cần | QC chọn fixture source thực tế |
+| Out of Scope | Để trống với note `<!-- QC fill -->` | Quyết định business của QC |
+| Test Strategy > Approach | Bullet generic theo template gốc | Strategy đặc thù integration QC fill |
+
+---
+
+### Bước 4: Write — sinh draft
+
+Tổng hợp và viết draft `test.md` theo `templates/integrations/test-template.md`:
+
+- **Context** — tóm tắt từ Bước 2
+- **Test Strategy** — placeholder + Environments table với placeholder rows
+- **Changes** — 1 block per feature *có delta*, mỗi block có operation + content theo template gốc `templates/main/feature/tsd-template.md`. Feature no-delta → bỏ block.
+- **Out of Scope** — empty với note QC fill
+- **Open Questions** — list các item mà agent không thể derive deterministic (vd: FAC có wording vague, VR không rõ nhánh fail nào)
+- **Cascade Summary** — table liệt kê **tất cả** feature trong `features:` (kể cả no-delta — ghi `no-op`)
+
+Hiển thị **toàn bộ draft** cho QC xem — **chưa ghi file, chưa cascade**.
+
+---
+
+### Bước 5: Review — xác nhận với user
+
+> Draft trên đã đúng chưa? QC điểm cần check:
+>
+> 1. **Mechanical derivation** — mỗi Flow / US / AC / VR / FAC trong frd đã có TC cover chưa? (xem Traceability Matrix)
+> 2. **Priority defaults** — có TC nào cần override khỏi default không?
+> 3. **Placeholders** — fill Environments / Test Data / Out of Scope / Strategy Approach.
+> 4. **Extra edge cases** — ngoài AC/VR có scenario nào QC muốn thêm? (vd: exploratory, security boundary, race condition không có trong AC)
+> 5. **Changes markers** — `[NEW]/[MODIFY]/[REMOVE]` có đúng không?
+> 6. **No-delta features** — Cascade Summary có ghi `no-op` đúng cho feature không có delta không?
+>
+> **Sau khi confirm, agent sẽ auto-apply tất cả Changes blocks lên feature tsd.md(s).**
+
+Nếu QC yêu cầu chỉnh sửa:
+- Override priority → update draft
+- Add extra TC → assign next ID, mark `[NEW]`
+- Fill placeholder → update draft
+- Remove TC khỏi draft → bỏ block hoặc đổi marker
+
+Chỉ tiến hành Bước 6 sau khi QC confirm.
+
+---
+
+### Bước 6: Save + Auto-cascade
+
+**[6.1] Ghi `specs/integrations/{slug}/test.md`** với status `approved` (không phải `draft` — human đã confirm ở Bước 5 chính là approval). Frontmatter `features` mirror từ `spec.md`.
+
+**[6.2] Auto-apply mỗi Changes block** vào `feature/{F-XXX}/tsd.md` tương ứng. Thứ tự apply: theo thứ tự xuất hiện trong frontmatter `features` (deterministic, không có forward reference giữa các feature tsd.md). Bỏ qua feature có operation `no-op` trong Cascade Summary.
+
+Cho từng block:
+
+- **Operation=create:**
+  - Tạo file `specs/main/feature/{F-XXX}-{slug}/tsd.md`
+  - Nội dung = nội dung của Changes block (theo format `templates/main/feature/tsd-template.md`)
+  - Frontmatter của tsd.md mới: status `draft` (separate lifecycle với integration test.md)
+
+- **Operation=update:**
+  - Đọc tsd.md hiện tại
+  - Với mỗi TS/TC trong Changes block:
+    - `[NEW]` → append/insert vào section tương ứng (giữ thứ tự numeric của ID)
+    - `[MODIFY {field}]` → tìm TS/TC bằng ID, update field đã chỉ định, giữ nguyên field khác
+    - `[REMOVE]` → xóa TS/TC khỏi tsd.md (ID retire, không tái sử dụng)
+  - Cập nhật Traceability Matrix: thêm row cho item mới, update row của item bị MODIFY, KHÔNG xóa row của REMOVE (đánh dấu retire)
+  - Ghi lại tsd.md
+
+**[6.3] Atomic rollback:** Nếu apply block nào fail (vd `[MODIFY TC-F001-005]` nhưng ID không tồn tại):
+1. Rollback các block đã apply trước đó về state ban đầu
+2. **Không** ghi integration test.md
+3. Báo lỗi cụ thể cho QC fix draft hoặc feature tsd.md hiện tại
+
+**[6.4] Thông báo kết quả:**
+
+```
+✓ specs/integrations/{slug}/test.md đã được tạo (status: approved)
+
+Auto-cascade applied:
+  ✓ feature/F-XXX-{slug}/tsd.md — {created | updated: +N TS, +M TC, modify K TC, remove L TC}
+  ✓ feature/F-YYY-{slug}/tsd.md — no-op (frd không đổi)
+
+Bước tiếp theo:
+  - QC: review feature tsd.md đã cascade, fill remaining TBD nếu có
+  - DEV: có thể run /plan nếu chưa có plan.md (plan.md hiện chưa consume tsd.md — test tasks tự QC manage trong test framework)
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "TC có thể nghĩ ra khi chạy test" | Không document = không có traceability. AC pass/fail không kiểm tra được nếu không có TC mapping. |
+| "VR positive đủ rồi, negative skip" | Negative case là nơi bug ẩn. Mỗi nhánh fail của VR phải có TC riêng. |
+| "Priority để default hết P1 cho nhanh" | Priority decorative thì cũng phải đúng — derive deterministic từ US Priority/FAC group. P1 hàng loạt = QC chưa nhìn frd. |
+| "Out of Scope để trống cũng được" | Mọi integration đều có thứ không test. Trống = scope creep hoặc gap không kiểm soát. |
+
+## Red Flags
+
+- Traceability Matrix có item ❌ mà không có lý do ở Gaps section → agent silent skip
+- TC có Covers trống → không trace được lên frd
+- VR có ít hơn 2 TC (1 positive + 1+ negative) → coverage thiếu
+- Priority hàng loạt giống nhau cho mọi TC → QC chưa override default
+- Test Data toàn `TBD` sau khi QC review → chưa thật sự confirm
+- Changes block có marker `[NEW]` cho TC trùng ID với TC đã có trong tsd.md hiện tại → diff bug
+- Cascade Summary thiếu row cho feature trong `features:` (kể cả no-op) → không minh bạch
+
+## Verification
+
+Trước khi QC confirm (Bước 5), kiểm tra:
+
+- [ ] Mỗi Flow trong frd có 1 TS tương ứng
+- [ ] Mỗi US AC có TC Functional cover
+- [ ] Mỗi VR có ≥1 positive + ≥1 negative TC
+- [ ] Mỗi FAC có TC Feature AC cover
+- [ ] Traceability Matrix đầy đủ (không ❌ mà không giải thích)
+- [ ] Priority deterministic theo bảng 3.3 (default), QC override visible
+- [ ] ID assignment từ max(seq)+1, không tái sử dụng, không renumber
+- [ ] Markers `[NEW]/[MODIFY {field}]/[REMOVE]` khớp diff vs current tsd.md
+- [ ] Feature no-delta được ghi `no-op` trong Cascade Summary, KHÔNG có Changes block
+
+Sau khi QC confirm (Bước 6):
+
+- [ ] Auto-apply theo thứ tự features trong frontmatter
+- [ ] Fail-safe: nếu apply fail thì không ghi integration test.md
+- [ ] Mỗi feature tsd.md mới có status `draft` (separate lifecycle)

package/skills/spec-tsd/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: spec-tsd
+description: Tạo tsd.md (Test Spec Document) trực tiếp tại feature level từ frd.md — mechanical derive Test Scenarios + Test Cases. KHÔNG cần integration, không cascade. Dùng cho brownfield onboarding (sau /spec-brownfield-feature) hoặc greenfield bootstrap khi feature đã có frd.md nhưng chưa có tsd.md.
+---
+
+# spec-tsd
+
+## Overview
+
+Tạo `specs/main/feature/{F-XXX}-{slug}/tsd.md` trực tiếp từ frd.md của feature đó — **không qua integration**, không cascade.
+
+Skill này song hành với `/spec-prd` và `/spec-sad`: skill có acronym suffix (`prd`/`sad`/`tsd`) → tạo main artifact trực tiếp. Phân biệt với `/spec-test` — skill đó tạo `test.md` integration-level và cascade qua Changes blocks.
+
+## When to Use
+
+- **Brownfield onboarding** — sau `/spec-brownfield-feature` đã sinh frd.md, cần bootstrap tsd.md để có test coverage tracking ngay từ đầu.
+- **Greenfield deferred** — feature có frd.md từ lâu nhưng tsd.md chưa được tạo (vd: test design bị defer).
+- **Ad-hoc rebuild** — tsd.md drift quá xa khỏi frd.md, muốn regenerate fresh.
+
+## When NOT to Use
+
+- Có integration mới và muốn cascade thay đổi frd lên tsd hiện tại → dùng `/spec-test` (changeset patch giữ ID stable)
+- Chỉ muốn sửa vài TC → edit `tsd.md` trực tiếp
+- Feature chưa có frd.md → chạy `/spec-brownfield-feature` (brownfield) hoặc `/spec-new` (greenfield) trước
+
+## Cảnh báo về ID stability
+
+`/spec-tsd` **regenerate IDs từ 001** mỗi lần chạy. Nếu tsd.md đã tồn tại và đang được reference (vd: test code có `// covers TC-F001-005`), rebuild sẽ làm vỡ những reference đó.
+
+Quy tắc:
+- **tsd.md chưa tồn tại** → an toàn, không có reference, regenerate fresh.
+- **tsd.md tồn tại** → skill hỏi confirm rõ ràng trước khi overwrite. Khuyến nghị: dùng `/spec-test` qua integration changeset để preserve ID stable.
+
+---
+
+## Process
+
+### Bước 1: Xác định feature
+
+**Nếu có ARGUMENT:**
+- Parse argument: có thể là feature ID (`F-001`, `001`) hoặc slug (`F-001-auth`, `auth`)
+- Quét `specs/main/feature/*/frd.md`, tìm feature khớp
+- Nếu không tìm thấy → báo lỗi:
+  > Không tìm thấy feature khớp với "{argument}". Kiểm tra `specs/main/feature/`.
+
+**Nếu không có ARGUMENT:**
+
+Quét `specs/main/feature/`. Liệt kê **tất cả** features có `frd.md`, đánh dấu trạng thái tsd:
+
+```
+Features có frd.md:
+
+  [1] F-001 — auth                spec✓ tsd✓
+  [2] F-002 — checkout             spec✓ tsd—
+  [3] F-003 — refund               spec✓ tsd— (frd có 5 Flow, 12 US, 8 VR, 3 FAC)
+
+Chọn số feature:
+```
+
+Nếu không có feature nào có frd → thông báo:
+> Chưa có feature nào có frd.md. Hãy chạy `/spec-brownfield-feature` hoặc `/spec-new` trước.
+
+---
+
+### Bước 2: Gate check — frd.md tồn tại + warn nếu tsd.md đã có
+
+**Check 1 — frd.md tồn tại:**
+
+Nếu `specs/main/feature/{F-XXX}-{slug}/frd.md` không tồn tại → dừng:
+> ⛔ `feature/{F-XXX}-{slug}/frd.md` không tồn tại. `/spec-tsd` cần frd làm input.
+
+**Check 2 — tsd.md đã tồn tại:**
+
+Nếu `specs/main/feature/{F-XXX}-{slug}/tsd.md` đã tồn tại:
+
+> ⚠ `tsd.md` đã tồn tại cho feature **{F-XXX} — {slug}**.
+>
+> `/spec-tsd` regenerate IDs từ 001 — nếu có test code đang reference TC-{F_ID}-NNN hoặc TS-{F_ID}-NNN, references sẽ bị vỡ.
+>
+> Khuyến nghị: dùng `/spec-test` qua integration changeset để giữ ID stable.
+>
+> Tiếp tục overwrite? (yes / no — default no)
+
+Nếu user chọn no → dừng, suggest `/spec-test`.
+Nếu user chọn yes → backup tsd.md cũ thành `tsd.md.bak.{timestamp}` rồi proceed.
+
+---
+
+### Bước 3: Load context
+
+Load các file sau:
+
+- `specs/main/feature/{F-XXX}-{slug}/frd.md` — **bắt buộc**, source của TC
+- `specs/main/feature/{F-XXX}-{slug}/fdd.md` — optional, đọc nếu tồn tại để hint Components Used (cho Dependencies section của tsd)
+
+Tóm tắt context:
+
+```
+TÔI HIỂU:
+- Feature: {F-XXX} — {slug}
+- Trong frd.md:
+  - {N} Flows
+  - {M} User Stories ({K} Acceptance Criteria)
+  - {P} Verification Rules
+  - {Q} Feature Acceptance Criteria
+- tsd.md hiện tại: {chưa có / sẽ overwrite — backup tại tsd.md.bak.{timestamp}}
+- fdd.md: {tồn tại — Components Used: C-XXX, C-YYY / chưa có}
+```
+
+---
+
+### Bước 4: Auto-derive draft
+
+**Nguyên tắc:** mechanical derive 1:1 từ frd.md — same algorithm như `/spec-test` (xem [skills/spec-test/SKILL.md](../spec-test/SKILL.md) Bước 3.1-3.3). Tóm lại:
+
+#### 4.1 ID assignment
+
+- IDs bắt đầu từ `001` (vì tạo mới hoặc regenerate). TS và TC cùng feature ID `F{NNN}`, TC dùng chung sequence cho Functional / Validation / Feature AC.
+- ID sẽ stable kể từ thời điểm này — lần edit tiếp theo qua `/spec-test` integration phải preserve.
+
+#### 4.2 Derivation rules
+
+| frd item | tsd output |
+| --- | --- |
+| Mỗi `Flow {N}` trong User Flows | 1 Test Scenario `TS-F{NNN}-{seq}` |
+| Mỗi `AC-F{NNN}-{seq}` trong US | 1 Functional TC `TC-F{NNN}-{seq}` |
+| Mỗi `VR-F{NNN}-{seq}` | 1 positive + 1+ negative Validation TC |
+| Mỗi `FAC-F{NNN}-{seq}` | 1 Feature AC TC |
+
+Detail dịch G/W/T → Preconditions/Steps/Expected, infer negative VR branches từ rule text — xem `/spec-test` Bước 3.2.
+
+#### 4.3 Priority defaults
+
+| Source | Priority |
+| --- | --- |
+| TC cover US Must | P0 |
+| TC cover US Should | P1 |
+| TC cover US Could | P2 |
+| TC cover VR | inherit max priority của Refs (P1 default nếu Refs trống) |
+| TC cover FAC e2e | P0 |
+| TC cover FAC consistency | P1 |
+| TC cover FAC NFR security/data | P0 |
+| TC cover FAC NFR perf/a11y/i18n/browser | P1 |
+| TC cover FAC data & migration | P0 |
+
+#### 4.4 Traceability Matrix
+
+Row per frd item — Flow / US / Story AC / VR / FAC. Mọi item phải có cover ✅. Item không thể derive → ❌ + ghi lý do ở Gaps section.
+
+#### 4.5 Placeholders cần QC fill
+
+Agent **không suy đoán**:
+
+| Field | Placeholder |
+| --- | --- |
+| Environments table | Row mặc định `dev / staging / prod-like` với data set `TBD`, mục đích `TBD` |
+| Test Data table | Row `{TBD — fixture}` cho mỗi dataset thấy cần |
+| Out of Scope | Để trống với note `<!-- QC fill -->` |
+| Test Strategy > Approach | Bullet generic theo template gốc |
+| Overview | 2-3 câu mô tả feature scope từ frd Overview |
+
+#### 4.6 Dependencies section
+
+- **FRD reference**: path tới `frd.md` của feature này
+- **Components Used**: copy từ `frd.md > Components Used`. Nếu fdd.md tồn tại → cross-reference C-XXX để đảm bảo đúng.
+
+---
+
+### Bước 5: Review — xác nhận với QC
+
+Hiển thị draft đầy đủ — chưa ghi file.
+
+> Draft tsd.md trên đã đúng chưa? Check:
+>
+> 1. **Coverage** — Traceability Matrix có đủ row cho mỗi Flow / US / AC / VR / FAC trong frd?
+> 2. **Priority** — defaults theo bảng 4.3, có TC nào cần override?
+> 3. **Placeholders** — fill Environments / Test Data / Out of Scope / Strategy Approach.
+> 4. **Extra edge cases** — ngoài AC/VR có scenario QC muốn thêm?
+>
+> Confirm để ghi file. Reject để revise.
+
+---
+
+### Bước 6: Save
+
+Ghi `specs/main/feature/{F-XXX}-{slug}/tsd.md` với status `draft` (feature-level artifact có lifecycle riêng, không phải `approved` — QC còn fill placeholders nên status `draft` cho đến khi đầy đủ).
+
+Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
+
+Thông báo kết quả:
+
+```
+✓ specs/main/feature/{F-XXX}-{slug}/tsd.md đã được tạo (status: draft)
+  Coverage: N Flows → N TS, M US/AC → M Functional TC, P VR → ~2P Validation TC, Q FAC → Q Feature AC TC
+  {nếu overwrite: backup tại tsd.md.bak.{timestamp}}
+
+Bước tiếp theo:
+  - QC: fill remaining placeholders (Environments, Test Data, Out of Scope, Strategy)
+  - Đổi status: draft → approved khi sẵn sàng
+  - Sau này: nếu frd thay đổi → dùng /spec-test qua integration changeset để giữ ID stable
+```
+
+---
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+| --- | --- |
+| "Có frd rồi, viết tsd sau cũng được" | Test coverage không tracked = không biết feature đóng được chưa. tsd làm song song với frd, không sau. |
+| "Rebuild tsd nhanh hơn cập nhật manual" | Đúng cho lần đầu. Lần sau khi đã có test code reference → rebuild sẽ break references. Lúc đó dùng `/spec-test`. |
+| "Brownfield không cần tsd, đã có test code" | Test code là HOW. tsd là WHAT — declarative TC list để track coverage vs frd. Hai layer khác nhau. |
+
+## Red Flags
+
+- Traceability Matrix có ❌ mà không có Gaps section giải thích
+- Priority hàng loạt P1 — chưa override theo defaults
+- Test Strategy / Test Data toàn `TBD` sau khi QC review xong
+- Overwrite tsd.md hiện có mà không cảnh báo về ID break
+
+## Verification
+
+Trước khi ghi file:
+
+- [ ] Mỗi Flow trong frd có 1 TS
+- [ ] Mỗi US AC có TC Functional cover
+- [ ] Mỗi VR có ≥1 positive + ≥1 negative TC
+- [ ] Mỗi FAC có TC Feature AC cover
+- [ ] Priority deterministic theo bảng 4.3
+- [ ] Nếu overwrite: tsd.md.bak.{timestamp} đã được tạo
+- [ ] QC đã confirm draft