Create Pull Request

Create Pull Request

This skill guides you through creating a well-structured GitHub pull request that follows project conventions and best practices.

Prerequisites Check

Before proceeding, verify the following:

1. Check if gh CLI is installed

gh --version

If not installed, inform the user:

The GitHub CLI (gh) is required but not installed. Please install it:

• macOS: brew install gh
• Other: https://cli.github.com/

2. Check if authenticated with GitHub

gh auth status

If not authenticated, guide the user to run gh auth login.

3. Check for related skills

Before creating a PR, check if any skills are available that relate to code review, CI, or testing. These should be invoked first as prerequisites.

Look for skills with descriptions containing:

• "review" (e.g., code review, PR review, web-design-guidelines)
• "CI" or "ci-fix" (e.g., fixing CI failures)
• "testing" or "test" (e.g., running tests, webapp-testing)

If such skills exist, invoke them before proceeding with PR creation. For example:

• If a ci-fix skill exists and CI is failing, use it to diagnose and fix issues
• If a web-design-guidelines skill exists for UI changes, use it to review the changes
• If a testing skill exists, use it to ensure tests pass

Only proceed with PR creation after these prerequisite skills have been satisfied.

4. Verify clean working directory

git status

If there are uncommitted changes, ask the user whether to:

• Commit them as part of this PR
• Stash them temporarily
• Discard them (with caution)

Check for Existing PR

Before gathering context, check if a PR already exists for the current branch:

gh pr list --head $(git branch --show-current) --json number,title,url

If a PR already exists:

• Display the existing PR details (number, title, URL)
• Ask the user if they want to:
  • View the existing PR: gh pr view
  • Update the existing PR (push more commits and the PR will update automatically)
  • Close the existing PR and create a new one

Only proceed with creating a new PR if no PR exists for this branch.

Gather Context

1. Identify the current branch

git branch --show-current

Ensure you're not on main or master. If so, ask the user to create or switch to a feature branch.

2. Find the base branch

git remote show origin | grep "HEAD branch"

This is typically main or master.

3. Analyze recent commits relevant to this PR

git log origin/main..HEAD --oneline --no-decorate

Review these commits to understand:

• What changes are being introduced
• The scope of the PR (single feature/fix or multiple changes)
• Whether commits should be squashed or reorganized

4. Review the diff

git diff origin/main..HEAD --stat

This shows which files changed and helps identify the type of change.

Information Gathering

Gather the following information from available context (commit messages, branch names, changed files):

Information to Extract

1. Related Issue Number: Look for patterns like #123, fixes #123, or closes #123 in:

   • Commit messages
   • Branch name (e.g., fix/issue-123, feature/123-new-login)
   • If found, include it in the PR title and/or description
   • If not found, proceed without it

2. Description: What problem does this solve? Why were these changes made?

   • Infer from commit messages and diff
   • Describe the changes made

3. Type of Change: Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow

   • Determine from commit messages and changed files

4. Test Procedure: How was this tested? What could break?

   • Mention test files if they were modified
   • Describe testing approach if evident from changes

Intelligent PR Title Generation

The PR title should be descriptive and meaningful. Avoid generic titles like:

• "initial commit"
• "fix"
• "update"
• "changes"

Instead, create a title that clearly summarizes the changes. Consider these approaches:

1. Conventional Commits Format

Check if the project uses conventional commits by analyzing:

• Commit messages for patterns like feat:, fix:, docs:, refactor:, test:, chore:
• Branch name prefixes like feat/, fix/, docs/

If conventional commits are detected, use the appropriate prefix for the PR title:

• feat: Add user authentication with OAuth
• fix: Resolve memory leak in data processing
• docs: Update API documentation for v2 endpoints
• refactor: Simplify error handling logic
• test: Add integration tests for payment flow
• chore: Update dependencies to latest versions

Include issue number if found:

• feat: Add user authentication with OAuth (#123)
• fix(auth): Resolve memory leak in data processing (fixes #456)

2. Descriptive Summary

If not using conventional commits, create a clear, action-oriented title:

• Good: "Add pagination to search results"
• Bad: "initial commit"
• Good: "Fix race condition in authentication flow"
• Bad: "fix bug"

Include issue number if found:

• "Add pagination to search results (#123)"
• "Fix race condition in authentication flow (fixes #456)"

3. Title Generation Strategy

1. Look at the most significant commit message (often the first or last)
2. Identify the main change from the diff (new feature, bug fix, etc.)
3. Extract the issue title if linked
4. If none of these provide a good title, synthesize one from the changed files and their purpose
5. Append issue number to title if found in commits or branch name

Git Best Practices

Before creating the PR, consider these best practices:

Commit Hygiene

1. Atomic commits: Each commit should represent a single logical change
2. Clear commit messages: Follow conventional commit format when possible
3. No merge commits: Prefer rebasing over merging to keep history clean