khangpqvn 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-specdù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. 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.
- Đọc profile trước Context và Constitution.
SPEC.mdchỉ 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.mddừ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:
- Business logic gaps — Rule nào chưa xác định rõ?
- Constraint kỹ thuật thiếu — NFR nào chưa có giá trị cụ thể?
- 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, 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 — kế thừa và áp dụng
Depth dùng đúng một trong SKIP | SKETCH | DETAILED | FORMAL theo Methodology Profile:
| Level | Dùng khi | Output tối thiểu |
|---|---|---|
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. |
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
| # | 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> - 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>
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:
- Pre-mortem: giả định feature đã gây incident; nêu failure scenario, impact và rule/evidence cần bổ sung.
- Domain walkthrough: xem normal flow, error flow, boundary/state transition, actor/authorization, duplicate/concurrency và data lifecycle khi applicable.
- 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:
- 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.
Các bước
- Đọc Context, Describe-back, Methodology Profile và Constitution.
- Chạy Clarification-First; chờ Human reviewer có thẩm quyền xác nhận trước bước tiếp theo.
- Áp dụng depth đã chọn và high-risk review route.
- Ghi SemVer và
Status: DRAFT. - Viết Spec theo depth; Functional Requirement dùng EARS.
- Chạy adversarial quality pass và ghi disposition.
- Ghi Feature Lock và deferred work.
- Kiểm tra DoD, cập nhật changelog và tạo recommendation.
DoD
- 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.
- Depth được áp dụng theo contract;
SKIPcó 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-updatepath. - SemVer/changelog đúng và Human Final Review đã
APPROVEDtrước lock.
AI Recommendation và Human Final Review
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.