gh-pr-review

name

gh-pr-review

description

Use when reading, posting, or managing PR review comments via the `gh-review` tool: viewing PR comments with filtering, leaving inline comments on specific diff lines, starting or deleting pending reviews, replying to review threads, editing or removing individual review comments. Triggers on phrases like "check for comments", "leave a comment on line X", "start a pending review", "reply to the comment", "edit the comment", "remove that comment", "delete that comment", "fix my comment", "move comment to line X", or any task involving PR comment mechanics. Do NOT use for merging, approving via `gh pr review --approve`, or non-review PR operations. Authoring a full PR review is the `reviewer` subagent's job; it loads this skill itself. Primary agents delegate instead of reviewing inline.

PR Review

All PR comment operations (reading, writing, replying) MUST go through gh-review. Do NOT use raw gh api or gh pr for any review-related task. Run gh-review --help and gh-review <command> --help for authoritative syntax; this skill covers workflow and semantics only.

Unlike gh, gh-review takes the repository as a positional owner/repo argument, NOT a --repo flag. The reading and review-creating commands share the shape gh-review <command> owner/repo NUMBER (e.g. gh-review view sketchy/cortex-backend 2794, gh-review start owner/repo 42).

Critical Rules

• NEVER submit reviews. The user manually submits pending reviews via GitHub UI.
• All new review comments, replies included, MUST go through a pending review. Never post directly.
• Pass Markdown bodies as --body - with a single-quoted heredoc. Double-quoted bodies execute backticks as shell commands before gh-review receives them.
• When a line target is outside diff hunks, comment automatically retries as a file-level comment on the same file. The output includes a note: line indicating the fallback. No manual retry or relocation needed.

Review Etiquette

Tone

• Bugs/defects: Direct language ("I think this is a bug...", "This will cause...")
• Style/architecture: Questions ("What do you think about...", "Would it make sense to...")
• Use contractions, be conversational, comment on code not developer
• Skip comments that just repeat what other reviewers already said
• Bot comments (infer from context: [bot] suffix, known CI/analysis tools, automated comment patterns): use neutral, factual statements. Explain what was done and why, or why something will not be done. Do not address the bot conversationally or phrase replies as if speaking to a person.

Verification

Use ctx7 to verify unfamiliar patterns, best practices, and security implications before writing comments. Use web search when Context7 lacks coverage. Every technical claim must be verified.

Reading a PR

gh-review view hides resolved threads unless you pass --all. Pass it whenever the question is what already happened on the PR: whether a finding was raised before, or whether your own review landed. A published review whose threads were all resolved is invisible without it, which reads as "never posted." --author LOGIN narrows output to one participant.

Inline comments belonging to an unsubmitted review are tagged [pending, unsubmitted], and the PENDING REVIEWS section prints the draft body and each inline comment. Nothing there is visible to anyone else yet.

Pending Review Workflow

1. gh-review view the PR. If the output includes a PENDING REVIEWS section, reuse that PRR_... ID. Otherwise, gh-review start to create one.
2. gh-review comment for each inline comment, passing the review ID.
3. Stop. The user submits the review manually via the GitHub UI.

To discard a pending review: gh-review delete PRR_....

Replying to Comments

gh-review reply adds a threaded reply to an existing review thread as part of a pending review, so it stays invisible until the user submits. It finds the pending review itself; pass --review-id only when more than one exists. With no pending review it errors instead of posting: start one first, and treat replies as part of the same review pass as your inline comments.

--publish skips the pending review and posts the reply immediately. Use it in exactly one case: the PR is the user's own and the comment you are answering came from a bot (CodeRabbit, Copilot, Qodana, any [bot] author). Batching those into a review the user then has to submit on their own PR buys nothing. Every other reply, on someone else's PR or to a human on the user's, MUST go through the pending review.

The COMMENT_ID argument is the numeric database ID shown as #ID in view output headers (e.g. @reviewer (2026-05-14) #98765 PRRC_kwDO...:). Extract the number after #, not the node ID.

Conversation comments (the PR's main timeline) have no thread and cannot be replied to this way.

Editing and Removing Comments

gh-review edit modifies an existing review comment. Two paths depending on what changed:

• Body only (no positioning args): patches the comment in place. One API call.
• Repositioning (any of --path, --line, --start-line, --side, --start-side): deletes the old comment and creates a new one on the same pending review. Requires both --review-id and --line, even when only --path changes (the underlying comment node does not expose its line, so it cannot be inferred). --path and --body are merged from the current comment when omitted; --side defaults to RIGHT rather than being read from the existing comment.

gh-review remove deletes a single review comment.

For pending comments, both commands take the PRRC_... node ID. For published comments and replies, pass OWNER/REPO followed by the numeric comment ID. Published comments support body edits only.

gh-review resolve OWNER/REPO NUMBER COMMENT_ID resolves the thread containing a numeric comment ID. Pass --undo to unresolve it.

Line Targeting

GitHub's API only supports line-level comments on lines within diff hunks (changed lines plus surrounding context). Lines in the gap between hunks cannot be targeted as line comments.

When comment targets a non-diff line, it automatically falls back to a file-level comment on the same file (using subjectType: FILE). The output includes a note: field explaining the fallback. The comment still lands on the correct file; it just appears at the top of the file's diff rather than on a specific line.

To post a file-level comment directly (skipping the line attempt), omit --line:

gh-review comment --review-id PRR_... --path {file} --body '{body}'

Suggestion blocks: Suggestions only work on line-level comments. The --start-line to --line range defines what GitHub replaces when a suggestion is applied. The range MUST exactly match the lines being replaced. Do NOT include surrounding context lines in the range; they will be deleted.

ID Formats

• PRR_...: Review node ID (from start or view)
• PRRT_...: Thread node ID (emitted by comment and resolve; not surfaced by view)
• PRRC_...: Comment node ID (from view review-thread headers or comment output's comment-node-id field); used by edit and remove
• #NNN: Numeric database ID (from view output or comment output's comment-id field); used by reply, published edit and remove, and resolve