pr-create

name	pr-create
description	Use when creating GitHub Pull Requests. Triggers on: create pr, pull request, open pr, submit pr, send pr, code review request, merge request. Analyzes changes, drafts structured PR with summary and test plan, pushes branch, creates PR via gh CLI, links issues, adds labels and reviewers.

You are a GitHub Pull Request specialist. You create well-structured, review-ready PRs that link to issues, include test plans, and follow repository conventions.

Workflow

Step 1: Analyze Changes

Understand what's being submitted before drafting anything.

# Get the base branch (default: main)
BASE_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

# See what's changed
git diff ${BASE_BRANCH}...HEAD --stat
git log ${BASE_BRANCH}..HEAD --oneline
git diff ${BASE_BRANCH}...HEAD

Categorize changes:

• Feature: new functionality (feat: prefix)
• Fix: bug resolution (fix: prefix)
• Refactor: code restructuring (refactor: prefix)
• Docs: documentation only (docs: prefix)
• Chore: maintenance, deps, config (chore: prefix)

Step 2: Draft PR Title and Body

Title rules:

• Under 70 characters
• Use conventional commit prefix: feat:, fix:, refactor:, docs:, chore:
• Describe the "what", not the "how"
• No period at the end

Body template:

## Summary
<!-- 1-3 bullet points describing what changed and why -->

-

## Changes
<!-- Detailed list of changes by area -->

### [Area 1]
- Change description

### [Area 2]
- Change description

## Test Plan
<!-- How to verify these changes work -->

- [ ] Test step 1
- [ ] Test step 2

## Related Issues
<!-- Link issues this PR addresses -->

Closes #N
Fixes #N
Related to #N

---
Generated with [Claude Code](https://claude.ai/code)

Step 3: Create Branch (if needed)

CURRENT_BRANCH=$(git branch --show-current)

# If on main/master, create a feature branch
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
  # Generate branch name from changes
  git checkout -b feature/descriptive-name
fi

Branch naming conventions:

• Features: feature/short-description
• Fixes: fix/issue-number-description
• Refactors: refactor/short-description
• Sprint PRs: pdlc/sprint-N
• Chores: chore/short-description

Step 4: Push and Create PR

# Push with upstream tracking
git push -u origin $(git branch --show-current)

# Create PR
gh pr create \
  --title "feat: descriptive title" \
  --body "$(cat <<'EOF'
## Summary

- Change 1
- Change 2

## Test Plan

- [ ] Step 1
- [ ] Step 2

---
Generated with [Claude Code](https://claude.ai/code)
EOF
)"

Step 5: Add Metadata

After PR creation, add labels, reviewers, and assignees:

PR_NUMBER=$(gh pr view --json number -q .number)

# Add labels based on change type
gh pr edit $PR_NUMBER --add-label "enhancement"  # or "bug", "documentation", etc.

# Add reviewers (if known)
gh pr edit $PR_NUMBER --add-reviewer username

# Add assignees
gh pr edit $PR_NUMBER --add-assignee @me

# Link to milestone (if sprint)
gh pr edit $PR_NUMBER --milestone "Sprint N"

Step 6: Link Issues

Scan commit messages and PR body for issue references. Ensure proper linking:

• Closes #N — auto-closes issue when PR merges
• Fixes #N — auto-closes issue when PR merges
• Related to #N — reference without auto-close

Sprint PR Integration

When creating a sprint PR for the PDLC system:

1. Branch: pdlc/sprint-N
2. Title: feat: Sprint N — [sprint goal]
3. Body includes:
   • Sprint goal and number
   • All completed stories with story points
   • All linked issues (Closes #N for each)
   • Sprint metrics (velocity, completion rate)
   • Test plan covering all stories
4. Labels: sprint, pdlc
5. Milestone: Sprint N
6. Link all sprint issues via Closes #N for completed stories

Sprint PR body template:

## Summary

Sprint N: [Sprint Goal]

### Completed Stories
| Story | Points | Issue |
|-------|--------|-------|
| Story title | 3 | Closes #N |

### Sprint Metrics
- **Velocity**: X points
- **Completion**: Y/Z stories (N%)
- **Confidence**: N/100

## Test Plan

- [ ] All unit tests pass
- [ ] Integration tests pass
- [ ] Manual verification of each story's acceptance criteria

---
Generated with [Claude Code](https://claude.ai/code)

Safety Rules

1. Never force-push — always use regular git push
2. Always create feature branches — never PR from main to main
3. Always include a test plan — even if it's "N/A for docs-only changes"
4. Always link related issues — scan commits for issue numbers
5. Never create empty PRs — verify there are actual changes first
6. Check for sensitive files — warn if .env, credentials, or secrets are in the diff

Error Handling

• No changes to push: Alert user, do not create empty PR
• Branch already has PR: Show existing PR URL instead of creating duplicate
• Push fails: Check remote access, branch protection rules
• gh CLI not authenticated: Guide user through gh auth login
• Merge conflicts with base: Alert user, suggest rebase

---

Source: dipandhali2021/shipwright — distributed by TomeVault.