create-pr-skill.txt

# Example create PR skill

## Layout
```
skills/create-pr
├── references
│   └── pr-best-practices.md
└── SKILL.md
```

======================================================
SKILL.md contents
======================================================

---
name: create-pr
description: Create well-structured pull requests by analyzing git diffs, determining appropriate PR metadata, and using the GitHub CLI. This skill should be used when the user wants to create a pull request from their current branch changes, needs help composing PR descriptions, or wants to streamline the PR creation process.
---

# Create PR

## Overview

This skill enables intelligent pull request creation by analyzing repository changes, determining appropriate PR metadata, and composing comprehensive PR descriptions using the GitHub CLI.

## Workflow

### Step 1: Verify Prerequisites

Before proceeding, check that the GitHub CLI is installed and authenticated:

```bash
# Check if gh is installed
which gh || command -v gh
```

If `gh` is not installed:
1. Inform the user that the GitHub CLI is required
2. Provide installation instructions based on their platform:
   - macOS: `brew install gh`
   - Linux: See https://github.com/cli/cli/blob/trunk/docs/install_linux.md
   - Windows: `winget install --id GitHub.cli` or `choco install gh`
3. After installation, guide them to authenticate: `gh auth login`
4. Wait for user confirmation before proceeding

### Step 2: Analyze Repository State

Gather comprehensive information about the current branch and changes:

```bash
# Check current branch and its tracking status
git status

# Check if current branch tracks a remote
git branch -vv | grep "^\\*"

# List recent commits on this branch compared to base
git log --oneline origin/main..HEAD 2>/dev/null || git log --oneline origin/master..HEAD 2>/dev/null || git log --oneline HEAD~5..HEAD

# View the full diff to understand changes
git diff origin/main...HEAD 2>/dev/null || git diff origin/master...HEAD 2>/dev/null || git diff HEAD~5..HEAD
```

### Step 3: Check for Unpushed Changes

Determine if there are local commits that need to be pushed:

```bash
# Check for unpushed commits
git log --oneline @{u}..HEAD 2>/dev/null || echo "Branch not tracking remote"
```

If unpushed commits exist:
1. Inform the user about the unpushed commits
2. Ask if they want to push the changes now
3. If yes, push with upstream tracking: `git push -u origin <branch-name>`
4. If no, inform them that the PR cannot be created until changes are pushed

### Step 4: Analyze Changes and Determine PR Metadata

Based on the diff analysis, determine:

1. **PR Type** - Analyze the changes to categorize:
   - Feature: New functionality added
   - Fix: Bug fixes or corrections
   - Refactor: Code restructuring without behavior changes
   - Docs: Documentation updates
   - Test: Test additions or modifications
   - Chore: Maintenance tasks, dependency updates
   - Perf: Performance improvements

2. **PR Title** - Create a concise, descriptive title following conventional commit format:
   - `feat: Add user authentication system`
   - `fix: Resolve memory leak in data processor`
   - `refactor: Simplify payment gateway integration`

3. **Breaking Changes** - Check for:
   - API changes that remove or rename public methods
   - Database schema changes
   - Configuration format changes
   - Dependency version major upgrades

4. **Test Requirements** - Identify what testing is needed:
   - Unit tests for new functions
   - Integration tests for API changes
   - Manual testing steps for UI changes

### Step 5: Compose PR Description

Create a comprehensive PR description using this template structure:

```markdown
## Summary
[1-3 sentences explaining what this PR does and why]

## Changes
- [Bulleted list of specific changes made]
- [Group related changes together]
- [Be specific about what was added, modified, or removed]

## Type of Change
- [ ] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] Documentation update
- [ ] Performance improvement
- [ ] Refactoring (no functional changes)

## Testing
- [ ] [Describe testing performed]
- [ ] [List any new tests added]
- [ ] [Note any manual testing steps]

## Breaking Changes
[If applicable, describe any breaking changes and migration steps]

## Related Issues
[Reference any related issues: Fixes #123, Relates to #456]

## Screenshots
[If applicable, add screenshots to help explain your changes]

## Additional Context
[Any other context about the PR that reviewers should know]
```

### Step 6: Confirm with User

Present the composed PR details to the user:

1. Show the determined PR type and title
2. Display the full PR description
3. Show the target branch (typically main or master)
4. Ask for confirmation or modifications

Allow the user to:
- Modify the title or description
- Change the target branch
- Add reviewers or labels
- Cancel the PR creation

### Step 7: Create the Pull Request

Once confirmed, create the PR using the GitHub CLI:

```bash
# Create PR with composed title and body
gh pr create \
  --title "PR Title Here" \
  --body "PR Description Here" \
  --base main  # or master, or user-specified branch

# Optionally add reviewers if requested
gh pr create \
  --title "..." \
  --body "..." \
  --reviewer "username1,username2"

# Optionally add labels if requested
gh pr create \
  --title "..." \
  --body "..." \
  --label "enhancement,needs-review"
```

After creation:
1. Display the PR URL
2. Offer to open it in the browser: `gh pr view --web`
3. Show next steps (review process, CI checks, etc.)

## Best Practices

### Effective PR Titles
- Keep under 72 characters
- Use imperative mood ("Add feature" not "Added feature")
- Be specific but concise
- Include ticket/issue numbers if applicable

### Comprehensive Descriptions
- Explain the "why" not just the "what"
- Include context for reviewers
- Link to relevant documentation or discussions
- Add screenshots for UI changes
- List manual testing steps

### PR Size Guidelines
- Keep PRs focused on a single concern
- Aim for <500 lines of code changes
- Split large features into multiple PRs
- Create draft PRs for work in progress

## References

For detailed PR best practices and additional context, refer to:
- `references/pr-best-practices.md` - Comprehensive guide for writing effective PRs

## Error Handling

Common issues and solutions:

1. **No remote tracking**: Set upstream with `git push -u origin branch-name`
2. **Authentication failed**: Run `gh auth login` to re-authenticate
3. **PR already exists**: Check existing PRs with `gh pr list`
4. **Base branch not found**: Verify branch names with `git branch -r`
5. **Merge conflicts**: Resolve locally first with `git merge origin/main`




======================================================
pr-best-practices.md contents
======================================================


```markdown
# Pull Request Best Practices

## PR Philosophy

A pull request is a conversation about a change. It should tell a complete story about why the change is necessary, what it does, and how it was tested.

## Writing Effective PR Descriptions

### The Summary Section
The summary should answer three questions:
1. **What** is being changed?
2. **Why** is this change necessary?
3. **How** does this solve the problem?

Good example:
> This PR adds rate limiting to the authentication API to prevent brute-force attacks. After analyzing our logs, we identified multiple attempted attacks that could have been prevented with proper rate limiting. This implementation uses a sliding window algorithm to limit users to 5 login attempts per minute.

### The Changes Section
- Group related changes together
- Use present tense ("Add" not "Added")
- Be specific about modifications
- Explain non-obvious changes

Example:
```markdown
## Changes
Authentication:
- Add rate limiting middleware to /auth/login endpoint
- Implement sliding window counter in Redis
- Add rate limit headers to responses

Configuration:
- Add RATE_LIMIT_WINDOW and RATE_LIMIT_MAX_ATTEMPTS env variables
- Update .env.example with new configuration

Testing:
- Add unit tests for rate limiting logic
- Add integration tests for authentication flow with rate limits
```

### Breaking Changes
Always clearly document breaking changes:
- What will break
- Why it's necessary
- Migration steps
- Timeline if deprecating

Example:
```markdown
## Breaking Changes
The `/api/v1/users` endpoint now requires authentication.

**Migration Steps:**
1. Update all API calls to include Authorization header
2. Obtain API tokens from /auth/token endpoint
3. Update client libraries to version 2.0+

**Deprecation Timeline:**
- 2024-01-15: Deprecation warning added
- 2024-02-15: Authentication enforced
```

## PR Patterns by Type

### Feature PRs
Focus on:
- User value and use cases
- Documentation updates needed
- Feature flags or gradual rollout strategy
- Performance implications
- Security considerations

### Bug Fix PRs
Include:
- Root cause analysis
- Steps to reproduce the bug
- How the fix addresses the root cause
- Regression test details
- Affected versions/environments

### Refactoring PRs
Explain:
- Why refactoring is needed now
- What stays the same (behavior/API)
- What improves (performance/maintainability)
- Risk assessment
- Testing strategy to ensure no regressions

### Documentation PRs
Ensure:
- Accuracy of technical details
- Clarity for target audience
- Proper formatting and structure
- Working code examples
- Updated diagrams if applicable

## Commit Message Formats

### Conventional Commits
```
<type>(<scope>): <subject>

<body>

<footer>
```

Types:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation only
- `style`: Code style (formatting, missing semicolons)
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `test`: Adding missing tests
- `chore`: Maintenance tasks
- `build`: Changes to build system
- `config`: Changes to CI configuration

Examples:
- `feat(auth): add OAuth2 authentication`
- `fix(api): resolve memory leak in data processor`
- `docs(readme): update installation instructions`
- `refactor(payments): simplify transaction handling`

### Scope Guidelines
- Use component/module names
- Keep it concise (one word when possible)
- Be consistent across the project
- Common scopes: api, ui, auth, db, config, deps

## Review Readiness Checklist

Before marking PR ready for review:

### Code Quality
- [ ] Code follows project style guidelines
- [ ] No commented-out code
- [ ] No debug prints or console.logs
- [ ] Meaningful variable and function names
- [ ] Complex logic has comments

### Testing
- [ ] All tests pass locally
- [ ] New features have tests
- [ ] Bug fixes have regression tests
- [ ] Edge cases are tested
- [ ] Performance impact measured if applicable

### Documentation
- [ ] API changes documented
- [ ] README updated if needed
- [ ] Inline comments for complex logic
- [ ] CHANGELOG updated
- [ ] Migration guide for breaking changes

### PR Hygiene
- [ ] PR has descriptive title
- [ ] PR has comprehensive description
- [ ] Related issues are linked
- [ ] Commits are logical and atomic
- [ ] No merge commits (rebase instead)
- [ ] PR is focused on single concern
- [ ] Sensitive data is not exposed

## Tips for Faster Reviews

1. **Keep PRs Small**
   - Aim for <500 lines of changes
   - Split large features into multiple PRs
   - Create "stacked" PRs that build on each other

2. **Make It Easy to Review**
   - Add review comments explaining complex parts
   - Include before/after screenshots for UI changes
   - Provide testing instructions
   - Link to relevant documentation

3. **Be Responsive**
   - Address feedback promptly
   - Ask questions if feedback is unclear
   - Re-request review after making changes

4. **Use Draft PRs**
   - Create early for visibility
   - Get feedback on approach
   - Mark ready when complete

## Common Anti-Patterns to Avoid

### The Monster PR
- Too many changes in one PR
- Multiple unrelated changes
- Difficult to review thoroughly
- Higher risk of bugs

### The Mystery PR
- Vague title like "Fix stuff"
- No description
- No context for reviewers
- Unclear what problem it solves

### The Never-Ending PR
- Keeps growing with new changes
- Review feedback leads to scope creep
- Becomes stale and conflicts arise
- Consider closing and starting fresh

### The Rushed PR
- Skipped tests
- No documentation
- Bypassed CI checks
- "I'll fix it later" mentality

## Template Examples

### Feature PR Template
```markdown
## Summary
This PR implements [feature name] to address [user need/problem].

## Motivation
- Current limitation: [describe current state]
- User impact: [how users are affected]
- Proposed solution: [brief overview]

## Implementation Details
- [Key technical decisions]
- [Architecture changes]
- [New dependencies]

## Testing
- [x] Unit tests for [components]
- [x] Integration tests for [flows]
- [x] Manual testing steps completed
- [x] Performance benchmarks run

## Documentation
- [x] API documentation updated
- [x] User guide updated
- [x] Migration guide (if applicable)

## Screenshots/Demo
[Include relevant visuals]

## Rollout Plan
- [ ] Feature flag: `enable_new_feature`
- [ ] Gradual rollout to X% of users
- [ ] Monitoring alerts configured
```

### Bug Fix PR Template
```markdown
## Summary
Fixes [issue description] that was causing [user impact].

## Root Cause
[Explain what was broken and why]

## Solution
[Explain how the fix works]

## Reproduction Steps
1. [Step to reproduce]
2. [Another step]
3. [Expected vs actual behavior]

## Testing
- [x] Regression test added
- [x] Manually verified fix in [environment]
- [x] No side effects identified

## Affected Versions
- Introduced in: v2.3.0
- Affects: v2.3.0 - v2.5.1
- Fixed in: v2.5.2
```

## Post-PR Best Practices

### After Approval
1. Squash commits if needed
2. Update branch with latest changes
3. Verify CI still passes
4. Monitor after deployment

### After Merge
1. Delete feature branch
2. Update related documentation
3. Close related issues
4. Notify stakeholders if needed
5. Monitor for issues
```