pr-generator

name	pr-generator
description	Generate well-structured Pull Requests following project templates and best practices. TRIGGER when: user asks to "create PR", "open PR", "submit PR", "create pull request", "open a pull request", "make a PR", or similar requests about creating pull requests. This skill ensures PRs are comprehensive, follow project conventions, and provide reviewers with all necessary context.

PR Generator

Generate Pull Requests that are clear, complete, and follow project conventions.

⚠️ Important: Prioritize GitHub MCP

If GitHub MCP is available, always use GitHub MCP tools first to handle PR-related operations.

GitHub MCP provides the following key capabilities for more efficient PR generation:

Feature	GitHub MCP Tool	Description
List branches	mcp__plugin_github_github__list_branches	View all branches
Get file content	mcp__plugin_github_github__get_file_contents	Fetch PR templates and other files
Get commit history	mcp__plugin_github_github__list_commits	View commit history of a branch
Create PR	mcp__plugin_github_github__create_pull_request	Directly create a Pull Request
Get PR template	mcp__plugin_github_github__get_file_contents with path .github/PULL_REQUEST_TEMPLATE.md	Fetch the project's PR template

Advantages of Using GitHub MCP

1. Direct remote repository access: Interact with the GitHub API without local git operations
2. Real-time status: Fetch the latest remote branch and PR status instantly
3. One-step PR creation: Use the create_pull_request tool to create PRs directly without manual pushes
4. Easier template retrieval: Fetch PR templates directly from the remote repository

Recommended Workflow (Using GitHub MCP)

graph TD
    A[Start] --> B{GitHub MCP available?}
    B -->|Yes| C[Use list_branches to get branch info]
    C --> D[Use get_file_contents to fetch PR template]
    D --> E[Use list_commits to get commit history]
    E --> F[Use get_file_contents to get changed files]
    F --> G[Generate PR content]
    G --> H[Use create_pull_request to create the PR]
    B -->|No| I[Fall back to local git commands]
    I --> G

Workflow

Step 1: Check for Project Template

First, check if the project has a PR template:

1. Look for .github/PULL_REQUEST_TEMPLATE.md
2. Also check for .github/PULL_REQUEST_TEMPLATE/ directory (multiple templates)
3. If a template exists, use it as the base structure

Step 2: Gather PR Information

Before drafting the PR, collect the following information:

1. Current branch name: git branch --show-current
2. Target branch: Usually main or master (check with git remote show origin)
3. Commits in this PR: git log <target>..HEAD --oneline
4. Changed files: git diff <target>...HEAD --name-status
5. Detailed diff: git diff <target>...HEAD --stat
6. Related issues: Check commit messages for issue references (e.g., "fixes #123", "closes #456")

Step 3: Draft PR Content

If a project template exists, follow its structure. Otherwise, use the default template below.

Default PR Template

When no project template exists, use this structure:

## 1. PR Overview
<!-- One sentence describing what this PR does and what problem it solves -->

---

## 2. Background / Motivation
<!-- Why is this change needed? What pain points, defects, or requirements prompted it? -->

- **Problem description**:
- **Scope of impact**:
- **Steps to reproduce** (optional):

---

## 3. Changes Made
<!-- What specifically was changed in this PR -->

- <!-- Change 1 -->
- <!-- Change 2 -->

**Type of change (select all that apply):**
- [ ] New feature
- [ ] Bug fix
- [ ] Refactor / cleanup
- [ ] Performance improvement
- [ ] Documentation update
- [ ] Test addition
- [ ] Dependency / configuration change

---

## 4. Implementation Notes
<!-- Explain *how* it was done to help reviewers quickly understand the key logic -->

- **Core approach**:
- **Key design decisions / trade-offs**:
- **Main files / modules affected**:
  - <!-- file1 -->
  - <!-- file2 -->

---

## 5. Behavior Changes (External Impact)
<!-- From the user's perspective, what visible changes does this PR introduce? -->

- **Before**:
- **After**:
- **Compatibility impact** (if any):

---

## 6. Testing & Verification
<!-- How did you confirm everything works correctly? -->

**Self-test results:**
- [ ] Verified locally
- [ ] Unit tests passing
- [ ] Integration / end-to-end tests passing (if applicable)

**Test commands / steps:**
\`\`\`bash
# e.g.: pytest -q
# e.g.: npm test
\`\`\`

---

## 7. Checklist

- [ ] Code style follows project conventions
- [ ] Necessary comments added
- [ ] Relevant documentation updated
- [ ] Tests added / updated
- [ ] No breaking changes (or clearly documented)
- [ ] Related issues linked

Content Generation Guidelines

PR Title

Generate a clear, concise title following these patterns:

1. If project uses conventional commits:

   • feat(scope): add new feature
   • fix(scope): resolve bug description
   • refactor(scope): what was refactored
   • docs: update documentation
   • test: add tests for X

2. Otherwise, use a descriptive sentence:

   • "Add user authentication with JWT"
   • "Fix memory leak in data processing"

Changed Files Section

Always include a clear summary of changed files:

**File change summary:**
- Added: X files
- Modified: Y files
- Deleted: Z files

**Detailed changes:**
| File | Change Type | Description |
|------|-------------|-------------|
| src/auth.py | Modified | Added JWT verification logic |
| tests/test_auth.py | Added | Authentication-related test cases |

Auto-fill What You Can

Automatically fill in information from git:

1. Commits: Extract from git log
2. Changed files: Extract from git diff
3. Related issues: Parse from commit messages
4. Change type: Infer from commit prefixes or file changes

Ask for Missing Information

If you cannot determine certain information from the code, ask the user:

1. Background / motivation (why this change was needed)
2. Testing performed
3. Breaking changes (if any)
4. Any additional context for reviewers

Best Practices

1. Be specific: Don't use vague descriptions like "fixed bug" or "updated code"
2. Provide context: Explain WHY, not just WHAT
3. Link issues: Always reference related issues
4. Small PRs: If the PR is large, suggest splitting it
5. Self-review: Before finalizing, re-read the PR as if you were a reviewer

Example Output

For a PR that adds JWT authentication:

## 1. PR Overview
Add JWT-based user authentication to address the lack of identity verification in the current system.

---

## 2. Background / Motivation
- **Problem description**: Current API endpoints have no authentication — anyone can call them freely
- **Scope of impact**: All API endpoints
- **Steps to reproduce**: Call any API endpoint directly and receive data without credentials

---

## 3. Changes Made
- Added JWT token generation and verification module
- Added login endpoint that returns a token
- Added token verification middleware to protected endpoints
- Added authentication-related test cases

**Type of change:**
- [x] New feature
- [ ] Bug fix
- [ ] Refactor / cleanup
- [ ] Performance improvement
- [ ] Documentation update
- [x] Test addition
- [ ] Dependency / configuration change

---

## 4. Implementation Notes
- **Core approach**: Used the PyJWT library to generate and verify tokens; a middleware layer intercepts requests to protected routes
- **Key design decisions / trade-offs**:
  - Token expiry is set to 24 hours (configurable)
  - Uses HS256 algorithm; can be upgraded to RS256 in the future
- **Main files / modules affected**:
  - `src/auth/jwt_handler.py` — core JWT logic
  - `src/middleware/auth.py` — authentication middleware
  - `src/routes/auth.py` — login endpoint
  - `tests/test_auth.py` — test cases

---

## 5. Behavior Changes (External Impact)
- **Before**: All APIs were accessible without any authentication
- **After**: Protected endpoints require a valid JWT token
- **Compatibility impact**: Existing callers must obtain a token first — this is a Breaking Change

---

## 6. Testing & Verification
**Self-test results:**
- [x] Verified locally
- [x] Unit tests passing
- [ ] Integration / end-to-end tests passing

**Test commands:**
\`\`\`bash
pytest tests/test_auth.py -v
\`\`\`

---

## 7. Checklist
- [x] Code style follows project conventions
- [x] Necessary comments added
- [x] Relevant documentation updated
- [x] Tests added / updated
- [ ] No breaking changes (or clearly documented)
- [ ] Related issues linked