kf-g-github-pr-review-workflow

GitHub PR Creation and Review Operations

This skill defines the rules for PR creation, updates, reviews, and comments. For all GitHub operations in general, use kf-g-github-operations-bot-workflow, and for issue-driven work, also use kf-g-github-issue-worktree-management .

Basic Policy

Use one issue per PR as the baseline.
Link the PR to the corresponding issue, and prefer a form where the issue closes on merge/close.
After creating the PR, leave the PR URL in an issue comment.
Set reviewers with the bot helper script.
AI agent PR creation / commenting / review / reply / resolve / description updates are executed only after a successful GitHub App bot preflight.
If bot preflight fails, display the setup steps and stop. Human gh / GH_TOKEN fallback is prohibited.

Before PR creation

Check:

Issue number, issue URL, completion criteria
Whether the branch is the branch for the issue
Whether the worktree is the worktree for the issue
Whether unrelated changes are mixed in
Whether repository native checks pass
Whether bot preflight succeeds

PR body

For PR description (body) content, separate based on whether HTML distribution exists.

HTML distribution present (already uploaded to R2)

kf-g-html-document-universal-single-file When generating HTML with and uploading it to R2:

In the PR description, put only the minimal summary and ## レビュー用資料 the HTML links under put only
Put the detailed plan, test plan, risks, and implementation history in the HTML body , and do not duplicate them in the description
After R2 upload and public URL confirmation finalize the description. While the URL or v{N}(version number) is not yet finalized, do not place links
Use only the link label v{N}(version number) extracted from the versioned object name(e.g., ..._v2.html → [v2](...)）。最新版HTML or do not use the entire filename
When you revise the HTML, upload a new v{N} and replace the description link and label with the latest version (do not overwrite the old version)

## 概要
- <PR の最小サマリ>

## レビュー用資料
[v{N}](https://ai-html.hacksaw.work/<object-key>)

Use only the verified URL and v{N}(version number) in the Markdown link
If automatic issue close is required, you may add Closes #<issue-number> or the closing keyword defined by the repository at the end of the description

No HTML distribution

For a normal PR with no HTML distribution:

In the PR description, put the Markdown completed on the issue sideas isand describe it
Reason: because with repository settings, the description (= planning) can be automatically reflected in the merge commit message during squash merge
If automatic issue close is required, you may add Closes #<issue-number> or the closing keyword defined by the repository at the end of the description. Only this allows additions to the issue Markdown

Items to include in PR comments

The following items that should originally be described in the PR description areinitial comment(or a comment as appropriate).

Summary for Reviewers
Verification results
Related information (issue links, dependent PRs, etc.)
Unconfirmed items or remaining risks

The following are already displayed in the GitHub PR UI, so in neither the description nor a commentdo not write them as a summary。

Commit list
List/summary of GitHub Actions / CI results
Changed files list

Only when a link to an individual check run is needed for investigation or incident response, it may be written as a URL link in a comment / reply (see## PR description / comment のリンク化 ).

Linking in PR description / comments

When creating the body of a PR description / comment / reply, if the following targets appear in the body, write them in link format whenever possible. For targets whose URL is not yet determined, supplement by updating the body or via a comment / reply after the URL is known.

issue: #<issue-number>. If it is a different repository, OWNER/REPO#<issue-number>。
PR: #<pr-number>. If it is a different repository, OWNER/REPO#<pr-number>。
commit: [{short commit id}]({PR base URL}/changes/{commit id})。
file: [path/to/file](<repository URL>/blob/<branch-or-commit>/path/to/file)。
file line: [path/to/file:L<line>](<repository URL>/blob/<branch-or-commit>/path/to/file#L<line>)。
review comment / thread: [review comment](<comment URL>)。
CI / check run: Only when investigation or incident response is needed, write it in a comment / reply with [<check name>](<check run URL>) . Do not write a list/summary of CI results.
R2 HTML (if HTML distribution is available): In the description's ## レビュー用資料 under [v{N}](https://ai-html.hacksaw.work/<object-key>) put it. Do not put unconfirmed URLs or v{N} .

PR creation

After bot preflight succeeds:

node ~/.agents/credentials/github/scripts/github-agent-create-pr.mjs OWNER/REPO --head BRANCH --base BASE [--title TITLE] BODY_FILE

PR description update:

node ~/.agents/credentials/github/scripts/github-agent-update-pr.mjs OWNER/REPO PR_NUMBER BODY_FILE

After PR creation

Perform:

Comment the PR URL on the issue.
Set the reviewer with the bot script.
Update the issue status to waiting for review.
Check CI / checks.
If it fails, investigate the cause and, if necessary, leave the status on the issue / PR.

Reviewer setting:

node ~/.agents/credentials/github/scripts/github-agent-set-reviewers.mjs OWNER/REPO PR_NUMBER REVIEWER [REVIEWER...]

Bot comment / review

PR conversation comment:

node ~/.agents/credentials/github/scripts/github-agent-comment.mjs OWNER/REPO PR_NUMBER BODY_FILE

PR review comment:

node ~/.agents/credentials/github/scripts/github-agent-review.mjs OWNER/REPO PR_NUMBER BODY_FILE --event COMMENT

Review comment reply:

node ~/.agents/credentials/github/scripts/github-agent-reply.mjs OWNER/REPO PR_NUMBER COMMENT_ID BODY_FILE

Review thread resolve (after successful reply):

node ~/.agents/credentials/github/scripts/github-agent-resolve-thread.mjs OWNER/REPO PR_NUMBER --comment-id COMMENT_ID

Review event:

COMMENT: Notification, confirmation, neutral comment.
APPROVE: Use only when AI agent approval is permitted by the repository rules.
REQUEST_CHANGES: Use only when there is a clear blocker and the repository rules permit an AI agent to submit requested changes.

Review response

When responding to review comments:

Check unresolved threads / requested changes / CI failures.
Always respond with a reply to user PR comments / review comments.
Even if multiple review comments are included in one review, reply individually to each review comment / thread.
Separate fixes, explanations, and holds for each point raised.
Leave the contents of fixes, explanations, and holds in the reply to the relevant comment / thread.
Resolve the thread only after confirming the reply succeeded.
Do not mix in unrelated changes you made yourself.

Prohibited items

Merge process
GitHub writes before bot preflight
Human gh / GH_TOKEN AI write fallback by
For a review that contains multiple comments together, create a single combined comment and reply with it.

Final check

Is it handled as 1 issue per 1 PR?
Did you leave the PR URL in the issue?
Did you set the reviewer with the bot script?
Did you make the bot preflight succeed?
Were AI agent comment / review / reply / resolve posted with bot credentials?
Did you individually reply to PR comments / review comments from users?
With HTML distribution: In the PR description, did you include the minimal summary and ## レビュー用資料 under [v{N}](https://ai-html.hacksaw.work/<object-key>) only? Without HTML distribution: Did you include the completed issue Markdown as is?
Did you include the Summary, verification results, and related information in a PR comment?
Are you not writing information that duplicates the GitHub UI (commit list, Actions, changed files) in the PR description / comments?
Did you write the link targets in the PR description / comment / reply in link format as much as possible?
Are you not avoiding gitleaks failures?