docs: add agent-assisted PR review guidelines

[zywind]

Summary

• adapt CodeRabbit's review-comment template with consistent area, impact, effort/value, and expected-handling metadata
• add a SHA-pinned helper command that submits an exact approved review and returns direct links
• include submitted review bodies in duplicate detection alongside inline and top-level comments
• require exact human approval, truthful attribution, and head rechecks before posting

Example review

Test plan

• uv run --no-project .../quick_validate.py .agents/skills/github-cli
• focused helper tests: 4 passed
• mise run format-check

Summary by CodeRabbit

New Features

• Added support for retrieving submitted pull request reviews and summary text alongside discussion comments.
• Added a workflow for submitting approved reviews with inline findings and result links.
• Added safeguards to ensure reviews target the latest pull request revision.

Bug Fixes

• Improved validation for review findings, including required line and side information.

Documentation

• Expanded review guidance covering approval, duplicate detection, attribution, revalidation, and completion requirements.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: c951efbf-79b7-4645-9323-eeb2eb77cca9

📥 Commits

Reviewing files that changed from the base of the PR and between 9fc33a4 and 8b3a595.

📒 Files selected for processing (1)

• .agents/skills/github-cli/references/review-comments.md

🚧 Files skipped from review as they are similar to previous changes (1)

• .agents/skills/github-cli/references/review-comments.md

📜 Recent review details

⏰ Context from checks skipped due to timeout. (2)

• GitHub Check: Greptile Review
• GitHub Check: Analyze (python)

---

Walkthrough

The pull request adds a review-comment contract, extends the GitHub CLI helper to collect and submit reviews, and updates repository guidance and tests for the workflow.

Changes

Pull Request Review Workflow

Layer / File(s)	Summary
Review comment contract .agents/skills/github-cli/references/review-comments.md	Defines review workflow controls, approved-review fields, finding classifications, fix authorization, and attribution requirements.
Review retrieval and submission .agents/skills/github-cli/scripts/gh_pr_helper.py	Adds submitted-review output, validated review models, head-SHA checks, the submit-review command, and returned review and comment links.
Workflow guidance and validation AGENTS.md, .agents/skills/github-cli/SKILL.md, .agents/skills/github-cli/references/workflows.md, .agents/skills/github-cli/tests/test_gh_pr_helper.py	Requires the review contract, documents discussion retrieval and submission, and tests collection, validation, stale-head rejection, and returned links.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Merge Risk: 🔵 Low · up to 8b3a5

The helper command still produces an unhandled traceback for a non-numeric PR argument instead of a clear validation error. This is a bounded CLI correctness issue, so the PR is mergeable with explicit owner follow-up.

Suggested labels: feature

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the documentation for agent-assisted PR reviews, but it does not mention the related helper tooling changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch yunfeng/agent-assisted-review-comments

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Greptile Summary

The PR adds an agent-assisted pull-request review workflow and a head-pinned helper for submitting approved reviews.

• Defines review classification, approval, attribution, deduplication, and completion requirements.
• Extends discussion retrieval to include submitted review bodies.
• Adds validated review-artifact submission with stale-head protection and direct result links.
• Adds focused tests for discussion collection, submission, head validation, and multiline ranges.

Confidence Score: 5/5

The PR appears safe to merge.

No blocking failure remains.

Important Files Changed

Filename	Overview
.agents/skills/github-cli/scripts/gh_pr_helper.py	Adds submitted-review retrieval and validated, head-pinned review submission with direct output links.
.agents/skills/github-cli/tests/test_gh_pr_helper.py	Adds focused unit coverage for discussion retrieval, successful submission, stale-head rejection, and multiline validation.
.agents/skills/github-cli/references/review-comments.md	Defines the review workflow, finding metadata, exact-approval requirements, attribution, and completion criteria.
.agents/skills/github-cli/SKILL.md	Routes PR-review tasks to the new contract and documents the expanded helper interface.
.agents/skills/github-cli/references/workflows.md	Updates comment-handling guidance to include review bodies and approved review submission.
AGENTS.md	Directs repository agents to follow the github-cli review-comment contract.

Sequence Diagram

sequenceDiagram
  participant Agent
  participant Human
  participant Helper as gh_pr_helper.py
  participant GitHub
  Agent->>GitHub: Fetch inline comments, reviews, and discussion
  Agent->>Human: Present exact head-pinned review artifact
  Human-->>Agent: Approve exact text and targets
  Agent->>Helper: submit-review with approved JSON
  Helper->>GitHub: Recheck current PR head
  alt Head matches
    Helper->>GitHub: Submit COMMENT review
    GitHub-->>Helper: Review and inline comments
    Helper-->>Agent: Return direct review and comment URLs
  else Head changed
    Helper-->>Agent: Abort and require re-verification
  end

Loading

_{Reviews (6): Last reviewed commit: "Update .agents/skills/github-cli/scripts..." | Re-trigger Greptile}

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (2)

.agents/skills/github-cli/tests/test_gh_pr_helper.py (1)

139-146: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Consider adding a case for a valid multiline range payload.

The current test covers only the rejection path. A positive case that sets start_line and start_side together and asserts the github_payload() output would lock the wire format for multiline findings.

.agents/skills/github-cli/scripts/gh_pr_helper.py (1)

259-281: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Handle GitHub API failures in submit_review.

PyGithub does not provide PullRequestReview.get_comments(), so retain pr.get_review_comments() for retrieving posted comments. Catch GithubException around the submission and retrieval calls to avoid raw tracebacks. Warn that retrying after an uncertain failure can create duplicate reviews.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 77159167-355c-4e3e-a4b7-2b351c0f578b

📥 Commits

Reviewing files that changed from the base of the PR and between c25c819 and 187e3b4.

📒 Files selected for processing (5)

• .agents/skills/github-cli/SKILL.md
• .agents/skills/github-cli/references/review-comments.md
• .agents/skills/github-cli/references/workflows.md
• .agents/skills/github-cli/scripts/gh_pr_helper.py
• .agents/skills/github-cli/tests/test_gh_pr_helper.py

🚧 Files skipped from review as they are similar to previous changes (1)

• .agents/skills/github-cli/references/review-comments.md

📜 Review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Greptile Review

⚠️ CI failures not shown inline (2)

GitHub Actions: CI - checks / CI Status: docs: add agent-assisted PR review guidelines

Conclusion: failure

View job details

##[group]Run echo "changes:    success"
 �[36;1mecho "changes:    success"�[0m
 �[36;1mecho "format:     failure"�[0m
 �[36;1mecho "typecheck:  success"�[0m
 �[36;1mecho "wheel:      skipped"�[0m
 �[36;1mecho "unit-test:  skipped"�[0m
 �[36;1mecho "smoke-test: skipped"�[0m
 �[36;1m�[0m
 �[36;1mif [[ "true" == "true" ]]; then�[0m
 �[36;1m  echo "::error::One or more CI jobs failed"�[0m

---

GitHub Actions: CI - checks / 0_CI Status.txt: docs: add agent-assisted PR review guidelines

Conclusion: failure

View job details

##[group]Run echo "changes:    success"
 �[36;1mecho "changes:    success"�[0m
 �[36;1mecho "format:     failure"�[0m
 �[36;1mecho "typecheck:  success"�[0m
 �[36;1mecho "wheel:      skipped"�[0m
 �[36;1mecho "unit-test:  skipped"�[0m
 �[36;1mecho "smoke-test: skipped"�[0m
 �[36;1m�[0m
 �[36;1mif [[ "true" == "true" ]]; then�[0m
 �[36;1m  echo "::error::One or more CI jobs failed"�[0m

🧰 Additional context used

📓 Path-based instructions (1)

.agents/skills/**

📄 CodeRabbit inference engine (.cursor/rules/repo-navigation.mdc)

Store skills in canonical location .agents/skills/ with each skill containing a SKILL.md file and optional references/

Repo-specific skills live in .agents/skills/; see .agents/README.md for the catalog. Read a skill when the task matches its scope instead of copying workflow details into this file.

Files:

• .agents/skills/github-cli/references/workflows.md
• .agents/skills/github-cli/SKILL.md
• .agents/skills/github-cli/tests/test_gh_pr_helper.py
• .agents/skills/github-cli/scripts/gh_pr_helper.py

🪛 GitHub Actions: CI - checks / 6_Format.txt

.agents/skills/github-cli/tests/test_gh_pr_helper.py

[error] 1-1: Formatting check failed: bash tools/codestyle/format.sh --check reported that this file would be reformatted. Run the formatter to fix it.

🪛 GitHub Actions: CI - checks / Format

.agents/skills/github-cli/tests/test_gh_pr_helper.py

[error] 1-1: Formatting check failed: the file would be reformatted. Run 'bash tools/codestyle/format.sh' to fix formatting.

🪛 Ruff (0.16.1)

.agents/skills/github-cli/scripts/gh_pr_helper.py

[warning] 336-345: Do not perform function call typer.Option in argument defaults; instead, perform the call within the function, or read the default from a module-level singleton variable

(B008)

🪛 SkillSpector (2.5.1)

.agents/skills/github-cli/SKILL.md

[warning] 226: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

---

[warning] 226: [EA2] Autonomous Decision Making: Skill enables autonomous high-impact decisions without human-in-the-loop verification. Critical operations (destructive commands, financial transactions, data deletion) should require explicit user confirmation.

Remediation: Add human-in-the-loop confirmation for destructive, irreversible, or high-impact operations. Never auto-execute commands that modify files, send data, or alter system state.

(Excessive Agency (EA2))

🔇 Additional comments (4)

.agents/skills/github-cli/scripts/gh_pr_helper.py (2)

79-98: LGTM!

Also applies to: 109-171

---

336-345: 🎯 Functional Correctness

Keep path_type=Path unchanged. Typer 0.24.1 forwards it to Click, and Click supports pathlib.Path. The review_file: Path annotation is consistent with the resulting value.

.agents/skills/github-cli/references/workflows.md (1)

227-227: LGTM!

Also applies to: 237-243, 274-282

.agents/skills/github-cli/SKILL.md (1)

13-19: 📐 Maintainability & Code Quality

References are present and valid. Both links resolve, and review-comments.md contains the Submit an Approved Review heading.