| name | submitting-pull-requests |
| description | Creates and submits pull requests with well-structured descriptions following project guidelines. Use when asked to open a PR, submit a PR, or create a pull request. |
Submitting Pull Requests
Creates pull requests using the GitHub CLI with descriptions that follow project conventions.
Prerequisites
- GitHub CLI (
gh) installed and authenticated
- Run
gh auth status to verify authentication
- Changes all committed and pushed to a remote branch
Workflow
- Gather context - Determine the branch, read commits, load linked Linear issue if not already in context
- Check for PR template - Look for
.github/pull_request_template.md in the repo
- Draft the PR description - Generate a description following the template structure
- Present draft to user - Show the proposed title and body, ask for feedback
- Iterate - Revise based on user feedback until approved
- Ask for reviewers - Prompt the user for who should review the PR
- Submit PR - Use
gh pr create to open the pull request
- Share the link - Display the PR URL to the user
Gathering Context
git branch --show-current
git log main..HEAD --oneline
git log main..HEAD --format="%B---"
git diff main...HEAD --stat
Linear Issue from Branch Name
If a Linear issue wasn't loaded in current context, extract the issue ID from the branch name and fetch it:
linear issue view ABC-123
Checking for PR Template
cat .github/pull_request_template.md 2>/dev/null
If a template exists, structure the PR body to match its sections.
Drafting the Description
Use all available context to draft the PR:
- Linear issue details (title, description, acceptance criteria)
- Slack conversations referenced during the thread
- Notion documents read
- Commit messages and code changes
- Any other context from the current conversation
Common PR Sections
Description
- What problem does this solve and how
- Alternatives considered (if applicable)
Context
- Links to Linear tickets, Notion docs, Slack threads, or other references
Changes
- Summary of what changed:
- An opportunity to highlight code design choices made that are too low level for the description section
- Less is more; highlighting the most important / interesting changes rather than listing every single choice
- It should NOT be:
- A file-by-file description of every change; reviewers can look at code changes to get that level of detail
- Screenshots for UI changes
Verification
- Acceptance testing steps: how a human can verify the feature works
- Expected user-facing behavior
- Do NOT mention activities that would have failed the CI build if they weren't done, such as:
- Automated tests pass
- A linting tool is green
- Pre-commit hooks have passed
Deployment
- Risk level and deployment considerations
- Migration notes if applicable
Rollback
- Never leave blank
- How to revert if something breaks
- Feature flag toggles, revert safety, migration concerns
Presenting the Draft
Show the user:
- Proposed PR title
- Full PR body in a code block
- Ask: "Does this look good, or would you like me to revise anything?"
Iterate until the user approves.
Requesting Reviewers
Before submitting, ask the user: "Who would you like to review this PR?"
The user may provide:
- GitHub usernames
- Team names (e.g., "platform team" →
org/platform)
- People's real names (look up their GitHub username)
If the user provides names you don't recognize, ask for clarification or search the repo's contributors/team members.
Submitting the PR
gh pr create --title "<title>" --body "<body>" --reviewer <users>
gh pr create --title "<title>" --body "<body>" --draft --reviewer <users>
After successful creation, gh pr create outputs the PR URL. Display this link to the user.
Useful Options
--draft: Create as draft PR--base <branch>: Target branch (default: main/master)--reviewer <users>: Request reviewers (users or org/team)--assignee <users>: Assign users--label <labels>: Add labels
