# Skill: Pull Requests

Manage GitHub pull requests — create, list, view, review, merge, and manage the full PR lifecycle.

## Commands Reference

### List Pull Requests

```bash
# List open PRs (default)
gh pr list --json number,title,headRefName,author,reviewDecision,createdAt --limit 30

# Filter by state
gh pr list --state closed --json number,title,mergedAt --limit 20
gh pr list --state merged --json number,title,mergedAt --limit 20
gh pr list --state all --json number,title,state --limit 50

# Filter by label
gh pr list --label "ready-for-review" --json number,title,labels

# Filter by assignee
gh pr list --assignee "@me" --json number,title,headRefName

# Filter by author
gh pr list --author "username" --json number,title

# Filter by base branch
gh pr list --base main --json number,title,headRefName

# Filter by head branch
gh pr list --head "feature/login" --json number,title

# Filter by draft status
gh pr list --draft --json number,title,headRefName

# Search with GitHub query syntax
gh pr list --search "is:open review:required" --json number,title,reviewDecision
gh pr list --search "is:open draft:false label:ready" --json number,title
```

### View a Pull Request

```bash
# Full detail
gh pr view 42 --json number,title,body,state,headRefName,baseRefName,author,reviewDecision,mergeable,labels,assignees,reviewRequests,comments,additions,deletions,changedFiles

# Check merge status
gh pr view 42 --json mergeable,mergeStateStatus --jq '{mergeable: .mergeable, status: .mergeStateStatus}'

# Get review decision
gh pr view 42 --json reviewDecision --jq '.reviewDecision'

# See the diff
gh pr diff 42

# Diff for specific file
gh pr diff 42 -- src/main.ts

# View CI checks status
gh pr checks 42
gh pr checks 42 --json name,state,conclusion --jq '.[] | "\(.name): \(.conclusion // .state)"'
```

### Create a Pull Request

```bash
# Basic PR from current branch
gh pr create --title "Add user authentication" --body "Implements JWT-based auth.

## Changes
- Added login endpoint
- Added token refresh logic
- Added auth middleware

Closes #42"

# With explicit base and head
gh pr create \
  --base main \
  --head feature/auth \
  --title "Add user authentication" \
  --body "Implements JWT-based auth. Closes #42"

# Draft PR
gh pr create \
  --title "WIP: New dashboard" \
  --body "Work in progress — not ready for review yet." \
  --draft

# With reviewers and assignees
gh pr create \
  --title "Fix memory leak in worker pool" \
  --body "Fixes the leak reported in #38." \
  --reviewer "alice,bob" \
  --assignee "@me" \
  --label "bug,performance"

# With milestone
gh pr create \
  --title "Update API schema" \
  --body "Breaking change for v3 API." \
  --milestone "v3.0"

# Body from file
gh pr create --title "Large refactor" --body-file ./PR_DESCRIPTION.md

# Generate title and body from commits
gh pr create --fill

# Fill title from commits but provide custom body
gh pr create --fill-first --body "Additional context beyond commit messages."

# Create in a different repo (push branch first)
gh pr create -R owner/repo --head "my-fork:feature-branch" --title "Cross-fork PR" --body "Details"
```

### Review a Pull Request

```bash
# Approve
gh pr review 42 --approve --body "LGTM! Clean implementation."

# Request changes
gh pr review 42 --request-changes --body "A few issues to address:
- The error handling in auth.ts needs a fallback
- Missing unit tests for the edge case in #L42"

# Comment (without approving or requesting changes)
gh pr review 42 --comment --body "Looks good overall. One question about the caching strategy."
```

### Merge a Pull Request

```bash
# Merge commit (default)
gh pr merge 42 --merge

# Squash merge
gh pr merge 42 --squash

# Rebase merge
gh pr merge 42 --rebase

# Delete branch after merge
gh pr merge 42 --squash --delete-branch

# Custom squash commit subject and body
gh pr merge 42 --squash --subject "feat: add auth (#42)" --body "Implements JWT authentication"

# Auto-merge (merge when checks pass)
gh pr merge 42 --auto --squash

# Disable auto-merge
gh pr merge 42 --disable-auto
```

### Edit a Pull Request

```bash
# Update title
gh pr edit 42 --title "feat: Add user authentication"

# Update body
gh pr edit 42 --body "Updated description..."

# Add/remove labels
gh pr edit 42 --add-label "ready-for-review"
gh pr edit 42 --remove-label "wip"

# Add/remove reviewers
gh pr edit 42 --add-reviewer "alice,bob"
gh pr edit 42 --remove-reviewer "charlie"

# Change assignees
gh pr edit 42 --add-assignee "@me"

# Set base branch
gh pr edit 42 --base develop

# Set milestone
gh pr edit 42 --milestone "v2.0"

# Mark ready for review (un-draft)
gh pr ready 42
```

### Close / Reopen

```bash
# Close without merging
gh pr close 42

# Close with comment
gh pr close 42 --comment "Superseded by #55"

# Delete branch on close
gh pr close 42 --delete-branch

# Reopen
gh pr reopen 42
```

### Checkout a PR Locally

```bash
# Checkout PR branch
gh pr checkout 42

# Checkout with custom local branch name
gh pr checkout 42 --branch "review/auth-feature"

# Checkout and detach (don't create local branch)
gh pr checkout 42 --detach
```

### PR Comments

```bash
# Add a comment
gh pr comment 42 --body "CI is green now, ready for re-review."

# Comment from file
gh pr comment 42 --body-file ./review-notes.md
```

## Workflows

### Feature Branch PR Workflow

```bash
# 1. Create branch and make changes
git checkout -b feature/new-endpoint
# ... make changes, commit ...

# 2. Push and create PR
git push -u origin feature/new-endpoint
gh pr create \
  --title "feat: Add /users endpoint" \
  --body "Adds CRUD operations for users. Closes #15." \
  --label "enhancement" \
  --reviewer "team-lead"

# 3. Check CI status
gh pr checks <pr-number>

# 4. After approval, merge
gh pr merge <pr-number> --squash --delete-branch
```

### Code Review Workflow

```bash
# 1. List PRs needing your review
gh pr list --search "is:open review-requested:@me" --json number,title,author,createdAt

# 2. Checkout and review
gh pr checkout 42
gh pr diff 42

# 3. Check the CI status
gh pr checks 42

# 4. Submit review
gh pr review 42 --approve --body "Looks good. Nice test coverage."
# or
gh pr review 42 --request-changes --body "Please fix the SQL injection vulnerability on line 55."
```

### Stacked PRs Workflow

```bash
# PR 1: base feature
gh pr create --base main --head feature/base --title "feat: base infrastructure" --body "Foundation for the feature"

# PR 2: builds on PR 1
gh pr create --base feature/base --head feature/extension --title "feat: extend base" --body "Builds on #<pr1-number>"

# After PR 1 merges, rebase PR 2 onto main
gh pr edit <pr2-number> --base main
```

### Auto-Merge Workflow

Set up a PR to merge automatically once all required checks pass:

```bash
# Create PR with auto-merge enabled
gh pr create \
  --title "chore: update dependencies" \
  --body "Routine dependency update" \
  --label "dependencies"

# Enable auto-merge on existing PR
gh pr merge 42 --auto --squash --delete-branch
```

### Draft to Ready Workflow

```bash
# Create as draft while work is in progress
gh pr create --draft --title "WIP: Redesign settings page" --body "Not ready for review yet"

# When ready, mark for review
gh pr ready <number>
gh pr edit <number> --add-reviewer "designer,frontend-lead"
```

## Available JSON Fields

Use these with `--json`:

`additions`, `assignees`, `author`, `autoMergeRequest`, `baseRefName`, `body`, `changedFiles`, `closed`, `closedAt`, `comments`, `commits`, `createdAt`, `deletions`, `files`, `headRefName`, `headRefOid`, `headRepository`, `headRepositoryOwner`, `id`, `isCrossRepository`, `isDraft`, `labels`, `latestReviews`, `maintainerCanModify`, `mergeCommit`, `mergeStateStatus`, `mergeable`, `mergedAt`, `mergedBy`, `milestone`, `number`, `potentialMergeCommit`, `projectCards`, `reactionGroups`, `reviewDecision`, `reviewRequests`, `reviews`, `state`, `statusCheckRollup`, `title`, `updatedAt`, `url`

## Tips

- Use `--fill` to auto-generate title/body from commit messages for quick PRs.
- `gh pr checks` shows CI status without needing to visit the web UI.
- `gh pr merge --auto` is powerful for dependency update PRs that just need green CI.
- Use `reviewDecision` field to quickly filter PRs by review status: `APPROVED`, `CHANGES_REQUESTED`, `REVIEW_REQUIRED`.
- `mergeStateStatus` indicates if a PR can be merged: `CLEAN`, `DIRTY`, `BLOCKED`, `BEHIND`, `UNSTABLE`.
- Always use `--delete-branch` with merge to keep the repo clean.
- For large diffs, use `gh pr diff 42 -- <path>` to focus on specific files.