macalbert/envilder/workflow-pr-sync

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

1. Get the current branch: git branch --show-current
2. Determine the base branch from the optional argument; if none is

provided, default to main.

1. 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

1. 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.

1. Optionally get commits for context: git log <base>..HEAD --oneline
2. 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.

1. 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.