git:20260824.63449ef to git:20260824.a9d95f4

58 added, 15 removed. Audit A to A.

---

name: sdd-update

- description: Cập nhật SPEC.md, bump SemVer, ghi changelog và đồng bộ downstream artifact theo profile

+ description: Cập nhật SPEC.md của feature — bump SemVer, thêm/sửa requirement, invalidate review cũ và chuẩn bị recommendation mới

user-invocable: true

---

- # SDD Feature Update và SemVer Bump (`/sdd-update`)

+ # SDD Spec Update (`/sdd-update`)

- Dùng khi cập nhật business requirement, xử lý Spec gap hoặc đổi behavior trong `.sdd/features/{feature-slug}/SPEC.md`.

+ **Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`PENDING HUMAN REVIEW`, `APPROVED`, `APPROVED & LOCKED`, `DRAFT`), EARS keywords, `REQ-XXX` identifiers, SemVer, file paths, and CLI commands are language-invariant.

+ Dùng khi cần sửa `SPEC.md` sau khi đã lock — thêm requirement mới, làm rõ edge case, sửa behavior hoặc đổi contract. Skill invalidate review cũ, bump SemVer và tạo recommendation mới để Human Director review lại trước khi execute.

## Tham số

- - `--feature=<feature-slug>`: Bắt buộc; feature cần cập nhật.

- - `--bump=<major|minor|patch>`: Bắt buộc; mức SemVer.

- - `--reason="<lý-do>"`: Bắt buộc; tóm tắt lý do trong changelog.

- - `--req="<EARS requirement>"`: Tùy chọn; requirement mới/điều chỉnh.

+ - `--feature=<feature-slug>`: Feature identifier. Bắt buộc.

+ - `--bump=<patch|minor|major>`: Loại thay đổi SemVer. Bắt buộc.

+ - `--reason=<mô-tả>`: Lý do cập nhật. Bắt buộc.

- ## Các bước

+ ## Chọn bump đúng

- 1. Đọc Spec, version, status và `REQ-XXX` hiện có.

- 2. Tính version mới: `patch` cho làm rõ/sửa tương thích, `minor` cho behavior tương thích mới, `major` cho breaking contract.

- 3. Đặt `SPEC.md` thành `DRAFT`, `Human Final Review: PENDING`; không giữ lock cũ.

- 4. Cập nhật EARS requirement, BDD, error, acceptance, Out of Scope và changelog.

- 5. Đọc Architecture Profile. Nếu thay đổi cần transport, persistence, validation, cache, messaging hay tooling mới, tạo profile recommendation và invalidate Plan/Tasks cũ.

- 6. Chỉ đề xuất execution khi binding/command cần thiết đã `APPROVED` và có evidence; binding unresolved thì dừng ở `PENDING HUMAN REVIEW`.

+ | Loại thay đổi | Bump |

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

+ | Làm rõ behavior đã có, thêm error case, clarify edge case không phá contract | `patch` |

+ | Thêm behavior tương thích ngược, thêm optional flow hoặc NFR mới | `minor` |

+ | Thay đổi API, DB schema, data contract hoặc behavior không tương thích ngược | `major` |

+ `--bump=major` bắt buộc phải ghi migration plan, rollback plan và risk trong Spec trước khi Agent được execute downstream.

+ ## Architecture Profile preflight

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

+ - Đọc profile và governance trước khi sửa Spec.

+ - Requirement bổ sung technology-neutral; không sinh ORM decorator, HTTP route, framework schema hoặc command chưa approved.

+ - Binding chưa resolve vẫn được phép trong Spec nhưng phải là `PLAN.md` planning blocker.

+ ## Quy trình

+ 1. Đọc `SPEC.md` hiện tại, `CONTEXT.md`, `CONSTITUTION.md` và Architecture Profile.

+ 2. Đặt header Spec về `Status: DRAFT` nếu đang ở `APPROVED & LOCKED`.

+ 3. Thêm/sửa requirement theo EARS; cập nhật BDD, error behavior, acceptance và Out of Scope liên quan.

+ 4. Bump version theo SemVer và ghi changelog entry:

+ ```markdown

+ ### vX.Y.Z (YYYY-MM-DD)

+ - <reason>: <mô tả thay đổi>

+ ```

+ 5. Invalidate recommendation cũ: đặt `AI Agent Recommendation.Status` về `PENDING HUMAN REVIEW` với changed scope làm evidence.

+ 6. Tạo recommendation mới gồm requirement gap, EARS risk, edge case, Out of Scope impact và SemVer impact.

+ 7. Xác định artifact bị ảnh hưởng: `PLAN.md`, `TASKS.md`, `@ears` trong `src/`, test liên quan.

+ ## DoD

+ - [ ] SemVer bumped đúng loại thay đổi.

+ - [ ] Mọi requirement mới/sửa dùng EARS.

+ - [ ] Changelog entry ghi rõ.

+ - [ ] `Status: DRAFT` — không còn `APPROVED & LOCKED`.

+ - [ ] Recommendation mới ở `PENDING HUMAN REVIEW`.

+ - [ ] Artifact bị ảnh hưởng đã được liệt kê.

## AI Recommendation và Human Final Review

- Sau khi đề xuất hoặc áp dụng Spec update, lưu canonical recommendation trong `SPEC.md`, gồm thay đổi, SemVer impact, requirement bị ảnh hưởng, migration risk và downstream file. `/add-execute` hoặc task breakdown mới bị block đến khi Human Director approve. Mọi sửa tiếp theo làm review cũ mất hiệu lực; Agent không self-approve changed contract.

+ Sau khi cập nhật `SPEC.md`, tạo canonical recommendation từ `.claude/skills/_shared/ai-review-protocol.md`, gồm requirement thay đổi, artifact bị ảnh hưởng, EARS/SemVer risk, edge case và downstream impact. Giữ `Human Final Review.Status: PENDING`; `/sdd-plan`, `/sdd-tasks` và `/add-execute` bị block đến khi Human Director ghi `APPROVED` và lock lại. Agent không tự approve Spec đã sửa.

+ ## Ví dụ

+ ```text

+ /sdd-update --feature=feat-user-register --bump=patch --reason="Add OTP rate-limit behavior"

+ /sdd-update --feature=feat-user-register --bump=minor --reason="Add optional recovery flow"

+ /sdd-update --feature=feat-user-register --bump=major --reason="Change registration contract"

+ ```

+ Sau khi Human Director approve và lock Spec mới, nếu Plan/Tasks bị ảnh hưởng thì phải chạy lại `/sdd-plan` hoặc cập nhật `TASKS.md` trước khi `/add-execute`.