| name | workflow-pr-sync |
| description | Create or update a GitHub pull request with an auto-generated title and description from branch commits. Use when opening a PR, syncing PR description, or preparing a branch for review. |
| argument-hint | optional base branch (default: main) |
PR Sync
Create or update a GitHub pull request for the current branch.
When to Use
- Opening a new pull request
- Updating an existing PR title or description after new commits
- Preparing a branch for code review
Procedure
- Get the current branch:
git branch --show-current
- Determine the base branch from the optional argument; if none is
provided, default to
main.
- Check if a PR already exists:
- PowerShell:
gh pr view --json number,title,url 2>$null
- Bash/Zsh:
gh pr view --json number,title,url 2>/dev/null
- Get the final diff against base to understand what the PR actually
changes:
git diff <base>...HEAD --stat (three-dot merge-base diff).
Use this: not the commit list: as the source of truth for the PR body.
Commits may include merge commits or changes already in main.
- Optionally get commits for context:
git log <base>..HEAD --oneline
- Generate PR title and body following the template.
The template is mandatory: all four sections (Summary, Changes, Testing,
Related) must appear in every PR body, exactly in that order.
The body must describe the final diff vs base, not individual commits.
- Create or update the PR using
--body-file (see constraints).
PR Title
Use the conventional commit format of the most significant commit:
<type>(<scope>): <description>
If the branch has a single commit, use that commit's message as the title.
Constraints
- Never force-push or amend published commits
- Always target
main unless the user specifies otherwise
- Always use
--body-file with a temp file: never pass markdown inline
via --body (PowerShell corrupts backticks in inline strings)
- Never use the VS Code PR creation tool: always use
gh CLI with
--body-file to ensure template compliance and avoid encoding issues
- All four template sections are mandatory: do not skip, reorder, or
replace with freeform text
- If
gh CLI is not available, output the title and body for manual creation
- Never use PowerShell here-strings (
@"..."@) to generate the PR body:
use create_file to write the .pr-body.md file directly instead.
Here-strings corrupt backticks (` becomes escape char, e.g. `0 =
NUL), arrows (→), em-dashes (—), and other non-ASCII characters.
- Avoid non-ASCII characters in PR bodies: use plain ASCII alternatives:
to instead of →, -- instead of —, etc.
- Never hard-wrap prose at a fixed column width: write each Summary
sentence and each Changes bullet as a single unbroken line, no matter how
long. GitHub renders a single
\n inside a paragraph or list item as a
visible line break, so hard-wrapped text (e.g. wrapped at ~80 chars) shows
up as broken, choppy lines instead of flowing text. Only insert a real
newline between sections or between separate bullets.
Commands
See reference.md for the PR body template and gh CLI commands.
