Skip to content

pivoshenko/pivoshenko.ai / skills/git-pr-create

git-pr-create

Verified

Open a GitHub pull request for the current branch using `gh` - conventional title, repo-template-aware body, auto-derived labels, push if needed. Use for every PR-creation request however casual: "create/open/raise a PR", "PR this", "send PR", "/git-pr-create", "ship this", "ship it", "send for review", "ready for review", "publish this branch", or whenever the user signals work on a feature branch should leave their machine. A raw `gh pr create` skips the push, label derivation, title format, and safety rules this skill owns. Boundary with `git-commit`: an explicitly local framing ("commit this", "save my work", "ship this locally") stops at a commit. Pushes the branch and opens the PR immediately without asking for confirmation.

Git PR Create

Open GitHub PR for current branch. No confirm.

Flow

  1. Base: user names one -> use it. Else detect: git symbolic-ref --short refs/remotes/origin/HEAD -> strip the origin/; ref missing -> git remote set-head origin -a, re-read; no remote -> stop; a PR needs a GitHub remote. Why -> a wrong base makes the PR diff include commits that aren't yours
  2. git fetch origin <base>. Why -> everything below compares against origin/<base>, not the local ref: the local base is often stale or absent entirely (git-branch-create branches off origin/<base> without ever creating it), so a local-ref diff either errors or replays commits already merged
  3. Parallel:
    • git status
    • git branch --show-current
    • git log origin/<base>..HEAD --oneline
    • git diff origin/<base>...HEAD
    • Linked issue, three sources, merged and deduped: the branch link git config --get branch.$(git branch --show-current).issue (git-issue-start records it there), the branch's commit footers git log origin/<base>..HEAD --format=%B | grep -oiE '(closes|fixes|resolves) #[0-9]+', and a trailing ticket id on the branch name (git-branch-create's optional -PROJ-123 suffix). Why -> git-issue-start opens the branch from an issue and git-commit writes the closing trailer, so the number is already on the branch; nobody retypes it
      • Exactly 1 distinct issue -> fill the Resolves: line with it
      • More than 1 -> first fills Resolves:, the rest become Refs: #<n> lines under it. Why -> a PR closing several issues is normal, but only the primary one belongs in the template's Resolves slot
      • None -> drop the line entirely. Never emit a #<n> placeholder
    • Check repo PR template: .github/PULL_REQUEST_TEMPLATE.md, .github/pull_request_template.md, docs/PULL_REQUEST_TEMPLATE.md, root PULL_REQUEST_TEMPLATE.md (first match wins)
  4. 0 commits ahead -> stop. Tell user: nothing to PR; commit first via git-commit
  5. Not pushed / ahead -> git push -u origin <branch>. Diverged from upstream (post-rebase) -> stop; tell user to git push --force-with-lease themselves (same rule as git-branch-sync)
  6. Read all branch commits (not just latest). Draft title + body
    • Template found -> fill that template's structure (preserve headings, checklist items, comment placeholders)
    • No template -> use fallback body below
  7. Derive labels (always pass --label):
    • Fetch the repo's labels once: gh label list --limit 200 --json name -q '.[].name'. Why -> detection, not hardcoding: this skill syncs globally and runs on forks and third-party repos, where the bare names exist and a namespaced taxonomy does not

    • Resolve the title <type> through its candidate chain, first existing name wins:

      IntentCandidate chain
      feattype: enhancement -> enhancement -> feature
      fixtype: bug -> bug
      docstype: documentation -> documentation -> docs
      perfperformance -> type: enhancement -> enhancement
      refactor / chore / build / citype: maintenance -> maintenance -> chore
      testtype: maintenance -> tests -> test
      breaking change in commits/bodytype: breaking -> breaking-change -> breaking
    • Whole chain missing -> drop that label and say which in the output. Never gh label create

    • Exactly one type: * label per PR -> title type and breaking both resolving to type: * names, breaking wins and the title-type label is dropped

    • At least 1 label required -> all dropped, resolve the fallback chain type: maintenance -> maintenance -> chore. Nothing in it exists either -> surface to user and stop. Why -> label-driven tooling (changelog generators, triage filters) silently skips an unlabeled PR

    • Multi-word names must be quoted: --label "type: bug"

  8. Heredoc body so markdown survives shell:
    gh pr create --base <base> --title "feat(auth): add oauth login flow" --label "type: enhancement" --body "$(cat <<'EOF'
    # Pull Request Checklist
    
    Resolves: #123
    
    ## Summary
    
    - swap session cookies for OAuth flow against Google provider
    - persist user via existing `users` table
    
    ## Checklist
    
    - [ ] My code follows the project style guidelines
    - [ ] I have performed a self-review of my code
    EOF
    )"
    
    'EOF' quoted -> no shell interpolation. --base always passed explicitly -> without it gh targets the repo's default branch, silently ignoring a base the user named
  9. Print PR URL

Title

Same as commits:

<type>(<scope>): <short summary>
  • Type: build|chore|ci|docs|feat|fix|perf|refactor|test (same set + picks as git-commit). Mixed commit types on the branch -> the highest-ranked present wins: feat > fix > perf > refactor > rest
  • Scope: optional
  • Summary: imperative present, lowercase, no .
  • Whole title ≤ 72 chars (matches git-commit header limit)

Examples:

  • feat(auth): add oauth login flow
  • fix(api): handle timeout on retry
  • refactor: extract user service

Body - Repo Template Present

  • Use the repo template verbatim as the skeleton (headings, order, checklist items, HTML comments)
  • Fill Summary with 1-3 bullets, why > what. Obey Length below
  • Tick checklist items that actually apply; leave the rest unchecked
  • Template has a Resolves: / Closes: / Fixes: line -> fill it with the issue detected in step 3, extras as Refs: #<n> lines under it; nothing detected -> drop the line entirely (no #<n> placeholder)
  • Preserve untouched any sections you have no content for (e.g. empty Screenshots), unless template explicitly says "remove if N/A"
  • Extra prose headings (Context, Testing, Notes, ...) -> ≤ 2 lines each, or leave the placeholder. Never one paragraph per heading

Fallback Body Template

Use when no repo template exists -> fill references/pr-body.md.

  • Diff = what. Body = why
  • Issue detected in step 3 -> uncomment the Resolves: line, fill the first number, extras as Refs: #<n> lines under it. None detected -> leave both comment lines out
  • Breaking -> add ## Breaking changes section + migration notes

Length

Hard cap: 10 lines of prose for the whole body. Headings, checklists and template boilerplate don't count - only text you write.

  • Summary: 1-3 bullets, one line each, ≤ 100 chars. No sub-bullets, no paragraph bullets. Why the char cap -> GitHub soft-wraps, so "one line" alone doesn't bound anything
  • Breaking changes: ≤ 5 lines including migration steps
  • Any other prose section: ≤ 2 lines, or leave its placeholder untouched
  • Nothing to say -> leave the section empty. Silence beats filler

Prohibitions:

  • Why, not what - the diff shows what
  • No restating the title. No file lists, no code dumps, no diff walkthrough
  • No play-by-play ("first X, then Y"). No "this PR does ..."
  • No test-plan narration unless the template asks for one

Good:

## Summary

- swap session cookies for OAuth so sessions survive the API split
- reuse the existing `users` table; no migration needed

Bad - one paragraph per bullet, narrates the diff:

## Summary

- This pull request implements a comprehensive OAuth login flow. It
  replaces the previous session-cookie approach in `auth/session.ts`
  with a new `OAuthProvider` class that handles the token exchange.
- Changes include: adding `oauth.ts`, updating `middleware.ts`,
  refactoring `validateSession`, and updating the auth tests.

Rules

  • Always pass --base <base> - the same base resolved in step 1. Never let gh infer it
  • Never PR from main/master against main/master. On base -> stop + ask user to branch (use git-branch-create)
  • Never force-push here
  • Never --no-verify unless asked. Why -> pre-push hooks gate CI and secret scans; skipping ships broken code
  • Push or PR-create fail -> surface + fix root cause. No blind retry
  • Always add at least one label (resolved from title <type> through its candidate chain against gh label list). Multi-word labels -> quote: --label "type: bug". No reviewers / assignees unless asked
  • Open as ready-for-review (no --draft) unless user explicitly asks for a draft PR
  • Body over 10 prose lines -> cut before creating. No "comprehensive" PR descriptions. Body prose obeys Length
  • No "Generated with Claude Code" / co-author trailers unless asked
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 469kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall