Sdd Update

SDD Artifact Update (/sdd-update)

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 artifact SDD đã approved mà không sinh lại từ đầu.

Khi nào dùng skill này

Tham số

• --feature=<feature-slug>: Feature identifier. Bắt buộc.
• --artifact=<spec|context|plan|tasks>: Artifact cần cập nhật. Mặc định: spec.
• --bump=<patch|minor|major>: Loại thay đổi SemVer. Bắt buộc khi --artifact=spec.
• --reason=<mô-tả>: Lý do cập nhật. Bắt buộc. Khuyến khích gắn REQ-XXX khi áp dụng, ví dụ "[REQ-003] Add OTP rate-limit: max 5 attempts per 10 minutes".

Chọn bump đúng (chỉ áp dụng cho --artifact=spec)

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

Shared methodology contract

Đọc AI Review Protocol. Mọi update phải thêm ## Change Impact Record trước recommendation:

## Change Impact Record
- Changed intent, requirement, architecture, or task assumption: <what changed>
- Feature Lock boundary affected: <locked scope/deferred work/no change>
- Material state-change classification: <none or category list>
- Downstream artifacts invalidated: <Context/Spec/Plan/Tasks/code/tests/contracts>
- Required trace, test, and sync actions: </sdd-trace, exact command, /sdd-sync or N/A>
- Review follow-up: <review route and approval required>

Không dùng Context-only update để che behavior change. Nếu Context thay đổi intent, actor, boundary, constraint hoặc risk, record phải quyết định rõ Spec revision required: yes | no và evidence. Spec update phải đánh giá Plan/Tasks trước resume.

Architecture Profile preflight

Tuân thủ Architecture Profile Protocol.

• Đọc profile và governance trước khi sửa artifact.
• Requirement bổ sung phải 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.

Clarification-First — bắt buộc trước khi thêm requirement hoặc sửa behavior

Trước khi viết thay đổi, liệt kê điểm chưa chắc chắn theo 3 loại:

1. Business logic gaps — Rule mới/sửa có assumption nào chưa được xác nhận?
2. Constraint kỹ thuật — NFR thêm vào có giá trị đo được chưa? (timeout, rate limit, threshold)
3. Edge case chưa xử lý — Thay đổi này ảnh hưởng tình huống nào đang có trong Spec?

Dừng và chờ Human reviewer có thẩm quyền confirm trước khi ghi thay đổi. Nếu được phép tiếp tục với assumption, ghi rõ assumption đó trong artifact.

Quy trình

Khi --artifact=spec

1. Đọc SPEC.md hiện tại, CONTEXT.md, CONSTITUTION.md, Architecture Profile, Plan và Tasks nếu tồn tại.
2. Chạy Clarification-First; chờ confirm.
3. Đặt header Spec về Status: DRAFT nếu đang ở APPROVED & LOCKED.
4. Thêm/sửa requirement theo EARS; cập nhật BDD, error behavior, acceptance, Out of Scope và Feature Lock liên quan.
5. Bump version theo SemVer và ghi changelog entry.
6. Đánh giá Plan/Tasks, @ears trong src/, tests và shared contract bị invalidated trước khi cho phép resume.
7. Ghi Change Impact Record, invalidate recommendation cũ và tạo recommendation mới.

Khi --artifact=context

1. Đọc CONTEXT.md hiện tại và SPEC.md để hiểu phạm vi đang lock.
2. Chạy Clarification-First cho thay đổi context.
3. Cập nhật Intent Packet, stakeholder, constraint, glossary hoặc open question bị ảnh hưởng.
4. Nếu intent, actor, boundary, constraint hoặc risk thay đổi, ghi rõ Spec revision required: yes | no và evidence trong Change Impact Record. Nếu yes, dừng để /sdd-update --artifact=spec trước downstream execution.
5. Ghi Change Impact Record, invalidate recommendation cũ và tạo recommendation mới.

Khi --artifact=plan

1. Đọc PLAN.md hiện tại, SPEC.md APPROVED & LOCKED và Architecture Profile.
2. Chạy Clarification-First cho thay đổi plan.
3. Cập nhật component, data flow, state-change classification, consistency map, contract impact hoặc risk bị ảnh hưởng.
4. Xác định task trong TASKS.md bị invalidated; ghi trace/test/sync follow-up.
5. Ghi Change Impact Record, invalidate recommendation cũ và tạo recommendation mới.

Khi --artifact=tasks

1. Đọc TASKS.md hiện tại, PLAN.md APPROVED và SPEC.md APPROVED & LOCKED.
2. Chạy Clarification-First cho task mới/sửa.
3. Thêm/sửa task: atomic, independent hoặc có blockedBy, exact verification command, scope category, checkpoint và sync-back responsibility.
4. Xác định task nào cần invalidate; cập nhật dependency và contract owner nếu cần.
5. Ghi Change Impact Record, invalidate recommendation cũ và tạo recommendation mới.

DoD

• Clarification-First đã chạy; assumption được ghi hoặc Human đã confirm.
• Change Impact Record nêu changed assumption, Feature Lock boundary, material state-change, invalidated downstream artifacts, trace/test/sync và review follow-up.
• Context change về intent/actor/boundary/constraint/risk quyết định rõ Spec revision required.
• Spec change đánh giá Plan/Tasks trước resume; requirement mới/sửa dùng EARS và SemVer đúng loại.
• Plan/Tasks change giữ profile binding, exact command, state-change checkpoint và sync-back responsibility.
• Recommendation mới ở PENDING HUMAN REVIEW; downstream execution dừng đến khi Human approve.

AI Recommendation và Human Final Review

Sau khi cập nhật artifact, tạo canonical recommendation từ .claude/skills/_shared/ai-review-protocol.md, gồm Change Impact Record, invalidated scope, review route và exact next command. Giữ Human Final Review.Status: PENDING; downstream execution bị block đến khi Human reviewer có thẩm quyền ghi APPROVED. Agent không tự approve artifact đã sửa.

Ví dụ

/sdd-update --feature=feat-user-register --artifact=spec --bump=patch --reason="[REQ-003] Add OTP rate-limit: max 5 attempts per 10 minutes"
/sdd-update --feature=feat-user-register --artifact=context --reason="Add compliance team as stakeholder; add GDPR constraint"
/sdd-update --feature=feat-user-register --artifact=plan --reason="Add Redis session risk and mitigation after security review"
/sdd-update --feature=feat-user-register --artifact=tasks --reason="Add T009 for concurrent registration dedup check"