Execution Playbook (Spec-Driven Delivery)

1. Intended Outcome

Sau khi đọc playbook này, dev có thể lấy 1 feature và triển khai ngay task kế tiếp bằng tài liệu chuẩn.

2. End-to-End Flow

Step 0 — Pick Work Item

Chọn item từ traceability/WORKITEM_BOARD.md.
Kiểm tra Feature Key có tồn tại trong FEATURE_STATUS_MATRIX.md.

Step 1 — Build Task Packet

Tạo packet theo specs/TASK_PACKET_TEMPLATE.md.
Điền đủ: scope, contract, touched files, acceptance criteria, test plan, rollback plan.

Step 2 — Pre-code Validation

Kiểm tra Decision liên quan ở 01_DECISION_LOG.md.
Kiểm tra API/UI/entity hiện trạng ở _generated/*.
Nếu scope chưa rõ hoặc mâu thuẫn, tạo quyết định mới trước khi code.

Step 3 — Implement

Backend: ưu tiên thay đổi ở module domain (libs/modules/*) rồi mới wiring vào apps/api nếu cần.
Frontend: thay đổi ở apps/v2-portal theo route và permission map.
Cập nhật tests tại cùng module.

Step 4 — Verify

Chạy test/lint tối thiểu cho module touched.
Đối chiếu lại contract request/response.
Cập nhật Feature Status và API Traceability.

Step 5 — Close & Handoff

Mark WORKITEM_BOARD sang DONE.
Thêm note ngắn vào 08_PROGRESS_AND_REPORTING.md.
Liệt kê next tasks phụ thuộc.

3. Task Granularity Rules

Task đủ nhỏ để review trong 1 PR:

Mỗi task chỉ nên chạm tối đa 1 domain chính + 1 integration point.
Nếu thay đổi trên 3 domain hoặc trên 15 file logic chính, tách thành sub-task.

4. “Ready for Coding” Criteria

Một task chỉ được bắt đầu khi có đầy đủ:

Feature Key và status hợp lệ.
Acceptance Criteria rõ ràng (Given/When/Then hoặc checklist định lượng).
API contract hoặc UI behavior xác định.
Test plan cụ thể.

5. “Done” Criteria

Code merge pass quality gates.
Docs update hoàn tất ở các file bắt buộc.
Traceability cập nhật xong.
Không còn TODO mơ hồ trong code hoặc docs.