pr-review-guide

---
name: pr-review-guide
description: Guidelines for posting pull request review comments via GitHub CLI, including suggested edits format, handling unresolved comments, etiquette, and report/issue tracking. Load this skill when reviewing a PR via GitHub and posting inline comments.
license: Apache-2.0
---

Load this skill when posting review comments on a GitHub pull request.

### Line Number Tracking

When analyzing a PR diff, **Always** record exact file paths and line numbers for every finding as
you go. Each finding must include the precise `path` and `line` (and `start_line` for multi-line
ranges) in the _new_ file (right side of the diff) needed to post a review comment. **Do not** defer
line number resolution to a later step.

When the review is performed by a sub-agent, the agent's returned findings must include these fields
per finding so the caller can post comments immediately:

- `path`: file path relative to repo root
- `line`: line number in the new file (end line for multi-line)
- `start_line` (optional): start line for multi-line comments
- `body`: the comment text, ready to post

### Posting Review Comments

When asked to review a pull request, you may use the GitHub CLI tool to post inline comments on the
PR with specific feedback for each issue you identify. You can suggest specific code changes in your
comments. **Always** reference specific lines of code in your comments for clarity.

When providing feedback on a pull request:

- **Always** focus on actionable insights that can help improve the code
- **Always** be clear and concise in your comments; provide specific examples or references
  to the code to support your feedback. Avoid vague statements and instead provide concrete
  suggestions for improvement.
- **Always** post comments on specific lines of code and never as a single monolithic comment

### Suggested Edits

When the fix for an issue is obvious and localized (e.g., a typo, a missing annotation, a wrong
type, a simple rename), include a GitHub suggested edit block in your review comment so the author
can apply it with one click. Use this format:

````
```suggestion
corrected line(s) of code here
```
````

Guidelines for suggested edits:

- **Do** use them for: typos, missing `override`/`[[nodiscard]]`/`constexpr`, wrong types, simple renames, small bug fixes where the correct code is unambiguous.
- **Do not** use them for: large refactors, design changes, cases where multiple valid fixes exist, or anything requiring context the author should decide on.
- Keep suggestions minimal — change only the lines that need fixing. Do not reformat surrounding code.
- When a suggestion spans multiple lines, include all affected lines in the block.

### Unresolved Review Comments

When reviewing a PR, **always** check prior review comments (from any reviewer) that have been marked
as resolved. If the current code still exhibits the issue described in a resolved comment, flag it as
a finding with a reference to the original comment. Use this format:

- **[HIGH]** Previously flagged issue not addressed: _{original comment summary}_
  - **Location**: File and line references
  - **Problem**: Review comment by {author} was marked resolved but the underlying issue remains in
    the current code.
  - **Evidence**: Link to or quote the original comment, and show the current code that still has
    the issue.
  - **Recommendation**: Address the original feedback before merging.

**Do not** flag resolved comments where the concern has been legitimately addressed, even if addressed differently than the reviewer suggested.

### Tone

- **Do not editorialize.** No praise, no compliments on the approach, no filler like "nice fix!" or "solid solution." The review body and inline comments should contain only findings, questions, and actionable feedback. Let the findings speak for themselves.
- The review body should be a concise summary of findings (a bulleted list is fine) plus the AI-generated disclaimer. Nothing else.

### Etiquette

- Do not spam the pull request with excessive comments. Focus on the most important issues and
  provide clear guidance on how to address them. If there are minor style issues, you can mention
  them but prioritize more significant architectural, performance, security, or correctness issues.
- Do not modify existing comments or feedback from other reviewers. When issues are addressed and
  resolved, you can acknowledge the changes with a new comment but avoid editing or deleting
  previous comments to maintain a clear history of the review process.
- Always be respectful and constructive. Always acknowledge that the code review comments are written
  by an AI assistant and may not be perfect.

### CI Status Interpretation

When reviewing PRs, be aware of CI jobs that are expected to fail for certain contributors:

- **`internal-build`**: Requires Cloudflare internal access. **Always fails for external
  contributors** — this is not indicative of a build or code problem. Do not flag CI failures from
  this job as issues on PRs from external contributors.

Before attributing a CI failure to a code problem, check whether the PR author is an external
contributor (not a Cloudflare org member). If so, check whether the failing job is access-gated.

### Tools

For interaction with GitHub, use the GitHub CLI (`gh`) tool or `git` as appropriate.