What is a pending review and why use it?

A pending review collects comments before final submission; it prevents automatic submission and lets humans review and approve first.

How should PR comments be styled?

Follow lowercase start, short sentences, avoid complex punctuation, and remain polite and concise.

What if a comment is not a valid concern?

Draft a concise response explaining why it may not require a change, and search for other occurrences of the issue before deciding next steps.

pr-comment-workflow

Scanned

npx machina-cli add skill fcakyon/claude-codex-settings/pr-comment-workflow --openclaw

Files (1)

SKILL.md

1.8 KB

PR Comment Workflow

Procedural knowledge for writing and responding to PR review comments.

Comment Style Rules

lowercase start for all sentences
no em-dashes, no complex sentences
simple terms, concise
no end-of-sentence punctuation if possible
max 1 sentence or shorter per comment
polite when responding to real people
few words is enough for automated bot comments

Review Comment Rules

Only create pending PR comments, never submit/confirm review automatically
Leave all comments for human review before posting
When creating review comments, follow the style rules above

Pending Review API Workflow

When posting review comments via gh api, use the two-step pending flow:

Create pending review: gh api repos/{owner}/{repo}/pulls/{number}/reviews -f event=PENDING -f body=""
Add comments to pending review: gh api repos/{owner}/{repo}/pulls/{number}/reviews/{review_id}/comments -f body="..." -f path="..." -F line=N -f side=RIGHT
Never call the submit endpoint — leave for human to review and submit
Output the review URL so user can review and submit manually

Resolving Review Feedback

Fetch unresolved comments from PR
For each comment, decide if valid concern or not
If valid: fix the code AND search for same problem in other codebase locations — fix all occurrences
If not valid: draft a concise response
If automated bot comment: few words response is enough
Present all draft responses to user before posting

Source

git clone https://github.com/fcakyon/claude-codex-settings/blob/main/plugins/github-dev/skills/pr-comment-workflow/SKILL.md

View on GitHub

Overview

This skill provides procedural guidance for writing and responding to PR review comments. It covers style rules, the two-step pending review flow, and how to resolve feedback effectively.

How This Skill Works

it enforces a simple commenting style: lowercase start, concise sentences, no end punctuation when possible. it uses a two-step pending flow for PR reviews using gh api: create a pending review, then add comments, never submit automatically. for resolving feedback, fetch unresolved comments, decide validity, fix code where needed, and draft concise responses before posting.

When to Use It

address PR comments or review feedback
draft responses to reviewer questions
write or refine a PR comment
get guidance on PR comment style and response drafting
prepare and manage the two-step pending review flow with gh api

Quick Start

Step 1: Identify unresolved or flagged comments in the PR
Step 2: Create a pending review and draft concise responses or fixes for each
Step 3: Share the pending review URL with collaborators and wait for human submission

Best Practices

start sentences lowercase in PR comments
keep comments concise with ideally one sentence each
be polite when replying to real people
use the two-step pending review flow and never auto-submit
present all draft responses to the user before posting

Example Use Cases

address a reviewer’s suggestion about variable naming with a concise, lowercase comment
reply to a blocking bug finding with a short, factual response and plan to fix
draft a neutral comment requesting clarification on a design decision
identify duplicates of a reported issue across the codebase and propose a fix for all occurrences
create a pending review, attach comments, and share the review URL for team review

Frequently Asked Questions

Add this skill to your agents