pr

name	pr
description	Create or update pull requests following best practices. Use when opening a PR, updating an existing PR, preparing changes for review, or running gh pr create.
user-invocable	true

Pull Requests

Follow these standards when creating or updating PRs.

Before Creating/Updating

1. Verify All Checks Pass

Run your project's standard checks:

# Examples - adapt to your project
npm test              # JavaScript/TypeScript
cargo test            # Rust
pytest                # Python
go test ./...         # Go

2. Review Your Changes

git status
git diff main...HEAD
git log main..HEAD --oneline

3. Inspect Commit History

Before drafting the PR, review the commit history for reviewability:

git log main..HEAD --oneline

Check whether commits are:

• Small and cohesive — each commit is one logical change
• Well-separated — mechanical changes (renames, formatting, imports) are in their own commits, not mixed with behavioral changes
• Intelligible — a reviewer reading commit-by-commit can follow the narrative

If the history is messy (e.g. "WIP", fixup commits scattered around, unrelated changes lumped together), suggest reworking it before creating the PR. Ask the user if they'd like you to do an interactive rebase to clean things up.

PR Title Guidelines

Do:

• Be specific and descriptive
• Keep under 72 characters
• Use plain language — no conventional commit prefixes (feat:, fix:, etc.)

Don't:

• Use emoji in titles
• Use vague titles like "Updates" or "Fixes"
• Include issue numbers in the title (put in body)

PR Description Structure

Template priority

1. Repo template — check for .github/PULL_REQUEST_TEMPLATE.md (or .github/PULL_REQUEST_TEMPLATE/ directory) in the current repo. If present, read it and use it as the structure.
2. Default template — if no repo template exists, read ~/.claude/skills/pr/PULL_REQUEST_TEMPLATE.md and use it as the structure.

You MUST read the template file and use its exact sections. Do not hardcode or guess the format — always read the file. Populate each section based on the actual changes — never leave placeholder text.

Commit-based review callout

If the PR has multiple commits organized for reviewability, add this callout at the top of the description (before the Summary):

> **Note:** This PR is best reviewed commit-by-commit.

What NOT to Include

Never mention in PR descriptions:

• "All tests passing"
• "Linting is clean"
• "No warnings"
• Any CI-related status

These are enforced by CI and mentioning them adds zero value.

Validation Steps Section

This section is ONLY for manual verification steps reviewers can follow:

Good:

## Validation Steps

1. Run `npm start` and navigate to /settings
2. Click the "Dark Mode" toggle
3. Verify the theme changes immediately

Bad:

## Validation Steps

- All tests pass
- Ran eslint with no warnings

Creating a PR

Always create PRs as drafts by default. Only create a ready-for-review PR if the user explicitly asks.

1. Read the template file (see "Template priority" above)
2. Push the branch and create the PR:

git push -u origin trevor/your-branch-name

# Use the template sections you read — pass body via HEREDOC
gh pr create --draft \
  --title "your descriptive title" \
  --body "$(cat <<'EOF'
...populated template sections...
EOF
)"

Do NOT hardcode the PR body format — always read and follow the template.

Updating a PR

When the user asks to update an existing PR, use gh pr edit to modify the title and/or body. Push any new commits first.

# Push new commits
git push

# Update the PR title and/or body
gh pr edit --title "updated title" --body "$(cat <<'EOF'
...updated body...
EOF
)"

If only the description needs updating, omit --title. If only the title needs updating, omit --body.

After Creating/Updating

1. Verify the PR looks correct on GitHub
2. Check that CI starts running
3. Address any review feedback promptly
4. Update PR title/description if you push additional commits

Checklist

• All tests pass locally
• Linting/formatting is clean
• Commit history is clean and reviewable (see step 3 above)
• PR is created as draft (unless explicitly told otherwise)
• PR title is descriptive — no emoji, no conventional commit prefixes
• Summary explains what and why
• Changes section lists specifics
• Validation Steps has actionable steps
• No CI status mentioned in description
• "Best reviewed commit-by-commit" callout added if multiple commits