GitHub Pull Request

Determine Mode of Operation

Identify which mode to use based on user’s request:

Mode 1: Generate PR Content in Chat

Use when user wants to see/copy PR content WITHOUT creating it on GitHub:

• Explicit requests: “show PR”, “generate PR”, “output PR”, “give me PR”, “PR to chat”, “send to chat”
• Key indicators: Words like “show”, “display”, “output”, “give”, “send to chat” without “create”/”open”
• When unclear: If ambiguous (no existing PR, no clear “create” intent), default to this mode

Mode 2: Create PR on GitHub

Use when user wants to actually create PR:

• Explicit creation: “create PR”, “open PR”, “make PR”, “submit PR”
• Clear action: User clearly wants to create/open PR on GitHub

Default for ambiguous requests: Use Mode 1 (generate in chat) to show user what will be created first.

Workflow for Creating Pull Requests

Follow this workflow systematically when creating PRs:

Step 1: Determine the Scenario

Which scenario applies?

• Scenario A: Creating PR for existing branch with commits

  • Branch exists with commits that differ from base branch
  • Need to analyze ALL commits in the branch
  • → Use git diff/log or branch comparison tools

• Scenario B: User has uncommitted/unstaged local changes

  • Changes not yet committed
  • User wants to commit and create PR
  • → First help commit changes, then proceed with Scenario A

IMPORTANT: Most PR requests are Scenario A – analyzing an existing feature branch!

Step 2: Identify Current Branch and Base Branch

First, determine what branch you’re working with:

# Get current branch name
git branch --show-current

# Identify base branch (usually main/master)
git remote show origin | grep "HEAD branch"

Common base branches: master, main, develop

Step 3: Get Complete Branch Changes

CRITICAL: Analyze ALL changes in the entire branch that will be merged, not just:

• ❌ The last commit
• ❌ Previous chat context
• ❌ Individual file changes mentioned earlier

What you need to obtain:

• Complete diff between current branch and base branch
• List of all modified files
• All commit messages in the branch
• Full context of what changed

How to get this information:

Primary approach – Git commands (universal):

# Get full diff between branches
git diff <base-branch>...<current-branch>

# Example:
git diff main...feature-branch

# List changed files only:
git diff --name-status main...feature-branch

# See all commits in branch:
git log <base-branch>..<current-branch> --oneline

Alternative – Use available tools in your environment:

Depending on your environment, you may have access to:

• IDE diff viewers or change tracking features
• Version control UI showing branch comparisons
• File comparison tools
• Any method that shows complete changeset between branches

The key is obtaining the complete changeset, regardless of the method.

For uncommitted changes: If changes are not yet committed, first check what’s uncommitted using:

• git status and git diff (for git environments)
• Your IDE’s change tracker or source control panel
• Any tool showing unstaged/uncommitted modifications

Troubleshooting “No Changes” Issue:

If you get empty diff or “no changes”:

1. ✅ Verify you’re comparing correct branches (current vs base)
2. ✅ Check if current branch IS the base branch (can’t PR main to main!)
3. ✅ Ensure commits exist in branch: git log --oneline -10
4. ✅ Try: git log <base-branch>..<current-branch> to see commits
5. ❌ If truly no changes, inform user PR cannot be created without changes

Step 4: Analyze Changes Comprehensively

1. Review every modified file in the branch
2. Understand the cumulative impact of all commits
3. Identify affected packages/modules (important for monorepos)
4. Note any breaking changes or migration requirements

Step 5: Generate PR Content

Based on complete analysis, create:

• Title that reflects the main purpose of ALL changes
• Summary listing all significant modifications
• Motivation explaining why these changes were needed
• Related issues with proper linking

This workflow ensures PR descriptions accurately reflect the total scope of changes being merged.

Step 6: Create PR or Output to Chat

If Mode 2 (Create PR on GitHub) – Default action:

1. Create PR using available GitHub API tools
2. After successful creation, provide user with:
   • PR URL
   • Brief confirmation message

If Mode 1 (Generate in Chat) – Fallback:

Output the PR content in chat using the format described in “Fallback: Output Format for Chat” section.

Skip GitHub creation if:

• User explicitly requested text output only (Mode 1)
• Authentication/API errors occur (then fallback to Mode 1)
• Request is ambiguous (then fallback to Mode 1 to show user what will be created)

Language Requirement

CRITICAL: Always write all PR content (title, description, comments) in English only, regardless of the chat language or user’s preferred language. This is a strict requirement for all generated PR content.

Fallback: Output Format for Chat

Use this format when in Mode 1 (Generate PR Content in Chat):

• User explicitly requests viewing/copying PR content (see “Determine Mode of Operation” section above)
• Cannot create PR due to API/authentication issues
• Request is ambiguous (no clear “create” intent)
• User specifically asks not to create the PR yet

When outputting PR content to chat instead of creating it on GitHub:

ALWAYS wrap the complete PR content in a markdown code block:

[PR Title Here]

[Full PR Description Here]

This allows user to easily copy the entire PR content with proper formatting preserved.

DO NOT output PR content as rendered markdown in chat – it must be in a copyable code block.

PR Title

• ≤50 characters, imperative mood (“Add feature” not “Added” or “Adds”)
• Accurately reflect main purpose of changes
• No issue numbers in title (use description)
• For monorepos, consider a scoped title (e.g., feat(scope): description)

Examples:

• Add dark mode support to theme package
• Fix input validation in text field component
• Refactor build configuration for better performance

PR Description

Required sections:

1. Summary – What changed (bullet points, mention affected packages/modules)
2. Motivation – Why these changes were necessary, impact on project
3. Related Issues – Fixes #123, Closes #456, Related to #789

Optional sections:

• Testing Notes
• Breaking Changes (with migration guide)
• Performance Impact

Example:

## Summary

Adds dark mode support to the theme package:

- Added dark color palette with semantic tokens
- Updated CSS variables for theme switching
- Added theme toggle component

## Motivation

Users requested dark mode to reduce eye strain and improve accessibility.

## Related Issues

Fixes #42

Writing Style

Style Reference:

• Always write using a similar style as this example: “This is a community for chill dudes😎👍 who love to puff on a hookah🌬 with double apple🍎🍏, know their way around bowl packs💨, aren’t fans of vapers🤣, and respect their ladies👩‍🦳🙏.”
• Use emojis as frequently as shown in the example
• Do not include the example message itself in PR descriptions, just use it as a style reference

See references/pr-examples.md for more examples.

Edge Cases

• Large changesets: Group changes by component in summary
• Updating existing PR: Preserve metadata, add update comment
• Breaking changes: Mark clearly, provide migration guide
• Monorepo: Clearly indicate affected packages