create-pr

name	create-pr
description	Automate GitHub Pull Request creation using MCP (Model Context Protocol) tools. Use when code changes are committed and you need to create a PR with auto-generated title and description following project commit conventions.

Create PR - Automated Pull Request Creation

Automatically create high-quality Pull Requests using GitHub MCP tools, following conventional commit specifications.

When to Use

Trigger when user requests PR creation, for example:

• "Create a PR"
• "Help me create a pull request"
• "I finished the refactoring work, can you create a PR?"
• "Create PR for current branch"

Prerequisites:

• Code changes are committed to a git branch
• Current branch is not the default branch (main/master)
• Branch is pushed to remote repository (or needs to be pushed before creating PR)

Workflow

Step 1: Branch Detection and Validation

Use Bash tool to check current git status:

# Get current branch
git branch --show-current

# Check for unpushed commits
git status -sb

# Check differences from base branch
git log origin/main..HEAD --oneline

Validation checklist:

• Current branch is not main/master
• Branch has unmerged commits
• Branch is pushed to remote (if not, push first)

Step 2: Gather PR Information

Use MCP GitHub tools to fetch commit history:

# Use MCP tool to get commits for current branch
mcp__github__list_commits owner=<owner> repo=<repo> sha=<current_branch>

# Or use git command to get complete diff and commit info
git log origin/main..HEAD --format="%h %s%n%b"
git diff origin/main...HEAD --stat

Extract information:

• Extract PR title and description from commit messages
• Identify target base branch (usually main or develop)
• Collect file change statistics
• Find related issue references (e.g., "fix #123")

Step 3: Generate PR Title and Description

Title format (strictly follow conventional commit):

<type>(<scope>): <summary>

• Type: feat, fix, perf, test, docs, refactor, build, ci, chore, revert
• Scope (optional): e.g., core, API, output, config
• Summary rules:
  • PR title MUST be written in English
  • PR description MAY be written in Chinese or mixed Chinese-English
  • Must start with a lowercase letter
  • Use imperative present tense ("add" not "added")
  • Must not end with a period
  • For breaking changes, add ! before the colon
  • To exclude from changelog, add (no-changelog) suffix

Validation regex:

^(feat|fix|perf|test|docs|refactor|build|ci|chore|revert)(\([a-zA-Z0-9 ]+( Node)?\))?!?: [a-z].+[^.]$

Description template (Paper Tracker format):

## Summary

<1-2 paragraph overview of what this PR does and why>

**Key changes (if applicable):**
- <Key change 1>
- <Key change 2>
- <Key change 3>

### Changes

<Detailed changes, organized by module/component if complex>

- **Module/Component Name** (if multiple modules affected)
  - <Specific change 1>
  - <Specific change 2>
- <Simple change 1>
- <Simple change 2>

## Breaking Changes

<Description of breaking changes, if any. Otherwise omit this section>

## Testing

<Testing approach>
- Tests performed: <description>
OR
- Not run (not requested)
OR
- Not run (docs-only changes)

## Related Issues

<Issue references like "Closes #123" or "N/A">

### Notes

<Optional additional context, caveats, or follow-up items>

Step 4: Create Pull Request

Use MCP GitHub tool to create PR:

mcp__github__create_pull_request \
  owner=<owner> \
  repo=<repo> \
  title="<conventional_commit_title>" \
  head=<current_branch> \
  base=<base_branch> \
  body="<pr_description>"

Optional parameters:

• draft=true - Create draft PR
• maintainer_can_modify=true - Allow maintainer edits

Step 5: Confirm and Report

After successful creation, report to user:

• PR number and URL
• PR title and target branch
• Number of changed files and statistics

Title Format Examples

Good examples:

• feat(core): add config override support
• fix(output): fix markdown rendering in tables
• docs: update environment variables guide
• refactor(API)!: change query parameter structure
• test(core): add tests for deduplication logic
• chore: update dependencies (no-changelog)

Bad examples (avoid):

• feat: Add feature - Summary should start with lowercase
• update code - Missing type
• fix(core): fixed bug. - Past tense and ends with period
• feature: add support - Wrong type (should be feat)

Project-Specific Conventions

For Paper Tracker project:

Common scopes:

• core - Core logic (query, deduplication, etc.)
• llm - LLM integration and services
• output - Output formatting and rendering
• config - Configuration system
• API - API interaction
• cli - Command line interface
• database - Database schema and storage

PR Description Guidelines:

• Summary section: Provide 1-2 paragraphs explaining what and why
• Changes section: List specific changes, group by module for complex PRs
• Breaking Changes: Only include if there are actual breaking changes
• Testing: Be explicit about test status:
  • Describe tests run, OR
  • State "Not run (not requested)", OR
  • State "Not run (docs-only changes)"
• Related Issues: Use "N/A" if no related issues

Reference recent commits:

# View project commit history to understand style
git log --oneline -n 10

Error Handling

Common issues and solutions:

1. Branch not pushed:

   git push -u origin <branch_name>
   

2. No unique commits:

   • Inform user that current branch is same as base branch
   • Suggest making code changes and committing first

3. MCP tool failure:

   • Provide clear error messages
   • Suggest checking network connection or GitHub authentication

4. Title format validation failure:

   • Display validation errors
   • Provide correct example format
   • Ask user to confirm modified title

Best Practices

1. Auto-detect project conventions:

   • Look for .github/pull_request_template.md
   • If template exists, use its structure

2. Extract issue references:

   • Find fix #123, closes #456 etc. in commit messages
   • Automatically add to "Related Issue" section of PR description

3. Branch naming hints:

   • If type can be inferred from branch name (e.g., feature/xxx, fix/xxx), prioritize it
   • Cross-validate type consistency with commit messages

4. Interactive confirmation:

   • Show preview after generating PR info
   • Ask user if modifications are needed
   • Create PR after confirmation

Usage Examples

Scenario 1: Feature PR

User: "Create a PR"
Assistant: Detected current branch feature/markdown-export, creating PR based on 5 commits
          Title: feat(output): add markdown export functionality

          Description preview:
          ## Summary

          Adds markdown export functionality to Paper Tracker, allowing users to export
          paper search results in a customizable markdown format.

          ### Changes
          - Add markdown renderer with template support
          - Add configuration for markdown output
          - Update documentation

          ## Testing
          - Manual testing with sample data

          ## Related Issues
          N/A

          Confirm creation? (use AskUserQuestion tool)

Scenario 2: Refactoring with no changelog

User: "Create PR for config nesting refactor"
Assistant: Title: refactor(core): nest LLM config (no-changelog)

          This will be excluded from changelog due to (no-changelog) marker.

Scenario 3: Breaking change

User: "Create a PR for this API refactoring"
Assistant: Detected breaking changes in configuration schema
          Title: refactor(config)!: change output format structure

          Description will include:
          ## Breaking Changes
          - Configuration field `output.format` renamed to `output.formats`
          - Field now accepts a list instead of single value

Important Notes

• ❌ Don't guess remote repository info, always verify
• ❌ Don't assume branch is pushed before creating PR
• ✅ Ensure all commits are pushed
• ✅ Maintain context awareness of project-specific conventions
• ✅ Provide clear error messages and recovery suggestions
• ✅ Generated PR description should include sufficient context