git:20260831.c10e62e to git:20260831.e1e1453

---

name: sdd-review

description: Ghi nhận Human Final Review bền vững cho SDD/ADD artifact và chuyển trạng thái sau khi review

user-invocable: true

---

# Human Review State Manager (`/sdd-review`)

**Output language:** All output mirrors the language of the invoking prompt. Vietnamese prompt → Vietnamese output; English prompt → English output. Canonical tokens (`HUMAN REVIEW: RECORDED`, `HUMAN REVIEW: BLOCKED`, `PENDING`, `APPROVED`, `REVISE`, `REJECTED`, `PENDING HUMAN REVIEW`, `APPLIED`, `NOT APPLICABLE`), file paths, and CLI commands are language-invariant.

Dùng skill này sau khi Human Director, Tech Lead hoặc reviewer được ủy quyền đã đọc recommendation và bằng chứng. Skill cập nhật đúng `Human Final Review` block trong artifact; Agent không được tự chọn quyết định thay cho Human.

## Tham số

### Chọn target — dùng đúng một cách

- `--target=<repo-relative-path>`: Đường dẫn tương đối tới một artifact có review block, ví dụ:

- `.sdd/features/feat-user-register/CONTEXT.md`

- `.sdd/features/feat-user-register/SPEC.md`

- `.sdd/features/feat-user-register/PLAN.md`

- `.sdd/features/feat-user-register/TASKS.md`

- `.sdd/reviews/audit-feat-user-register.md`

- `.sdd/rfcs/RFC-001-soft-delete-policy.md`

- `.sdd/architecture-profile.md`

- Hoặc dùng cặp `--feature=<feature-slug> --artifact=<context|spec|plan|tasks>`.

Không dùng đồng thời `--target` với `--feature`/`--artifact`. Không nhận absolute path, path ngoài repository, `.env`, secret, private key, `node_modules/`, `dist/`, `.git/` hoặc `CONSTITUTION.md`; Constitution chỉ được thay đổi bằng RFC đã `APPROVED` theo `/sdd-rfc`.

### Ghi quyết định của Human

- `--status=<APPROVED|REVISE|REJECTED>`: Bắt buộc.

- `--decision="<quyết định cụ thể và phạm vi đã review>"`: Bắt buộc.

- `--reviewer="<tên hoặc identity của người review>"`: Bắt buộc.

- `--reviewed-at="<ISO-8601 timestamp có timezone>"`: Tùy chọn; nếu không điền mặc định lấy ISO-8601 timestamp hiện tại của hệ thống.

- `--follow-up="<bước tiếp theo, command hoặc điều kiện đóng>"`: Bắt buộc.

Không được bỏ trống các trường bắt buộc. Dùng `--status=REVISE` khi artifact phải sửa rồi review lại; dùng `--status=REJECTED` khi hướng đề xuất không được chọn. `APPROVED`, `REVISE` và `REJECTED` đều phải có decision, reviewer, timestamp (do user cung cấp hoặc mặc định lấy thời gian hiện tại) và follow-up.

## Quy trình thực hiện

1. **Xác định và kiểm tra target**:

- Resolve target từ `--target` hoặc `--feature` + `--artifact`.

- Chỉ cho phép feature artifact, `.sdd/reviews/` report, `.sdd/rfcs/` RFC hoặc `.sdd/architecture-profile.md`.

- Đọc file trước khi sửa; dừng nếu file không tồn tại, có nhiều review block hoặc không có `## Human Final Review`.

2. **Đọc protocol và recommendation**:

- Đọc `.claude/skills/_shared/ai-review-protocol.md`.

- Bắt buộc có `## AI Agent Recommendation` với `Status: PENDING HUMAN REVIEW`.

- Kiểm tra recommendation có `Scope`, `Recommendation`, `Evidence`, `Risks and assumptions`, `Alternatives considered` và `Required human decision` có nội dung.

- Không dùng skill này để biến recommendation thiếu bằng chứng thành approval.

3. **Kiểm tra dữ liệu Human**:

- `status` phải đúng một trong ba giá trị canonical.

- `decision`, `reviewer` và `follow-up` không được là placeholder như `<...>`, `TBD`, `TODO`, `PENDING` hoặc chuỗi rỗng.

- `reviewed-at` nếu được truyền phải là timestamp ISO-8601 có timezone, ví dụ `2026-08-22T00:45:00+07:00`; nếu không truyền thì mặc định lấy ISO-8601 timestamp hiện tại có timezone của hệ thống.

- `decision` phải nói rõ artifact/phạm vi đã duyệt và kết luận; `follow-up` phải nói bước tiếp theo hoặc lý do không có bước tiếp theo.

- Nếu review hiện tại đã là `APPROVED`, không ghi đè decision hợp lệ bằng lệnh mới.

- Nếu artifact đã thay đổi approved scope — intent, requirement, file boundary, exact command, checkpoint category hoặc shared-contract decision — phải coi review cũ là không còn hợp lệ, đưa status về `PENDING`, tạo recommendation mới hoặc ghi nhận thay đổi scope trước khi Human review lại. Task status và append-only `Action Record`/`Current Handoff State` không làm mất hiệu lực khi các field scope không đổi.

- Nếu status cũ là `REVISE` hoặc `REJECTED`, chỉ cập nhật khi recommendation mới đã được Agent tạo và vẫn đang `PENDING HUMAN REVIEW`.

- Chỉ thay đổi các dòng trong `## Human Final Review`: `Status`, `Decision`, `Reviewer`, `Reviewed at`, `Follow-up`.

- Không sửa `AI Agent Recommendation`, requirement, architecture, tasks, evidence, changelog hoặc nội dung RFC.

- Giữ nguyên thứ tự và tên field canonical.

- Nếu target là `SPEC.md` và status là `APPROVED`, kiểm tra DoD tối thiểu: SemVer hợp lệ, requirement `REQ-XXX` không trùng, EARS/acceptance/out-of-scope hiện diện, recommendation hợp lệ và review đủ trường.

- Chỉ sau khi các kiểm tra đạt mới đổi header `Status: DRAFT` thành `Status: APPROVED & LOCKED`.

- Nếu status là `REVISE` hoặc `REJECTED`, giữ Spec ở trạng thái chưa lock và in bước xử lý tiếp theo.

- Skill không sửa `CONSTITUTION.md`; RFC vẫn phải được phê duyệt bằng `/sdd-rfc --approve=<rfc-number>` theo contract riêng.

- Nếu target là `.sdd/architecture-profile.md`, kiểm tra recommendation nêu selected binding, repository evidence, exact verification command hoặc explicit `N/A` và configuration gap còn lại.

- `APPROVED` chỉ xác nhận binding/evidence đã review. Nó không tự resolve binding thiếu, không thay exact command bằng suy đoán và không bypass Architecture Profile Protocol cho Plan, Tasks hoặc execution.

```text

HUMAN REVIEW: RECORDED

Target: <path>

Previous status: <old status>

New status: <APPROVED|REVISE|REJECTED>

Reviewer: <identity>

Reviewed at: <timestamp>

Spec lock: APPLIED | NOT APPLICABLE | BLOCKED

Next step: <follow-up>

```

Nếu validation fail, không sửa file và báo `HUMAN REVIEW: BLOCKED` kèm field/path/điều kiện cần khắc phục.

## Ví dụ

### Approve Context

```text

/sdd-review --feature=feat-user-register --artifact=context --status=APPROVED --decision="Đã duyệt problem, stakeholders, glossary và constraints; đủ cơ sở lập SPEC, chưa duyệt giải pháp kỹ thuật." --reviewer="Nguyen Van A, Product Owner" --reviewed-at="2026-08-22T00:45:00+07:00" --follow-up="/sdd-spec --feature=feat-user-register"

```

### Approve Spec và lock

```text

/sdd-review --target=.sdd/features/feat-user-register/SPEC.md --status=APPROVED --decision="Đã duyệt REQ-001 đến REQ-012, BDD, error cases, NFR và out-of-scope; cho phép lập Plan theo Spec v1.0.0." --reviewer="Nguyen Van B, Tech Lead" --reviewed-at="2026-08-22T01:00:00+07:00" --follow-up="/sdd-plan --feature=feat-user-register"

```

### Yêu cầu sửa

```text

/sdd-review --target=.sdd/features/feat-user-register/PLAN.md --status=REVISE --decision="Bổ sung phương án rollback migration và làm rõ dependency giữa repository với usecase." --reviewer="Nguyen Van B, Tech Lead" --reviewed-at="2026-08-22T01:10:00+07:00" --follow-up="Cập nhật PLAN.md, tạo recommendation mới rồi gọi lại /sdd-review sau khi review."

```

### Từ chối report

```text

/sdd-review --target=.sdd/reviews/audit-feat-user-register.md --status=REJECTED --decision="Không chấp thuận disposition vì Layer 1 failure còn mở; phải remediation trước delivery." --reviewer="Nguyen Van C, Human Director" --reviewed-at="2026-08-22T01:20:00+07:00" --follow-up="Sửa blocker, chạy lại /sdd-audit và tạo report review mới."

```

## Điều kiện không được tự động vượt qua

- Không có recommendation hoặc recommendation không ở `PENDING HUMAN REVIEW`.

- Thiếu một trong các trường Human bắt buộc (`status`, `decision`, `reviewer`, `follow-up`).

- Target không nằm trong phạm vi cho phép.

- Review cũ đã `APPROVED` nhưng chưa có evidence artifact thay đổi và recommendation mới.

- Spec không đạt DoD tối thiểu khi cần lock.

- Architecture Profile recommendation thiếu binding/evidence/exact command hoặc cố bypass protocol.

- RFC chưa qua quy trình `/sdd-rfc --approve`.

`/sdd-review` chỉ ghi nhận quyết định do người gọi cung cấp. Nó không xác minh người gọi có đúng quyền trong tổ chức; quyền reviewer phải được kiểm soát bởi quy trình repository và Git/PR.