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. 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)

Gather Context

1. Identify the current branch

git branch --show-current

If you're on main or master, create a feature branch automatically:

1. Decide the branch name using, in order of preference:
   • Issue number + slug: If an issue number is available from conversation context, use fix/<issue>-<short-slug> or feat/<issue>-<short-slug> (e.g. fix/42-auth-timeout, feat/123-add-login).
   • Change content: If no issue number, infer type and slug from changed files: git status, git diff --stat, or git diff to derive a short kebab-case slug (e.g. fix/memory-leak-handler, docs/update-readme).
2. Create and switch to the branch:

   git checkout -b <branch-name>

   Use a type prefix (fix/, feat/, docs/, refactor/, chore/) that matches the change. Keep the slug short and lowercase with hyphens.

If already on a feature branch, proceed to the next step.

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

Before creating the PR, you need the following information. Check if it can be inferred from:

• Conversation context (user-mentioned issue numbers)
• Branch name (e.g., fix/issue-123, feature/123-new-login)
• Changed files and their content

If any critical information is missing, use ask_followup_question to ask the user:

Required Information

1. Related Issue Number: Look in this order—(1) conversation context (user-mentioned issue numbers), (2) branch name patterns (e.g. issue-123, 123-new-login). If not found, do not ask the user; omit or use a placeholder in the PR body.
2. Description: What problem does this solve? Why were these changes made?
3. Type of Change: Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow
4. Test Procedure: How was this tested? What could break?

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

Branch Management

1. Rebase on latest main (if needed):

   git fetch origin
   git rebase origin/main

2. Squash if appropriate: If there are many small "WIP" commits, consider interactive rebase:

   git rebase -i origin/main

   Only suggest this if commits appear messy and the user is comfortable with rebasing.

Push Changes

Ensure all commits are pushed:

git push origin HEAD

If the branch was rebased, you may need:

git push origin HEAD --force-with-lease

PR Title Format (Conventional Commits)

PR titles MUST follow Conventional Commits format:

<type>[optional scope]: <description>

Types

Type	Description
feat	A new feature
fix	A bug fix
docs	Documentation only changes
refactor	A code change that neither fixes a bug nor adds a feature
chore	Other changes that don't modify src or test files

Examples

• feat(auth): add OAuth2 login support
• fix: resolve memory leak in event handler
• docs: update API documentation
• refactor(utils): simplify date formatting logic

Create the Pull Request

IMPORTANT: Read and use the PR template at .github/pull_request_template.md. The PR body format must strictly match the template structure. Do not deviate from the template format.

When filling out the template:

• Replace #XXXX with the actual issue number, or keep as #XXXX if no issue exists (for small fixes)
• Fill in all sections with relevant information gathered from commits and context
• Mark the appropriate "Type of Change" checkbox(es)
• Complete the "Pre-flight Checklist" items that apply

Create PR with gh CLI

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main

Alternatively, create as draft if the user wants review before marking ready:

gh pr create --title "PR_TITLE" --body "PR_BODY" --base main --draft

Post-Creation

After creating the PR:

1. Display the PR URL so the user can review it
2. Remind about CI checks: Tests and linting will run automatically
3. Suggest next steps:
   • Add reviewers if needed: gh pr edit --add-reviewer USERNAME
   • Add labels if needed: gh pr edit --add-label "bug"

Error Handling

Common Issues

1. No commits ahead of main: The branch has no changes to submit

   • Ask if the user meant to work on a different branch

2. Branch not pushed: Remote doesn't have the branch

   • Push the branch first: git push -u origin HEAD

3. PR already exists: A PR for this branch already exists

   • Show the existing PR: gh pr view
   • Ask if they want to update it instead

4. Merge conflicts: Branch conflicts with base

   • Guide user through resolving conflicts or rebasing

Summary Checklist

Before finalizing, ensure:

• Working directory is clean
• All commits are pushed
• Branch is up-to-date with base branch
• Related issue number is identified, or placeholder is used
• PR title follows Conventional Commits format
• PR description follows the template exactly
• Appropriate type of change is selected
• Pre-flight checklist items are addressed