pr-workflow

name

pr-workflow

description

Git workflow for pushing code and opening pull requests on GitHub. ALWAYS use this before you git push, push to a remote, open or create a pull request, raise a PR, or "ship" code. Covers confirming the user actually asked to push, cutting a Conventional-Commits feature branch off main, writing a Conventional-Commit PR title, and using the repo's .github PR template as the body. Use whenever the user says push, ship, open/create a PR, raise a pull request, or commit-and-push.

Workflow

1. Confirm the user asked — in their latest message. Pushing to a remote / opening a PR is outward-facing and hard to undo. Do it only when the user's most recent request actually says to push, ship, or open a PR. Approval from an earlier turn does not carry forward — "make the change" is not "push it." If you finished work and the user didn't ask to push, stop and ask. Never push proactively.

2. Branch off the default branch. Unless the user explicitly says to push straight to main (e.g. "commit straight to main", "push to main directly"), create a feature branch named with Conventional Commits: <type>/<kebab-description>, e.g. feat/add-logout-button.

3. Commit with a Conventional Commit message, then push the branch. Always make a new commit. Never force-push (git push --force / --force-with-lease) and never amend (git commit --amend) or otherwise rewrite existing commits — unless the user explicitly asks for it in their latest message. To update a PR or fix a previous commit, add another commit and push normally.

4. Open the PR with a Conventional-Commit title (<type>[(scope)][!]: <subject>, e.g. feat(auth): add OAuth login). For the body: if a .github PR template exists, use it verbatim and add no extra sections, summaries, or "test plan" fields. If there's no template, keep the body to a one-line description — don't invent a template.

type is one of: feat fix docs style refactor perf test build ci chore revert.

Notes

• Default branch: the base for the PR is the repo's default branch — read it from origin/HEAD, falling back to main.
• Branch names: lowercase the description, replace spaces and punctuation with dashes, prefix the type — "Add Login (OAuth)" with type feat → feat/add-login-oauth.
• Finding the PR template: check .github/PULL_REQUEST_TEMPLATE.md first, then the lowercase variant, then the repo root, then docs/. The .github/PULL_REQUEST_TEMPLATE/ directory form holds multiple templates — if the repo uses it, pass the chosen file to gh pr create --body-file.
• Opening the PR: gh pr create --base <default-branch> --title "<conventional title>" with --body-file <template> when a template exists, or a one-line --body when it doesn't.

Gotchas

• "The user asked earlier" is not the latest message. Step 1 is about the most recent request. If it was "fix the bug" and you fixed it, you have not been asked to push. Ask first.
• A PR template is not a checklist for you to fill in. Use it verbatim as the body; leave its checkboxes/headings exactly as written unless the user fills them. Stacking your own "## Summary / ## Test plan" on top of an existing template is wrong.
• Never rewrite history to "clean up." Force-pushing and amending are destructive and break anyone who pulled the branch. Even when a previous commit was wrong, the default is a new follow-up commit, not an amend or force-push. Only rewrite when the user explicitly tells you to in their latest message.
• The template lookup checks .github first, then the repo root, then docs/, and includes the .github/PULL_REQUEST_TEMPLATE/ directory form (multiple templates). If the repo has several, ask which to use.

Troubleshooting

• gh pr create fails with no default remote repository → run gh repo set-default <owner>/<repo> once, or pass --repo <owner>/<repo>.
• gh: not authenticated → the user must run gh auth login themselves (suggest they type ! gh auth login). Don't authenticate for them.