spec-lite 1.5.2 → 1.7.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`

package/templates/main/feature/tsd-template.md

@@ -1,238 +0,0 @@
----
-id: tsd-{feature}
-type: tsd
-status: draft
-owner: "{QC}"
-feature_id: "{Feature ID — match frd.md}"
-frd_ref: "feature/{F-XXX}-{slug}/frd.md"
-template_version: 1
-migrations:
-  - to: 1
-    note: "baseline"
-referenced_by:
-  - conventions.md > 3. Main Artifacts > 3.3 Feature level > tsd.md > Cấu trúc
----
-
-<!--
-Canonical format cho feature/{F-XXX}-{slug}/tsd.md.
-Sinh từ frd.md — mỗi AC / VR / Flow phải có ít nhất 1 test case cover.
-Traceability Matrix ở cuối là source of truth để kiểm tra coverage trước khi đóng feature.
-
-TSD chỉ tồn tại ở FEATURE level — không tách tsd riêng cho component.
-Component là internal building block; contract của component được verify gián tiếp qua TC ở đây
-và qua unit test trong code (không phải spec artifact).
--->
-
-# Test Spec: {Feature Name}
-
-## Overview
-
-{Phạm vi tsd này — feature gì, các luồng / AC / VR chính cần verify, trong 2-3 câu.}
-
-## Test Strategy
-
-### Approach
-
-- **Functional**: verify từng US / Story AC theo happy + edge.
-- **Validation**: derive 1:1 từ Verification Rules.
-- **Flow-based (E2E)**: chạy theo Mermaid flows trong frd.
-- **Feature AC**: cover các Feature AC — e2e liên story, cross-story consistency, NFR, data & migration.
-
-### Environments
-
-| Env | Mục đích | Data set | Ghi chú |
-| --- | --- | --- | --- |
-| {dev / staging / prod-like} | {functional / E2E / load} | {seed / anonymized prod} | ... |
-
-## Test Scenarios
-
-Mỗi scenario gắn với 1 flow trong `frd.md > User Flows`. Scenario mô tả end-to-end path; test case chi tiết liệt kê ở section bên dưới.
-
-TS ID format: `TS-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** — đã assign rồi giữ nguyên kể cả khi xóa (không tái sử dụng seq, không renumber).
-
-### TS-{F_ID}-001: {Tên — match Flow 1 trong frd}
-
-- **Flow ref:** `frd.md > Flow 1: {tên}`
-- **Preconditions:** {state trước khi chạy}
-- **Postconditions:** {state sau khi pass}
-- **Paths:**
-  - Happy: A → B → C(happy) → D → F
-  - Edge: A → B → C(edge) → E → G
-- **Test cases:** `TC-{F_ID}-001`, `TC-{F_ID}-002`, ...
-
----
-
-### TS-{F_ID}-002: {Tên — match Flow 2 nếu có}
-
-...
-
-## Functional Test Cases
-
-Cover User Stories và Acceptance Criteria trong frd.
-
-TC ID format: `TC-F{NNN}-{seq}` — đánh số tăng dần toàn feature. ID **stable** (không tái sử dụng seq khi xóa, không renumber). Nếu xóa TC → ID đó retire, seq mới tiếp tục tăng từ max.
-
-### TC-{F_ID}-001: {Title ngắn — verb-first}
-
-| Field | Value |
-| --- | --- |
-| **Type** | Functional — positive / negative |
-| **Priority** | P0 / P1 / P2 |
-| **Covers** | `US-{F_ID}-001`, `AC-{F_ID}-001` |
-| **Scenario** | `TS-{F_ID}-001` |
-| **Preconditions** | ... |
-
-**Steps:**
-
-1. {action}
-2. {action}
-3. {action}
-
-**Expected:**
-
-- {observable outcome 1}
-- {observable outcome 2}
-
-**Test data:** {ref Test Data section hoặc inline literal}
-
----
-
-### TC-{F_ID}-002: ...
-
-## Validation Test Cases
-
-Derive 1:1 từ Verification Rules trong frd. Mỗi `VR-F{NNN}-{seq}` cần ít nhất:
-- 1 positive (rule pass)
-- 1+ negative — mỗi nhánh fail là 1 case riêng (vd VR "email format" → 1 case cho missing `@`, 1 case cho missing domain, ...)
-
-Form bảng để dễ scan; case phức tạp có thể tách ra block riêng như Functional TC.
-
-| TC ID | Covers VR | Field | Input | Expected | Polarity |
-| --- | --- | --- | --- | --- | --- |
-| `TC-{F_ID}-010` | `VR-{F_ID}-001` | `email` | `"user@example.com"` | accept | positive |
-| `TC-{F_ID}-011` | `VR-{F_ID}-001` | `email` | `""` | reject — required | negative |
-| `TC-{F_ID}-012` | `VR-{F_ID}-001` | `email` | `"abc"` | reject — invalid format | negative |
-
-## Feature AC Test Cases
-
-Cover Feature Acceptance Criteria (`FAC-*`) trong frd. Feature AC trong frd đã ở format G/W/T → TC ở đây dịch 1:1: Given → Preconditions, When → Steps, Then → Expected.
-
-### TC-{F_ID}-040: {Title — e2e liên story}
-
-| Field | Value |
-| --- | --- |
-| **Type** | Feature AC — e2e |
-| **Priority** | P0 / P1 / P2 |
-| **Covers** | `FAC-{F_ID}-001` |
-| **Spans** | `US-{F_ID}-001`, `US-{F_ID}-002`, `US-{F_ID}-003` |
-| **Preconditions** | account mới chưa onboard |
-
-**Steps:**
-
-1. Đăng ký account mới
-2. Verify email qua link
-3. Hoàn thành onboarding form
-4. Thực hiện first transaction
-
-**Expected:**
-
-- Toàn bộ flow chạy trong 1 session, không cần support intervene
-- State persist đúng giữa các step (refresh không mất tiến độ)
-
----
-
-### TC-{F_ID}-041: {Title — consistency}
-
-| Field | Value |
-| --- | --- |
-| **Type** | Feature AC — consistency |
-| **Priority** | P1 |
-| **Covers** | `FAC-{F_ID}-002` |
-| **Preconditions** | feature đã deploy lên test env, 3 màn Register / Profile / Admin Create accessible |
-
-**Steps:**
-
-1. Trigger empty `email` validation ở Register
-2. Trigger empty `email` validation ở Profile
-3. Trigger empty `email` validation ở Admin Create
-4. Trigger invalid format `"abc"` ở cả 3 màn
-
-**Expected:**
-
-- 3 message ở step 1-3 identical (cùng text, cùng style)
-- 3 message ở step 4 identical
-
----
-
-### TC-{F_ID}-050: {Title — NFR perf}
-
-| Field | Value |
-| --- | --- |
-| **Type** | Feature AC — performance |
-| **Priority** | P0 |
-| **Covers** | `FAC-{F_ID}-003` |
-| **Preconditions** | env perf-test, dataset baseline đã load |
-
-**Steps:**
-
-1. Chạy load test (k6 / JMeter) profile 100 RPS sustained 5 phút lên `/login`
-2. Đọc p95 latency từ summary report
-
-**Expected:**
-
-- p95 ≤ 500ms
-- Error rate ≤ 0.1%
-
-## Test Data
-
-| Data set | Mục đích | Nguồn | Refresh |
-| --- | --- | --- | --- |
-| `seed_users` | functional positive | fixture / factory | mỗi run |
-| `boundary_inputs` | validation edges | inline trong TC | n/a |
-
-## Traceability Matrix
-
-**Source of truth** để verify coverage trước khi đóng feature. Mỗi item từ frd phải xuất hiện. Gap → đánh ❌ và mô tả rõ ở phần "Gaps" bên dưới.
-
-| FRD Item | Type | Covered by | Status |
-| --- | --- | --- | --- |
-| Flow 1 | Flow | `TS-{F_ID}-001` | ✅ |
-| `US-{F_ID}-001` | US | `TC-{F_ID}-001`, `TC-{F_ID}-002` | ✅ |
-| `AC-{F_ID}-001` | Story AC | `TC-{F_ID}-001` | ✅ |
-| `VR-{F_ID}-001` | VR | `TC-{F_ID}-010`, `TC-{F_ID}-011`, `TC-{F_ID}-012` | ✅ |
-| `FAC-{F_ID}-001` | Feature AC | `TC-{F_ID}-040` | ✅ |
-| `FAC-{F_ID}-002` | Feature AC | `TC-{F_ID}-041` | ✅ |
-| `FAC-{F_ID}-003` | Feature AC | `TC-{F_ID}-050` | ✅ |
-| `AC-{F_ID}-00X` | Story AC | — | ❌ chưa có TC |
-
-### Gaps
-
-{Liệt kê item ❌ kèm lý do tạm hoãn / blocker — empty nếu coverage đầy đủ.}
-
-## Out of Scope
-
-- {những gì tsd này KHÔNG cover — lý do (vd: thuộc layer khác như infra/security audit, đã verify ở môi trường khác, ...)}
-
-## Dependencies
-
-### FRD reference
-
-- `frd.md` của feature này — mọi ID (`US-`, `AC-`, `VR-`, Flow) phải match.
-
-### Components Used (input only)
-
-Tham chiếu `frd.md > Components Used` để hiểu contract của các component được feature này dùng. Behavior của component được verify **gián tiếp** qua các TC ở đây — không tách tsd riêng cho component.
-
-## Change History
-
-Append-only log của các thay đổi cascade lên artifact này. Quy ước xem `conventions.md` §5.5.
-
-<!-- Entry format:
-### YYYY-MM-DD — [{id}-{slug}](../../../integrations/{id}-{slug}/test.md) — create|update|manual
-
-- **{Section name}**:
-  - [NEW] {item} — {mô tả ngắn}
-  - [MODIFY {field}] {item} — {old → new}
-  - [REMOVE] {item} — {lý do}
--->
-