pr-push

name

pr-push

description

Commit all working-tree and untracked changes on a feature branch, push the branch, and open a GitHub pull request with a Conventional Commit-style title, a concise summary, and a collapsed rationale section. If the current branch is `main`, create and switch to a feature branch first. When a PR already exists, fetch its current title and description, synthesize them with the new changes, and update the PR — never silently overwrite useful existing content. Use when Codex needs to finish the full git handoff flow after implementing changes and the user wants a branch-safe commit, push, and PR creation sequence.

PR Push

Complete the repo handoff flow without cutting corners.

Workflow

1. Confirm the current branch before touching git state:

   git rev-parse --abbrev-ref HEAD
   

   If the branch is main, create and switch to a new feature branch before staging or committing. Derive a short kebab-case branch name from the change when possible (for example chore/playwright-one-retry or fix/invite-expiry-copy):

   git switch -c "<branch-name>"
   

   Only continue once you are on a non-main branch.
2. Stage everything:

   git add -A
   git diff --cached --stat
   git diff --cached
   

   If nothing is staged after git add -A, stop and report that there is nothing to commit.
3. Generate the commit message yourself. Follow Conventional Commit format:

   type(scope): subject
   

   Use the same conventions as the commit and commit-and-push skills:
   • type: feat, fix, refactor, docs, test, chore, ci, perf, or style
   • scope: the most specific affected area
   • subject: concise, imperative, and meaningful
4. Attempt the commit with the existing helper:

   bash .agents/skills/commit/scripts/commit.sh "<message>"
   

   If pre-commit hooks fail, read the errors, fix the real issue, re-stage, and retry until the commit succeeds cleanly. Never use --no-verify.
5. Check for an existing PR on this branch:

   gh pr view --head "$(git rev-parse --abbrev-ref HEAD)" --json title,body,url 2>/dev/null
   

   • If a PR exists, read its current title and body. These represent previously reviewed, intentional content — do not discard them.
   • Proceed to step 6 whether or not a PR exists.
6. Draft the PR content, synthesizing with any existing PR metadata:
   • When no PR exists: write fresh content from the committed changes.
   • When a PR already exists: incorporate the existing title and description. Keep anything that is still accurate and relevant. Weave new changes into the existing narrative rather than appending a changelog or overwriting wholesale.
   • PR title: Conventional Commit-style. When updating, evolve the existing title only if the scope has meaningfully changed; otherwise keep it.
   • Summary: Focus on purpose and why — what problem does this PR solve and why does it matter? Summarize the what in 1–2 sentences max. Do not produce a bulleted list of individual changes; reviewers can see the diff. Keep the total summary to a short paragraph.
   • Rationale: Substantive explanation of why the change exists, notable implementation choices, and important reviewer context.
7. If the PR includes significant UI or product-facing behavior changes, invoke $create-video-demo before finishing the handoff:
   • Record a sub-minute Playwright demo for the changed workflow.
   • Export the video into ux-artifacts/video-demos/.
   • Do not commit the exported video artifact.
   • Upload the final video to Vercel Blob.
   • Prepare the PR demo comment body starting with Demo at commit {hash}.
8. Push the branch and create or update the PR:
   • Prefer file-based inputs whenever the title, summary, or rationale may contain backticks, $(), quotes, or multiple lines.
   • Write each field to a temporary file with a quoted heredoc, then invoke:

   bash .agents/skills/pr-push/scripts/pr_push.sh \
     --title-file /tmp/pr-title.txt \
     --summary-file /tmp/pr-summary.txt \
     --rationale-file /tmp/pr-rationale.txt
   

   • The legacy positional form still works for simple single-line content:

   bash .agents/skills/pr-push/scripts/pr_push.sh "<pr title>" "<summary>" "<rationale>"
   

   The script pushes the current branch, then either creates a new PR or updates the existing one with the synthesized content.
9. If step 7 applied, leave a top-level PR comment with the demo video after the PR exists:
   • Use the hosted Vercel Blob URL from $create-video-demo.
   • Use the comment body generated by $create-video-demo.
   • Keep the final comment to: Demo at commit {hash}, a 1-2 sentence summary, and the durable demo URL.
10. Report the final commit message, branch name, and PR URL back to the user.

PR Description Guidelines

• Lead with purpose. The first sentence should answer "why does this PR exist?"
• Summarize the what briefly. One or two sentences covering the approach — not a line-by-line diff walkthrough.
• Never bullet-list individual file changes. The diff is right there; don't duplicate it.
• Preserve prior context. When updating an existing PR, the previous description was written for a reason. Synthesize, don't replace.

PR Body Format

The helper script creates this structure:

<summary>

<details>
<summary>Rationale</summary>

<rationale>
</details>

Keep the summary concise and the rationale substantive. Avoid dumping raw diffs or test logs into the PR body unless they materially help review.

Script

Use pr_push.sh for the push and PR creation step instead of retyping git push and gh pr create manually.