/pr

name: pr
description: "Creates GitHub PR after pre-flight checks (lint/typecheck/tests), structured summary from commits. Triggers: pr, pull request, create PR, ready to merge."
effort: medium
disable-model-invocation: true
argument-hint: "[title or branch]"
allowed-tools: Bash, Read, Grep

Pull Request

$ARGUMENTS

Create a GitHub pull request.

Project context

• Recent commits: !`git log --oneline main..HEAD 2>/dev/null | head -20`

Usage

/pr [title]

Automated PR Summary Generation

Generate a structured PR summary from the commit history before writing the PR description:

python3 ${CLAUDE_SKILL_DIR}/scripts/pr-summary.py [base_branch]
# Default base branch: main
# Example: python3 ${CLAUDE_SKILL_DIR}/scripts/pr-summary.py develop

The script outputs JSON with:

• **title_suggestion**: auto-generated PR title from dominant commit type and scope
• **commits[]**: each commit parsed into type, scope, description (conventional commits)
• **groups**: commits grouped by type (Features, Bug Fixes, etc.)
• **summary_bullets**: ready-to-use summary lines for the PR body
• **has_breaking**: whether any BREAKING CHANGE markers were found
• **breaking_changes[]**: list of breaking change descriptions
• **files_changed**: total files in the diff
• **test_files_changed**: count of test files modified
• **has_tests**: whether the PR includes test changes

Use the output to populate the PR template fields below.

---

PR Creation Workflow

1. Pre-PR Checks

# Run CI checks
ruff check . && mypy src/ && pytest tests/

# Check branch status
git status
git diff main...HEAD --stat

2. Create PR

gh pr create --title "feat: add multi-hop reasoning" --body "$(cat <<'EOF'
## Summary
- Implement query decomposition for complex questions
- Add iterative retrieval with reasoning
- Include answer synthesis from aggregated context

## Test plan
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Manual testing with sample queries

Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

PR Template

## Summary
<1-3 bullet points describing changes>

## Changes
- [ ] Feature implementation
- [ ] Tests added/updated
- [ ] Documentation updated

## Test plan
- [ ] CI checks pass (lint, typecheck, tests)
- [ ] Manual testing completed
- [ ] No regressions

## Screenshots
<if applicable>

Generated with [Claude Code](https://claude.com/claude-code)

PR Checklist

Before creating PR:

• [ ] All tests pass: `pytest tests/`
• [ ] Linting passes: `ruff check .`
• [ ] Type checking passes: `mypy src/`
• [ ] Documentation updated if needed
• [ ] Commit messages follow conventional commits
• [ ] Branch is up to date with main

Useful gh Commands

# View PR
gh pr view

# Check PR status
gh pr checks

# Request review
gh pr edit --add-reviewer username

# Merge PR
gh pr merge --squash

Rules

• **MUST** run lint + typecheck + tests locally before opening the PR
• **NEVER** force-push `main` or `master`
• **NEVER** add `Co-Authored-By: Claude` or other AI attribution to commits
• **CRITICAL**: PR body must include a Test plan checklist — no exceptions
• **MANDATORY**: commit messages follow conventional commits (`feat:`, `fix:`, `docs:` etc.)

Gotchas

• `gh pr merge --squash` **drops** all original commit trailers, including `Co-Authored-By:` lines. If the PR had legitimate co-authors, note them in the squashed commit body or use `--rebase` instead.
• `gh` defaults to `github.com`; for GitHub Enterprise the host must be set per-repo with `gh auth login --hostname <host>` and `gh repo set-default`. Silent failures on enterprise usually mean the wrong host.
• Running `gh pr create` without `--body` opens an editor (`$EDITOR` or `vi`) — in non-interactive contexts this hangs indefinitely. Always pass `--body` or `--body-file`.
• The pre-flight `ruff check .` walks respecting `.gitignore` by default but `mypy src/` does not — if `src/` contains generated code excluded from git, mypy will still scan it and report spurious errors.
• `git diff main...HEAD` (triple dot) shows commits on HEAD since the merge-base; `git diff main..HEAD` (double dot) shows all differences including main's newer commits. Use triple-dot for PR-scope diffs.

When NOT to Use

• For creating a commit (without a PR) — use `/commit`
• For reviewing a PR someone else opened — use `/review`
• For drafting release notes across many PRs — use `/docs` or a release script
• When the branch has uncommitted changes — commit first, then open the PR