creating-pull-requests

What this skill does

# Creating Pull Requests

You are activating pull request creation capabilities. Your role is to create comprehensive, reviewer-friendly PRs that accelerate the review process.

## When to Activate

This skill activates when:

- User says "create PR", "make pull request"
- User says "ready to merge" or "ready for review"
- Feature work is complete and tests pass
- User asks about PR best practices
- Significant changes are ready to share

## PR Philosophy

### Why Quality PRs Matter

- **Faster Reviews**: Clear context = quick approval
- **Better Feedback**: Reviewers understand intent
- **Knowledge Sharing**: PRs document decisions
- **Future Reference**: PRs are searchable history
- **Team Culture**: Quality PRs encourage quality code

### PR Best Practices

1. **Small & Focused**: One thing per PR
2. **Clear Context**: Why this change matters
3. **Test Coverage**: Prove it works
4. **Reviewer Friendly**: Easy to review
5. **Self-Review First**: Catch obvious issues

## PR Creation Process

### 1. Analyze Changes

Understand what's being submitted:

```bash
# Check current branch and status
git status
git branch --show-current

# See all commits since divergence from base branch
git log main..HEAD --oneline

# View full diff from base branch
git diff main...HEAD

# Check for staged/unstaged changes
git diff HEAD
git diff --staged
```

**Key Questions**:

- What feature/fix does this implement?
- What's the scope of changes?
- Are there related commits?
- Is everything committed?

### 2. Verify Quality

Ensure PR is ready:

```bash
# Run tests
npm test  # or pytest, cargo test, etc.

# Run linting
npm run lint  # or ruff check, cargo clippy, etc.

# Check builds
npm run build  # if applicable
```

**Pre-flight Checklist**:

- [ ] All tests pass
- [ ] Linting passes
- [ ] No unintended changes
- [ ] No debug code/comments
- [ ] No secrets/credentials
- [ ] Branch is up to date with main

### 3. Craft PR Description

Create comprehensive description:

```markdown
## Summary

[2-3 sentences describing what this PR does and why]

## Changes

- [Key change 1]
- [Key change 2]
- [Key change 3]

## Motivation

[Why this change is needed. Link to issue if applicable.]

## Implementation Details

[Any non-obvious decisions or tradeoffs]

## Testing

- [ ] Unit tests added/updated
- [ ] Integration tests pass
- [ ] Manual testing completed
- [ ] Edge cases covered

## Screenshots/Videos

[If UI changes, include before/after screenshots]

## Breaking Changes

[If any, describe and provide migration guide]

## Rollout Plan

[For significant changes: how will this be deployed?]

## Related

- Fixes #[issue number]
- Related to #[issue number]
- Depends on #[pr number]
```

### 4. Create PR

Push and create:

```bash
# Push to remote (with tracking if needed)
git push -u origin feature-branch

# Create PR with gh CLI
gh pr create \
  --title "Clear, descriptive title" \
  --body "$(cat <<'EOF'
[PR description from step 3]
EOF
)"
```

### 5. Self-Review

Review your own PR first:

- Read the diff as if you're the reviewer
- Check for embarrassing mistakes
- Ensure all changes are intentional
- Add comments explaining complex parts

## PR Title Guidelines

### Format

```
<type>: <short description>
```

**Types**:

- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation only
- `refactor:` Code restructuring (no behavior change)
- `perf:` Performance improvement
- `test:` Adding/fixing tests
- `chore:` Maintenance tasks

**Examples**:

- ✅ `feat: Add user authentication with JWT`
- ✅ `fix: Resolve race condition in cache invalidation`
- ✅ `refactor: Extract payment logic into separate module`
- ❌ `Update stuff` (vague)
- ❌ `WIP` (not ready for review)
- ❌ `Fix bug` (which bug?)

### Good Titles

- **Descriptive**: What changed, not just where
- **Concise**: 50-72 characters
- **Action-oriented**: Start with verb
- **Specific**: Enough context to understand

## PR Description Template

### Comprehensive Template

```markdown
# [Feature/Fix Name]

## Summary

[1-2 paragraph overview of what this PR does and why it matters]

## Problem

[What problem does this solve? What was broken/missing?]

## Solution

[High-level approach taken. Why this approach?]

## Changes

### Added

- [New feature 1]
- [New feature 2]

### Changed

- [Modified behavior 1]
- [Modified behavior 2]

### Removed

- [Deleted code/feature]

### Fixed

- [Bug fix 1]
- [Bug fix 2]

## Implementation Details

### Key Decisions

1. **[Decision 1]**: [Why this choice?]
2. **[Decision 2]**: [Tradeoffs considered]

### Tradeoffs

- **Chose X over Y because**: [Reasoning]
- **Accepted limitation**: [What and why]

### Alternative Approaches Considered

- **Approach A**: [Why not chosen]
- **Approach B**: [Why not chosen]

## Testing

### Test Coverage

- Unit tests: [X% or list of tests]
- Integration tests: [Description]
- Manual testing: [What was tested]

### Test Plan for Reviewers

1. [Step 1]
2. [Step 2]
3. [Expected result]

### Edge Cases Tested

- [ ] Empty input
- [ ] Large input
- [ ] Concurrent requests
- [ ] Error conditions

## Performance Impact

- Memory: [Impact]
- CPU: [Impact]
- Network: [Impact]
- Database: [Query count changes]

## Security Considerations

- [ ] No sensitive data logged
- [ ] Input validation added
- [ ] Authentication/authorization checked
- [ ] No new security vulnerabilities

## Breaking Changes

[If any, list them with migration guide]

**Migration Guide**:
```

// Before
oldMethod();

// After
newMethod();

```

## Deployment Notes

- [ ] Database migrations needed
- [ ] Configuration changes required
- [ ] Dependencies updated
- [ ] Feature flags to toggle

## Screenshots

[For UI changes]

**Before**:
[Screenshot]

**After**:
[Screenshot]

## Checklist

- [ ] Tests pass locally
- [ ] Linting passes
- [ ] Documentation updated
- [ ] No console.log/print statements
- [ ] No commented-out code
- [ ] Self-reviewed the diff
- [ ] Breaking changes documented

## Related

- Closes #[issue]
- Related to #[issue/pr]
- Blocks #[issue/pr]
- Blocked by #[issue/pr]

---

Generated with Claude Code
```

### Minimal Template (Small PRs)

```markdown
## Summary

[Brief description of changes]

## Changes

- [Change 1]
- [Change 2]

## Testing

- [ ] Tests added/updated
- [ ] Manually tested

## Related

- Fixes #[issue]

---

Generated with Claude Code
```

## Size Guidelines

### Ideal PR Sizes

- **Small** (< 200 lines): Easy to review, fast approval
- **Medium** (200-500 lines): Manageable, good context
- **Large** (500-1000 lines): Needs extra effort to review
- **Too Large** (> 1000 lines): Consider splitting

### When to Split PRs

Split if:

- Multiple unrelated changes
- Can be deployed independently
- Large refactor + feature addition
- Different reviewers needed for different parts

**Example Split**:

```
Original: "Rewrite authentication and add OAuth"

Split into:
1. PR: Refactor existing auth to be more modular
2. PR: Add OAuth support on top of refactored auth
```

## Review Considerations

### Make It Easy to Review

**Add Comments to Complex Code**:

```python
def complex_algorithm(data):
    # Review note: Using binary search here because data is pre-sorted
    # from database query (see line 45). Time complexity: O(log n)
    result = binary_search(data, target)
    return result
```

**Break Into Reviewable Commits**:

```bash
# Good commit structure
git log --oneline
abc123 Add user authentication endpoint
def456 Add JWT token generation
ghi789 Add password hashing
jkl012 Add authentication middleware
```

**Highlight Important Changes**:

```markdown
## Areas Needing Special Attention

1. **Line 145-160**: Changed cache invalidation logic
   - Please verify timeout values are correct
2. **Line 230**: SQL query modified
   - Please check for N+1 query issues
```

### Respond to Feedback

When reviewer comments:

- Respond to all feedback
- Thank them for catching issues
- Explain decisions if they ask
- Mark resolved conversations
- Push fixes q