create-pull-request

name create-pull-request description Create a GitHub pull request following project conventions. Use when the user asks to create a PR, submit changes for review, or open a pull request. Handles commit analysis, branch management, PR template usage, and PR creation using the gh CLI tool. 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. 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 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 Before creating the PR, you need the following information. Check if it can be inferred from: Commit messages Branch name (e.g., fix/issue-123 , feature/new-login ) Changed files and their content If any critical information is missing, use ask_followup_question to ask the user: Required Information Related Issue Number : Look for patterns like #123 , fixes #123 , or closes #123 in commit messages Description : What problem does this solve? Why were these changes made? Type of Change : Bug fix, new feature, breaking change, refactor, cosmetic, documentation, or workflow Test Procedure : How was this tested? What could break? Example clarifying question If the issue number is not found: I couldn't find a related issue number in the commit messages or branch name. What GitHub issue does this PR address? (Enter the issue number, e.g., "123" or "N/A" for small fixes) Git Best Practices Before creating the PR, consider these best practices: Commit Hygiene Atomic commits : Each commit should represent a single logical change Clear commit messages : Follow conventional commit format when possible No merge commits : Prefer rebasing over merging to keep history clean Branch Management Rebase on latest main (if needed): git fetch origin git rebase origin/main 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 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 Use a temporary file for the PR body to avoid shell escaping issues, newline problems, and other command-line flakiness: Write the PR body to a temporary file: /tmp/pr-body.md Create the PR using the file: gh pr create --title "PR_TITLE" --body-file /tmp/pr-body.md --base main Clean up the temporary file: rm /tmp/pr-body.md For draft PRs: gh pr create --title "PR_TITLE" --body-file /tmp/pr-body.md --base main --draft Why use a file? Passing complex markdown with newlines, special characters, and checkboxes directly via --body is error-prone. The --body-file flag handles all content reliably. Post-Creation After creating the PR: Display the PR URL so the user can review it Remind about CI checks : Tests and linting will run automatically 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 No commits ahead of main : The branch has no changes to submit Ask if the user meant to work on a different branch Branch not pushed : Remote doesn't have the branch Push the branch first: git push -u origin HEAD 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 Merge conflicts : Branch conflicts with base Guide user through resolving conflicts or rebasing Summary Checklist Before finalizing, ensure: gh CLI is installed and authenticated 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 description follows the template exactly Appropriate type of change is selected Pre-flight checklist items are addressed