git:20260831.c10e62e to git:20260906.b53a8e9

55 added, 49 removed. Audit A to A.

---

name: sdd-spec

description: Pha 1 SDD — tạo SPEC.md với EARS, SemVer, BDD, error contract và DoD

user-invocable: true

---

# SDD Phase 1 — Specification (`/sdd-spec`)

**Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`PENDING HUMAN REVIEW`, `PENDING`, `APPROVED`, `APPROVED & LOCKED`, `DRAFT`), EARS keywords (`WHEN`, `WHILE`, `WHERE`, `IF`, `THEN`, `SHALL`), file paths, and CLI commands are language-invariant.

Dùng `CONTEXT.md` và `CONSTITUTION.md` để tạo `.sdd/features/{feature-slug}/SPEC.md`.

## Tham số

- `--feature=<feature-slug>`: Feature identifier.

> **Cập nhật Spec đã `APPROVED & LOCKED`?** Dùng `/sdd-update --artifact=spec --bump=<patch|minor|major>` thay vì chạy lại skill này. `/sdd-spec` dùng để tạo Spec lần đầu hoặc làm lại khi context thay đổi lớn.

## Shared methodology contract

- Đọc [AI Review Protocol](../_shared/ai-review-protocol.md). Kế thừa `Intent Packet` và `Methodology Profile` từ Context, ghi depth/rationale/risk posture trong Spec header, và bổ sung `High-risk review route` khi applicable. Methodology metadata không chọn technology hoặc bypass Architecture Profile gate.

+ Đọc [AI Review Protocol](../_shared/ai-review-protocol.md). Kế thừa `Intent Packet`, `Describe-back record` và `Methodology Profile` từ Context. Ghi depth/rationale/risk posture trong Spec header; không tự đổi level đã được chọn. Methodology metadata không chọn technology hoặc bypass Architecture Profile gate.

## Architecture Profile preflight

Tuân thủ [Architecture Profile Protocol](../_shared/architecture-profile-protocol.md).

- Đọc profile trước Context và Constitution.

- `SPEC.md` chỉ mô tả behavior, data contract, error và NFR; không sinh ORM decorator, framework schema, package hoặc CLI command chưa approved.

- Ghi profile version và binding feature cần dùng.

- - Binding chưa resolve được phép trong Spec nhưng phải là planning blocker; `PLAN.md` dừng đến khi Human Director approve.

+ - Binding chưa resolve được phép trong Spec nhưng phải là planning blocker; `PLAN.md` dừng đến khi Human reviewer có thẩm quyền approve.

## Clarification-First — bắt buộc trước khi viết requirement

Trước khi draft requirement, AI phải liệt kê điểm chưa chắc chắn từ `CONTEXT.md` theo 3 loại:

- 1. **Business logic gaps** — Rule nào chưa xác định rõ? (ví dụ: "duplicate handling thế nào khi user submit hai lần?")

- 2. **Constraint kỹ thuật thiếu** — NFR nào chưa có giá trị cụ thể? (ví dụ: timeout, rate limit, response time)

- 3. **Edge case chưa đề cập** — Tình huống hiếm nhưng quan trọng? (ví dụ: "concurrent request từ cùng user?")

+ 1. **Business logic gaps** — Rule nào chưa xác định rõ?

+ 2. **Constraint kỹ thuật thiếu** — NFR nào chưa có giá trị cụ thể?

+ 3. **Edge case chưa đề cập** — Tình huống hiếm nhưng quan trọng?

- Với mỗi điểm, nêu: điều chưa chắc là gì — assumption sẽ dùng nếu phải chọn — ảnh hưởng của assumption đó. **Dừng và chờ Human Director confirm trước khi viết requirement.** Nếu được phép tiếp tục với assumption, ghi rõ assumption đó vào Spec.

+ Với mỗi điểm, nêu điều chưa chắc, assumption sẽ dùng nếu phải chọn và ảnh hưởng của assumption. **Dừng và chờ Human reviewer có thẩm quyền confirm trước khi viết requirement.** Nếu được phép tiếp tục với assumption, ghi rõ assumption đó vào Spec.

- ## Spec Depth — chọn mức phù hợp trước khi viết

+ ## Spec Depth — kế thừa và áp dụng

- Dùng Risk × Complexity Matrix:

+ `Depth` dùng đúng một trong `SKIP | SKETCH | DETAILED | FORMAL` theo Methodology Profile:

- | | Complexity Thấp | Complexity Cao |

+ | Level | Dùng khi | Output tối thiểu |

| :--- | :--- | :--- |

- | **Risk Thấp** | **Sketch** — Functional Req + Acceptance Criteria | **Detailed** — Đủ 8 thành phần |

- | **Risk Cao** | **Detailed** — Đủ 8 thành phần | **Formal** — 8 thành phần + State Diagram + formal verification |

- - **Sketch**: CRUD đơn giản, không auth, không money, không PII. 3–5 requirement là đủ.

- - **Detailed**: Feature có auth, payment, state machine, concurrent access, third-party.

- - **Formal**: Core business logic, compliance-critical, data migration, irreversible operation.

+ | `SKIP` | Scope đã được Human chấp nhận là exploratory/throwaway hoặc không thêm behavior/contract material | Lý do, evidence, boundary và decision; không dùng để né review. |

+ | `SKETCH` | Logic/risk thấp, phạm vi nhỏ | Requirement, acceptance, out-of-scope và clarification cho ambiguity. |

+ | `DETAILED` | Mặc định cho integration, authorization, concurrency, third-party hoặc risk đáng kể | Đủ tám thành phần Spec. |

+ | `FORMAL` | Money, compliance, destructive/irreversible work, migration, security/authorization, core business state hoặc external contract | Detailed cộng state/transition, invariant và adversarial review. |

- Nêu depth và rationale trong `Methodology Profile`. `High-risk review route` bắt buộc cho sensitive data, financial/business-critical behavior, destructive/irreversible work, compliance, authorization, cross-system consistency hoặc public/external contract. Không tự chỉ định người review; ghi route và decision owner theo Context.

+ Không level nào bỏ Human review, Feature Lock, Architecture Profile evidence, exact approved command hoặc material checkpoint. `FORMAL` không tự tạo formal-verification tooling khi chưa có binding/evidence.

## 8 Thành phần Spec bắt buộc

- Thiếu thành phần nào tạo "lỗ hổng context" — AI tự lấp bằng assumption không kiểm soát.

- | :--- | :--- | :--- | :--- |

+ | # | Thành phần | Câu hỏi phải trả lời |

+ | :--- | :--- | :--- |

+ | 1 | **Context & Goal** | Tại sao feature tồn tại? |

+ | 2 | **Actors & Roles** | Ai tương tác? Với quyền gì? |

+ | 3 | **Functional Requirements** | Hệ thống làm gì? (EARS) |

+ | 4 | **Non-functional Requirements** | Tốt đến mức nào? |

+ | 5 | **Data Model** | Dữ liệu có cấu trúc gì? |

+ | 6 | **Error Handling** | Khi sai thì làm gì? |

+ | 7 | **Acceptance Criteria** | Định nghĩa xong là gì? |

+ | 8 | **Out of Scope** | Hệ thống không làm gì? |

## EARS Notation — 5 patterns

Mọi Functional Requirement phải thuộc đúng một pattern:

- - **Ubiquitous**: `The <system> SHALL <action>` — rule luôn đúng, không cần trigger

- - **Event-driven**: `WHEN <trigger>, the <system> SHALL <action>` — phản ứng sự kiện

- - **State-driven**: `WHILE <in state>, the <system> SHALL <action>` — hành vi trong trạng thái

- - **Optional**: `WHERE <feature is included>, the <system> SHALL <action>` — feature flag

- - **Unwanted**: `IF <invalid/error condition>, THEN the <system> SHALL <action>` — error path

+ - **Ubiquitous**: `The <system> SHALL <action>`

+ - **Event-driven**: `WHEN <trigger>, the <system> SHALL <action>`

+ - **State-driven**: `WHILE <in state>, the <system> SHALL <action>`

+ - **Optional**: `WHERE <feature is included>, the <system> SHALL <action>`

+ - **Unwanted**: `IF <invalid/error condition>, THEN the <system> SHALL <action>`

- Quy tắc: mỗi happy path (`WHEN`) cần ít nhất một `IF ... THEN ...` cho error tương ứng. Tránh từ mơ hồ: "nhanh chóng", "giao diện đẹp", "xử lý linh hoạt", "nếu cần thiết". Mọi NFR phải có giá trị đo được.

+ Mỗi happy path (`WHEN`) cần ít nhất một `IF ... THEN ...` cho error tương ứng. Tránh từ mơ hồ; mọi NFR phải có giá trị đo được.

+ ## Adversarial quality pass

+ Trước recommendation, thực hiện và ghi disposition cho mọi finding:

+ 1. **Pre-mortem:** giả định feature đã gây incident; nêu failure scenario, impact và rule/evidence cần bổ sung.

+ 2. **Domain walkthrough:** xem normal flow, error flow, boundary/state transition, actor/authorization, duplicate/concurrency và data lifecycle khi applicable.

+ 3. Mỗi finding phải thành một trong: clarified rule, approved assumption, deferred item hoặc blocking Human decision.

+ Pass này không thay Human review và không cho phép Agent tự bù rule thiếu bằng assumption không được ghi nhận.

## Feature Lock

`SPEC.md` phải có `## Feature Lock` trước recommendation:

```markdown

- Locked scope: <behavior and contract in this feature or sprint>

- Deferred work: <explicitly excluded future work>

- Change path: /sdd-update --feature=<slug> --artifact=spec --bump=<...> --reason="..."

- Lock boundary: Feature/sprint only; this does not lock unrelated project work.

```

- Sau `APPROVED & LOCKED`, behavior hoặc contract chỉ thay đổi qua `/sdd-update`. Deferred work không được implement ngầm như cleanup hoặc extension.

+ Sau `APPROVED & LOCKED`, behavior hoặc contract chỉ thay đổi qua `/sdd-update`.

## Các bước

- 1. Đọc Context, Methodology Profile và Constitution.

- 2. Chạy Clarification-First; chờ Human Director xác nhận trước bước tiếp theo.

- 3. Xác định Spec Depth phù hợp (Sketch/Detailed/Formal) và high-risk review route.

+ 1. Đọc Context, Describe-back, Methodology Profile và Constitution.

+ 2. Chạy Clarification-First; chờ Human reviewer có thẩm quyền xác nhận trước bước tiếp theo.

+ 3. Áp dụng depth đã chọn và high-risk review route.

4. Ghi SemVer và `Status: DRAFT`.

- 5. Viết đủ 8 thành phần theo depth đã chọn; Functional Requirement dùng EARS.

- 6. Ghi Feature Lock và deferred work.

- 7. Kiểm tra DoD, cập nhật changelog và tạo recommendation.

+ 5. Viết Spec theo depth; Functional Requirement dùng EARS.

+ 6. Chạy adversarial quality pass và ghi disposition.

+ 7. Ghi Feature Lock và deferred work.

+ 8. Kiểm tra DoD, cập nhật changelog và tạo recommendation.

## DoD

- - [ ] Đã chạy Clarification-First; assumption được ghi rõ hoặc đã Human confirm.

+ - [ ] Describe-back/Clarification-First không còn contradiction hoặc material question không disposition.

- [ ] Methodology Profile có depth, rationale, risk posture, review route khi high-risk và decision owner.

- - [ ] Có đủ 8 thành phần: Context, Actors, Functional, NFR, Data, Error, Acceptance, Out of Scope.

- - [ ] Mọi Functional Requirement dùng đúng EARS pattern.

- - [ ] Mỗi happy path có ít nhất một Unwanted EARS tương ứng.

- - [ ] Không có từ mơ hồ; NFR có giá trị cụ thể đo được.

- - [ ] Open question quan trọng đã resolve hoặc nêu rõ với assumption.

- - [ ] Feature Lock ghi locked scope, deferred work và `/sdd-update` path; không lock toàn dự án.

+ - [ ] Depth được áp dụng theo contract; `SKIP` có Human-accepted rationale/evidence.

+ - [ ] Có đủ tám thành phần phù hợp với depth; mọi Functional Requirement dùng EARS.

+ - [ ] Mỗi happy path có ít nhất một Unwanted EARS tương ứng; NFR đo được.

+ - [ ] Adversarial pre-mortem và domain walkthrough đã ghi; finding có disposition.

+ - [ ] Feature Lock ghi locked scope, deferred work và `/sdd-update` path.

- [ ] SemVer/changelog đúng và Human Final Review đã `APPROVED` trước lock.

## AI Recommendation và Human Final Review

- Sau khi tạo/sửa `SPEC.md`, lưu canonical recommendation trong artifact, gồm Methodology Profile, requirement gap, EARS risk, high-risk review route, edge case, Out of Scope, Feature Lock và SemVer impact. Giữ `Human Final Review.Status: PENDING`; `/sdd-plan` bị block đến khi Human Director ghi `APPROVED`. Agent không được đặt `APPROVED & LOCKED` thay con người.

+ Sau khi tạo/sửa `SPEC.md`, lưu canonical recommendation gồm Methodology Profile, requirement gap, EARS risk, adversarial findings/disposition, high-risk review route, edge case, Out of Scope, Feature Lock và SemVer impact. Giữ `Human Final Review.Status: PENDING`; `/sdd-plan` bị block đến khi Human reviewer có thẩm quyền ghi `APPROVED`. Agent không được đặt `APPROVED & LOCKED` thay con người.