pda Submitting Pull Requests
Creates pull requests using the GitHub CLI with descriptions that follow project conventions.
Prerequisites
- GitHub CLI (
gh) must be installed and authenticated - Run
gh auth statusto verify authentication - Changes must be 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.mdin 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 createto open the pull request - Share the link - Display the PR URL to the user
Gathering Context
# Current branch
git branch --show-current
# Recent commits on branch vs main
git log main..HEAD --oneline
# Full commit messages for context
git log main..HEAD --format="%B---"
# Changed files
git diff main...HEAD --stat
Linear Issue from Branch Name
If a Linear issue hasn't already been loaded in the current context, extract the issue ID from the branch name and fetch it:
# Branch names often contain issue IDs like "abc-123-feature-name"
# Extract and view the issue
linear issue view ABC-123
Checking for PR Template
# Look for project 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 that were read
- Commit messages and code changes
- Any other context from the current conversation
Common PR Sections
Description
- What problem is being solved and how
- Alternatives considered (if applicable)
Context
- Links to Linear tickets, Notion docs, Slack threads, or other references
Changes
- Bulleted list of what changed
- Screenshots for UI changes
Verification
- Acceptance testing steps: how a human can verify the feature works
- Expected user-facing behavior
Deployment
- Risk level and deployment considerations
- Migration notes if applicable
Rollback
- Never leave blank
- How to safely 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
# With reviewers
gh pr create --title "<title>" --body "<body>" --reviewer <users>
# As draft with reviewers
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