spec-lite 1.5.1 → 1.6.0

package/skills/spec-tsd/SKILL.md

@@ -1,241 +0,0 @@
----
-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 đủ). Frontmatter lấy `template_version` từ `tsd-template.md` (xem `conventions.md` §7).
-
-Nếu overwrite — file backup `tsd.md.bak.{timestamp}` đã tạo ở Bước 2.
-
-**Change History:** Append entry vào section `## Change History` cuối tsd.md (theo `conventions.md` §5.5):
-
-```markdown
-### {YYYY-MM-DD} — manual — create
-
-- **All sections**: initial scaffold qua /spec-tsd (mechanical derive từ frd.md — N TS, M Functional TC, P Validation TC, Q Feature AC TC)
-```
-
-Nếu overwrite tsd.md cũ → entry vẫn dùng operation `create` (vì IDs regenerate fresh, không phải update), thêm note trong body: `- **Note**: overwrote previous tsd.md (backup tại tsd.md.bak.{timestamp}) — IDs regenerated từ 001`.
-
-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
-- [ ] Frontmatter có `template_version` copy từ `tsd-template.md`