Sdd Review

---
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/reviews/dispatch-feat-user-register-batch-01.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.

4. **Batch dispatch review**:
   - Batch dispatch approval dùng `.sdd/reviews/dispatch-<feature>-<batch>.md`; `TASKS.md` Dispatch Record chỉ tham chiếu report này và không là review target độc lập.
   - Với material/cross-contract batch, `decision` phải nêu feature, batch/task IDs, frozen contract version, scope/file boundary và allowed action/checkpoint.
   - Không dùng review để xác nhận host enforcement không có observed evidence; `UNVERIFIED` là configuration limitation, không phải approval bypass.

5. **Kiểm tra trạng thái cũ**:
   - 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`.

6. **Cập nhật đúng phạm vi**:
   - 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.

7. **Xử lý Spec lock**:
   - 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.

8. **Architecture Profile review**:
   - 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.

9. **Báo cáo kết quả**:

```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.