Pull Request Creation Best Practices

Purpose

This skill enforces three critical best practices when creating GitHub pull requests:

1. Include ticket numbers - Associates PRs with tracking tickets (Jira, GitHub Issues)
2. Use PR templates when available - Ensures consistent, complete PR descriptions
3. Create PRs as drafts by default - Allows review before marking ready for review

Ticket Detection and Integration

Before creating the pull request, attempt to identify an associated ticket number from Jira or GitHub Issues.

Detection Sources

Check the following sources for ticket numbers (in order of preference):

1. Conversation context - Ticket mentioned in recent messages or conversation history
2. Branch name - Parse current branch name for ticket patterns:
   • PROJ-123/description (Jira-style prefix)
   • feature/PROJ-123-description (Jira after prefix)
   • 123-description (GitHub issue number)
   • Other common patterns using intuition
3. Recent commit messages - Check for ticket references in commit messages
4. Ask user - If no ticket found in above sources, use AskUserQuestion to ask if there's an associated ticket

Ticket Number Patterns

Recognize these common patterns:

• Jira tickets: PROJ-123, ABC-456 (uppercase letters, hyphen, numbers)
• GitHub issues: #123, 456 (numbers, optionally with # prefix)

PR Title Integration

When ticket number is identified, format the PR title as:

[TICKET-NUM] Descriptive PR title

Examples:

• [MSI-608] Add Zendesk integration
• [#456] Fix authentication bug
• [PLATFORM-123] Refactor API endpoints

PR Body Integration

If PR template exists with ticket field:

• Look for placeholders like [TICKET], [ISSUE], Ticket:, Issue:, JIRA:, etc.
• Replace placeholder with ticket number (as link if URL can be determined)
• Preserve template formatting

If template has no specific ticket field:

• Add ticket reference at the top of the PR body
• Format as: **Ticket:** [TICKET-NUM](url) or **Ticket:** TICKET-NUM if no URL

If no template:

• Include ticket reference at the start of the PR description
• Format with link if available

Ticket URL Determination

Determine ticket URLs from available context and knowledge:

1. Check CLAUDE.md or project configuration - Look for Jira base URL, GitHub repo URL, or ticket system configuration
2. Parse git remote - Extract GitHub repository URL from git config for GitHub issues
3. Use conversation context - Apply knowledge from earlier in conversation about project's ticket systems
4. Infer from project structure - Look for .jira, project config files, or documentation mentioning ticket URLs

URL formats:

• Jira: https://company.atlassian.net/browse/PROJ-123
• GitHub Issues: https://github.com/owner/repo/issues/123

If URL cannot be determined, include ticket number without link.

PR Template Discovery

Before creating the pull request, check for GitHub PR templates in the .github/ directory using the following search order:

1. .github/pull_request_template.md (lowercase, standard GitHub convention)
2. .github/PULL_REQUEST_TEMPLATE.md (uppercase variant)
3. .github/PULL_REQUEST_TEMPLATE/*.md (multiple templates in subdirectory)

Template Usage

If a template is found:

• Read the template file to understand the required sections
• Use the template structure when constructing the PR body with gh pr create --body
• Fill in each template section appropriately based on the changes being submitted
• Preserve template formatting, headings, and structure

If multiple templates exist in .github/PULL_REQUEST_TEMPLATE/:

• List available templates to the user
• Ask which template to use for this PR
• Proceed with the selected template

If no template is found:

• Proceed with standard PR creation
• Generate a comprehensive PR description including:
  • Summary of changes
  • Test plan or verification steps
  • Any relevant context or decisions

Draft PR Creation

Always create pull requests as drafts using the --draft flag:

gh pr create --draft --title "PR title" --body "$(cat <<'EOF'
PR description here
EOF
)"

Why Draft by Default

Draft PRs provide several benefits:

• Allows CI/CD checks to run before requesting reviews
• Provides opportunity to review the PR diff on GitHub before soliciting feedback
• Prevents accidental notification spam to reviewers for incomplete work
• Enables incremental commits and refinements before marking ready

Making PR Ready for Review

After creating the draft PR, inform the user they can mark it ready for review when appropriate:

gh pr ready <pr-number>

Or they can mark it ready directly on GitHub.

Complete Workflow

Follow this sequence when the user requests PR creation:

1. Detect ticket number:

   • Check conversation context for ticket references
   • Parse current branch name for ticket patterns
   • Check recent commit messages
   • If no ticket found, use AskUserQuestion to ask user
   • Determine ticket URL if possible from context, CLAUDE.md, or git config

2. Check for PR templates:

   • Search .github/ directory for template files
   • If found, read template content
   • Identify if template has ticket field/placeholder

3. Gather PR information:

   • Analyze recent commits using git log and git diff
   • Generate appropriate PR title with ticket: [TICKET] Title
   • Generate PR description:
     • If template with ticket field: fill in ticket (with link if available)
     • If template without ticket field: add ticket at top of body
     • If no template: include ticket at start of description
   • If using template, structure description according to template format

4. Create draft PR:

   • Use gh pr create --draft with ticket-formatted title and body
   • Include template content if applicable
   • Ensure body is passed via heredoc for proper formatting

5. Verify creation:

   • Confirm PR was created successfully
   • Display PR URL to user
   • Remind user that PR is in draft state

6. Provide next steps:

   • Inform user how to mark PR ready when appropriate
   • Note any CI/CD checks that will run

Example Commands

PR with ticket from branch name

# Detect ticket from branch (e.g., MSI-608/zendesk2)
BRANCH=$(git branch --show-current)
# Parse ticket: MSI-608

# Create draft PR with ticket in title
gh pr create --draft --title "[MSI-608] Add Zendesk integration" --body "$(cat <<'EOF'
**Ticket:** [MSI-608](https://company.atlassian.net/browse/MSI-608)

## Summary
Added Zendesk integration for customer support tickets

## Changes
- Implemented Zendesk API client
- Added webhook handlers
EOF
)"

PR with template containing ticket placeholder

# Template has "Ticket: [TICKET]" placeholder
# Replace with actual ticket and link

gh pr create --draft --title "[PLATFORM-123] Refactor API endpoints" --body "$(cat <<'EOF'
## Ticket
[PLATFORM-123](https://jira.company.com/browse/PLATFORM-123)

## Summary
[Filled from template]

## Test Plan
[Filled from template]
EOF
)"

PR with GitHub issue number

# Detect from branch: 456-fix-auth-bug

gh pr create --draft --title "[#456] Fix authentication bug" --body "$(cat <<'EOF'
**Related Issue:** [#456](https://github.com/owner/repo/issues/456)

## Summary
Fixed authentication token expiration handling
EOF
)"

Important Notes

• Detect ticket numbers - Always attempt to find associated ticket from context, branch, or commits before asking user
• Always use --draft flag - Never create PRs as immediately ready for review
• Include ticket in title - Format as [TICKET] Title when ticket is identified
• Link tickets when possible - Use context knowledge to determine ticket URLs
• Respect template structure - When templates exist, follow their format exactly
• Use heredoc for body - Ensures proper multiline formatting and prevents shell escaping issues
• Verify template locations - Check all three standard locations before proceeding
• Inform the user - Always communicate that the PR was created as a draft and how to mark it ready

Edge Cases

No ticket found and user declines to provide: If user indicates there's no associated ticket or chooses not to provide one, proceed with PR creation without ticket in title or body

Multiple ticket references: If multiple tickets are found, ask user which is the primary ticket for this PR

Invalid ticket format: If detected ticket doesn't match expected patterns, verify with user before using

Cannot determine ticket URL: If ticket is identified but URL cannot be determined from context, include ticket number without link

No git repository: Verify current directory is a git repository before proceeding

Not a GitHub repository: Confirm remote is GitHub before using gh commands

No GitHub CLI: If gh command is not available, inform user to install GitHub CLI

Branch already has PR: If a PR already exists for the current branch, inform user rather than creating duplicate

No commits to push: Ensure there are commits to include in the PR before creating it