Review, sửa hoặc merge các pull request với ak:review-pr

Dùng ak:review-pr để đánh giá một hoặc nhiều GitHub pull request dựa trên scope đã nêu, code xung quanh, quy tắc repository, test, ranh giới bảo mật và trạng thái sẵn sàng merge. Mode mặc định chỉ đọc. Các cờ tùy chọn lần lượt mở rộng workflow của từng pull request để sửa branch, đăng formal review hoặc merge rồi theo dõi CI sau merge.

Chọn ak:review-pr cho các GitHub pull request hiện có

Dùng ak:review-pr khi

• Bạn cần verdict dựa trên toàn bộ diff và các tệp đầy đủ liên quan.
• Bạn muốn kiểm tra correctness, security, breaking change, test và chất lượng code trong một review.
• Bạn muốn vòng lặp sửa và review lại có giới hạn trên branch của pull request.
• Bạn chủ động muốn đăng review cuối hoặc merge một pull request đã sẵn sàng.

Chọn workflow khác khi

• Bạn chỉ cần review thay đổi local chưa gửi lên. Dùng ak:code-review.
• Bạn đã biết defect và cần sửa root cause ngoài pull request workflow. Dùng ak:fix.
• Bạn cần chuẩn bị commit và mở hoặc cập nhật pull request. Dùng ak:ship.
• Repository không nằm trên GitHub hoặc session không thể dùng GitHub CLI.

Chuẩn bị GitHub và repository

Trước khi bắt đầu:

• Hoàn thành Làm quen và xác nhận Kit đã cài có thể dùng trong runtime hiện tại.
• Chạy trong repository của pull request. Cung cấp một hoặc nhiều ref dưới dạng số thuần (123), số có dấu thăng (#123) hoặc URL đầy đủ của PR; phân tách các ref bằng khoảng trắng hoặc dấu phẩy.
• Cài đặt, xác thực gh với quyền đọc repository và các pull request.
• Với --fix, bắt đầu từ đúng head branch của pull request ở trạng thái sạch và giữ nguyên thay đổi không liên quan của người dùng.
• Chỉ cấp quyền write, review, merge và Actions cho các mode bạn định dùng.

Chọn quyền hạn có chủ đích

Các cờ có thể đứng theo thứ tự bất kỳ và kết hợp với nhau. Không có cờ, Skill in từng review ở local.

--fix --reply chỉ đăng lần review lại cuối cho từng PR. Thêm --merge sẽ chạy giai đoạn merge cuối cùng của PR đó, sau hành vi sửa và reply.

Các ref có thể được phân tách bằng khoảng trắng hoặc dấu phẩy: 482 517 --reply và 482,517 --reply chọn cùng hai PR. Skill xử lý ref theo thứ tự input và hoàn tất toàn bộ flow review, fix, reply, merge cùng advice đã chọn cho một PR trước khi bắt đầu PR tiếp theo. Lỗi nghiêm trọng riêng của một PR được ghi lại và run tiếp tục với các ref còn lại; chỉ lỗi môi trường không thể khôi phục mới dừng toàn bộ run. Truyền một ref vẫn giữ nguyên mode, gate và tác động của workflow một PR.

/ak:review-pr 482 --fix --reply

/ak:review-pr 482 --fix --reply

$ak:review-pr 482 --fix --reply

Để review chỉ đọc, bỏ mọi cờ. Để cấp quyền cho toàn bộ đường đi, dùng input như 482 --fix --reply --merge; các cờ cấp quyền cho giai đoạn được nêu nhưng không bỏ qua readiness, verification hay bảo vệ của repository.

Hiểu review workflow

Với từng PR theo thứ tự input:

1. Skill phân giải context. Skill đọc metadata, description, số tệp thay đổi, toàn bộ diff và check hiện tại của pull request.
2. Skill xác minh công việc đã nêu. Title, body, issue liên kết, scope và completion evidence được so với thay đổi thực tế.
3. Skill kiểm tra implementation context. Mọi tệp thay đổi và source xung quanh có liên quan được đối chiếu với instruction hiện tại cùng pattern của project.
4. Skill phân loại finding. Finding về correctness, security, breaking change, test và maintainability trở thành mục Critical, Important hoặc Suggestion với bằng chứng cụ thể.
5. Skill trả về verdict. Approve nghĩa là không có finding Critical hoặc Important; Request changes nghĩa là còn blocker; Comment nghĩa là chỉ có gợi ý nhỏ.
6. Các giai đoạn tùy chọn chạy theo thứ tự. Fix loop sửa và review lại, reply đăng review cuối, còn merge chỉ chạy sau khi mọi điều kiện readiness đạt.

Chuỗi đã chọn hoàn tất từ đầu đến cuối cho PR hiện tại trước khi ref tiếp theo bắt đầu. Phần review prose dành cho người đọc dùng writing language đã cấu hình khi có thể phân giải. Command, path, identifier, GitHub keyword và bằng chứng trích dẫn được giữ nguyên.

Hiểu đường GitHub API thích ứng

Compatibility helper đã cài probe tính khả dụng của GraphQL bằng gh api graphql. Khi GraphQL bị chặn, các lượt đọc được hỗ trợ cho metadata PR, diff, tệp thay đổi, check và body dùng REST. Formal review và comment trên PR cũng có REST fallback: session chỉ dùng REST sẽ bỏ qua lần thử native, còn session dùng được GraphQL ưu tiên thao tác gh pr native rồi thử lại qua REST nếu thao tác đó thất bại.

Đây là fallback thích ứng, không phải claim rằng mọi thao tác GitHub đều GraphQL-free. Lệnh gh pr native vẫn có thể dùng GraphQL, và GitHub chỉ cung cấp việc bật auto-merge qua GraphQL. Vì vậy giai đoạn merge dùng hành vi native hoặc REST có điều kiện được mô tả bên dưới.

Giữ quyền write và merge rõ ràng

Các ranh giới quan trọng:

• Nếu kiểm tra cài đặt hoặc xác thực gh thất bại trong reply mode, Skill quay về output local; không âm thầm tuyên bố đã đăng review.
• GitHub không cho bạn approve pull request của chính mình. Skill gửi lại một self-review lẽ ra Approve dưới dạng comment trung lập và báo rõ việc hạ cấp.
• Merge gate yêu cầu verdict Approve, không có blocker từ fix loop, PR đang mở và mergeable, không còn changes request, đồng thời check đã pass hoặc chỉ đang chờ. Với check đang chờ, đường native có thể bật --auto; REST fallback không thể bật auto-merge mà phải đợi check terminal-green trước khi merge qua REST. Cả hai đường đều không ép qua check đỏ, conflict hay branch protection.
• --fix không được commit hoặc push khi verification thất bại, phát hiện secret hoặc sẽ bao gồm thay đổi không liên quan của người dùng.
• Chạy lại --reply sẽ đăng thêm một review; workflow hiện tại không deduplicate reply cũ.
• gh dùng credential và network access hiện có của session. Policy repository, hosted CI minute và third-party check có thể tạo tác động hoặc chi phí bên ngoài; Skill không định nghĩa phí provider riêng.

Xác minh bằng chứng

Kết quả hoàn chỉnh nên có cho từng PR:

• Summary, risk level, finding theo severity và verdict cuối.
• Bằng chứng tệp cùng dòng hoặc function cho mọi finding có thể hành động.
• Số lần lặp fix loop, commit đã push và blocker còn lại khi chạy --fix.
• --reply đã đăng, hạ self-approval xuống comment hay quay về output local.
• Với --merge, kết quả merge, merge commit, kết luận CI đã theo dõi và mọi follow-up fix.
• Câu hỏi chưa giải quyết được nêu rõ thay vì claim hoàn tất thiếu căn cứ.

Sau khi mọi ref hoàn tất, kết quả cũng tổng hợp số PR đã xử lý, tổng theo verdict, mode môi trường AK_GH_REST=<0|1> và số lần thực sự dùng đường REST, cùng blocker còn lại theo PR. Lần gọi một ref vẫn giữ nguyên kết quả đầy đủ cho PR đó.

Bằng chứng release bao phủ việc chuyển Skill sang adapter portable cùng contract multi-PR và API thích ứng được mô tả tại đây. Điều này không bảo đảm permission GitHub thực tế, quy tắc merge riêng của repository, thời lượng CI hay approval prompt giống nhau giữa các runtime.

Khắc phục an toàn

Tiếp tục với ak:code-review để review local, ak:ship để chuẩn bị pull request hoặc ak:git cho Git workflow tập trung hơn.