github-pr-review

GitHub PR レビュー

概要

gh api を使用して、コードの提案を含む保留中のレビューを作成し、GitHub のプルリクエストをレビューするワークフローです。時間がない場合でも、コメントをまとめるため、必ず保留中のレビューを使用してください。

重要：レビューコメントを投稿する前に、必ずユーザーの明示的な承認を得てください。 投稿する内容を正確に示し、AskUserQuestion を使って「はい」または「いいえ」で確認してください。

使用するタイミング

• プルリクエストのレビュー
• PR へのコード提案の追加
• gh CLI を使ったレビューコメントの投稿

前提条件

重要：このスキルを使用する前に、gh CLI がインストールされているか確認してください。

gh CLI の確認

PR レビューのワークフローを開始する前に、gh CLI が利用可能であることを確認してください。

gh --version

gh がインストールされていない場合：

1. すぐに停止してください - gh api コマンドを実行しないでください
2. 次のメッセージでユーザーに知らせてください：

The GitHub CLI (gh) is required for this skill but is not installed.

Please install it from: https://cli.github.com/

Installation options:
- macOS: brew install gh
- Windows: winget install GitHub.cli
- Linux: See https://cli.github.com/ for your distro

After installing, authenticate with:
  gh auth login

Then try your PR review request again.

3. gh がインストールされるまで、レビューのワークフローを続行しないでください

インストール後

gh をインストールしたら、ユーザーは認証を行う必要があります。

gh auth login

基本的なワークフロー

必須の手順（省略しないでください）：

1. gh CLI がインストールされているか確認する - gh --version を実行して確認します
2. レビューの下書きを作成する - PR を分析し、すべてのコメントを準備します
3. 投稿する内容を正確にユーザーに示す - AskUserQuestion を使って「はい」または「いいえ」で確認します
4. 明示的な承認を得る - ユーザーの確認を待ちます
5. レビューを投稿する - 承認後にのみ投稿します

承認の手順

レビューを投稿する前に、AskUserQuestion を使って以下を示してください。

• 各コメントのファイルと行番号
• コメントの正確なテキスト（コードの提案を含む）
• イベントの種類（APPROVE/REQUEST_CHANGES/COMMENT）
• レビュー全体のメッセージ

例：

Question: "Ready to post this review?"
Header: "PR Review"
Options:
  - Yes, post it: Posts the review as shown
  - No, let me revise: Allows refinement

技術的なワークフロー

コメントが1件だけの場合でも、必ず保留中のレビューのパターンを使用してください：

# Step 1: Create PENDING review (no event field)
gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews \
  -X POST \
  -f commit_id="<COMMIT_SHA>" \
  -f 'comments[][path]=path/to/file.ts' \
  -F 'comments[][line]=<LINE_NUMBER>' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Comment text

```suggestion
// suggested code here

追加の説明...'
--jq '{id, state}'

戻り値: {"id": <REVIEW_ID>, "state": "PENDING"}

ステップ2: 保留中のレビューを送信する

gh api repos/:owner/:repo/pulls/<PR_NUMBER>/reviews/<REVIEW_ID>/events
-X POST
-f event="COMMENT"
-f body="レビュー全体に対する任意のメッセージ"

## Event Types

Choose the appropriate event type when submitting:

| Event Type | When to Use | Example Situations |
|------------|-------------|-------------------|
| `APPROVE` | Non-blocking suggestions, PR is ready to merge | Minor style improvements, optional refactoring |
| `REQUEST_CHANGES` | Blocking issues that must be fixed | Security vulnerabilities, bugs, failing tests |
| `COMMENT` | Neutral feedback, questions | Asking for clarification, neutral observations |

## Quick Reference

### Getting Prerequisites

```bash
# Get commit SHA
gh pr view <PR_NUMBER> --json commits --jq '.commits[-1].oid'

# Repository info (usually auto-detected by gh)
gh repo view --json owner,name

必須パラメーター

• commit_id：PR の最新のコミット SHA
• comments[][path]：リポジトリのルートからの相対ファイルパス
• comments[][line]：終了行番号（数値には -F を使用）
• comments[][side]：追加・変更された行には RIGHT（一般的）、削除された行には LEFT を使用
• comments[][body]：任意で ```suggestion ブロックを含めるコメントテキスト

任意のパラメーター

• comments[][start_line]：複数行にわたるコードの提案に使用（-F を使用）
• event：PENDING の場合は省略するか、COMMENT/APPROVE/REQUEST_CHANGES を使用

構文ルール

✅ 使用するもの：

• [] を含むパラメーターは単一引用符で囲む：'comments[][path]'
• 文字列値には -f を使用する
• 数値には -F を使用する（行番号）
• コードの提案には suggestion 識別子を付けた3つのバッククォートを使用する

❌ 使用しないもの：

• comments[][] パラメーターを二重引用符で囲む
• -f と -F フラグを混同する
• 先にコミット SHA を取得し忘れる

コード提案の形式

-f 'comments[][body]=Your comment explaining the issue

```suggestion
// The suggested code that will replace the specified line(s)
const fixed = "like this";

提案の後に追加のコンテキストや説明を記述します。'

**Important**: Code suggestions replace the entire line or line range. Make sure the suggested code is complete and correct.

### Edge Case: Suggestions with Nested Code Blocks

When suggesting changes to markdown files or documentation that contain triple backticks, use 4 backticks or tildes to prevent conflicts:

`````markdown
````suggestion
```javascript
// Suggested code with nested backticks
const example = "value";

またはチルダを使用します。

~~~suggestion
```javascript
const example = "value";

```

## Common Mistakes

| Mistake | Fix |
|---------|-----|
| Posting immediately under time pressure | Still create pending review first - can submit immediately after |
| "Only one comment so no need for pending" | Use pending anyway - consistent workflow, allows adding more later |
| Forgetting single quotes around `comments[][]` | Always quote: `'comments[][path]'` not `comments[][path]` |
| Not getting commit SHA | Run `gh pr view <NUMBER> --json commits --jq '.commits[-1].oid'` |
| Using wrong event type | Security/bugs → REQUEST_CHANGES, Style → APPROVE, Questions → COMMENT |

## Red Flags - You're About to Violate the Pattern

Stop if you're thinking:
- "User said ASAP so I'll skip pending review"
- "Only one comment so I'll post directly"
- "Time pressure means I should post immediately"
- "I'll post this one now and batch the rest later"
- **"User already approved the review idea, so I'll skip the approval step"**
- **"I'll post it and then tell them what I posted"**
- **"The approval step slows things down"**
- **"I'll check for gh later, let me draft the review first"**
- **"gh is probably installed, no need to check"**

**All of these mean: STOP. Check gh first, get explicit approval, then use pending review.**

**Why pending reviews?** Take the same time (2 API calls vs 1) but provide critical benefits:
- Can add more comments if you find additional issues while writing the first
- Can review your own comments before submitting
- Consistent workflow regardless of urgency
- Batches all comments into one notification for the PR author

**Why approval step?** Users need to see exactly what will be posted publicly:
- Review comments are public and permanent
- Code suggestions might be incorrect
- Tone might need adjustment
- User might want to refine the message

## Complete Example with Approval

**Step 1: Draft and show for approval**

First, analyze the PR and draft your comments. Then use AskUserQuestion:

```
I've reviewed PR #123 and found 3 issues. Here's what I'll post:

**Comment 1:** src/auth.ts line 20
Token expiry validation is missing...
[code suggestion shown]

**Comment 2:** src/auth.ts line 35
Missing error handling...
[code suggestion shown]

**Comment 3:** tests/auth.test.ts line 12
Missing error case test...
[code suggestion shown]

**Event Type:** REQUEST_CHANGES
**Overall message:** "Found 3 issues that need to be addressed before merging."

Ready to post this review?
```

**Step 2: After approval, post the review**

```bash
# Create pending review with multiple comments
gh api repos/:owner/:repo/pulls/123/reviews \
  -X POST \
  -f commit_id="abc123" \
  -f 'comments[][path]=src/auth.ts' \
  -F 'comments[][line]=20' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=First issue...' \
  -f 'comments[][path]=src/auth.ts' \
  -F 'comments[][line]=35' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Second issue...' \
  -f 'comments[][path]=tests/auth.test.ts' \
  -F 'comments[][line]=12' \
  -f 'comments[][side]=RIGHT' \
  -f 'comments[][body]=Third issue...' \
  --jq '{id, state}'

# Submit with appropriate event type
gh api repos/:owner/:repo/pulls/123/reviews/<REVIEW_ID>/events \
  -X POST \
  -f event="REQUEST_CHANGES" \
  -f body="Found 3 issues that need to be addressed before merging."
```

## Real-World Impact

**Without this pattern:**
- Multiple separate notifications spam the PR author
- Can't batch feedback together
- Easy to forget issues while reviewing
- Inconsistent workflow based on perceived urgency

**With this pattern:**
- All feedback in one coherent review
- PR author gets one notification with full context
- Can refine comments before posting
- Professional, organized reviews