---

name: pr description: Create a pull request

Create a pull request

I'll create a pull request for the current branch by following these steps. If any steps fail, stop.

Mode — check the arguments passed to this skill (shown at the end). If they include reviewed (or skip-review), an upstream step already ran the review and fixed its findings (e.g. /deliver's code-review phase via /review-changes), so skip steps 5–7 to avoid reviewing identical code twice. Otherwise (standalone /pr), run the internal review as normal.

Also skip steps 5–7 when the branch changes no reviewable code. Use /review-changes' own gate set, not a narrower one — committed scripts under .claude/workflows/ and Scripts/ are reviewable too, and a PR editing only Scripts/check-defaulted-witnesses.py changes a CI gate:

git diff --name-only origin/main...HEAD \
  | grep -qE '\.swift$|^\.claude/workflows/|^Scripts/' \
  || echo "no reviewable code → skip review"

(If the change rewrites the pipeline's own skills, don't skip — pass force-review to /review-changes; see its §0.)

1. Run /format to format code

2. Commit all outstanding work. Run git status. If the working tree has any uncommitted or unstaged changes (the feature work, plus the formatting from step 1), stage and commit them — the PR reflects committed history only, so anything left uncommitted will be missing from the PR. First verify no secrets, .env, or build artifacts are included (per CLAUDE.md — .env must stay gitignored; check git status before git add). Use a descriptive gitmoji message (or several logical commits if the work spans concerns); formatting-only changes can use "🎨 apply code formatting". If the tree is already clean (e.g. work was committed during /deliver), this is a no-op.

3. Rebase onto the latest origin/main. Fetch the remote and rebase the feature branch directly onto origin/main — do this before make ci so the gate (and the eventual PR) reflects the real merge result, not stale code:

   git fetch origin
   git rebase origin/main
   

   • Rebase onto origin/main, not local main — this is worktree-safe. A /deliver runs inside a git worktree, and git checkout main there fails (fatal: 'main' is already used by worktree …) whenever the main checkout is on main; rebasing onto origin/main avoids checking main out at all and uses the true remote base directly.
   • If git rebase reports conflicts, stop, resolve them, then continue. Never skip or force past a conflict you don't understand.
   • The rebase rewrites the branch tip, so a branch that was already pushed will need git push --force-with-lease at the push step below.
   • Already branched off an up-to-date origin/main with nothing to replay → this is a fast no-op.

4. Run the pre-PR gate — MANDATORY; it must pass before going further. Run it directly (do not delegate). If it fails, stop and fix — commit the fixes — then re-run; never open a PR on a red gate. Scale the gate to the diff:

   • Default — full make ci. The gate CLAUDE.md requires before any PR: lint, markdown lint, unit tests, integration tests, the release build, and the docs build. Use this whenever any code or build-affecting file changed.

   • Docs/config-only fast gate. When the diff touches no build- or test-affecting files — i.e. no *.swift and none of Makefile, Package.swift, Package.resolved, *.xctestplan, .github/workflows/**, or Tests/TMDbTests/Resources/** — the test/release-build legs of make ci have nothing to exercise. Run only the meaningful checks instead: make lint && make lint-markdown && make build-docs (drop build-docs if no *.docc/** changed). Detect this with:

     git diff --name-only origin/main...HEAD \
       | grep -qE '\.swift$|^Makefile$|^Package\.(swift|resolved)$|\.xctestplan$|^\.github/workflows/|^Tests/TMDbTests/Resources/' \
       && echo "code/build touched → full make ci" \
       || echo "docs/config-only → fast gate"
     

     JSON fixtures count as test-affecting. They are a build input of the TMDbTests target via .process("Resources") (Package.swift), so a fixture-only diff still has to run the unit suites — a re-captured value can break a decode assertion that no amount of lint will catch. .github/workflows/ci.yml's swift paths filter carries the same path for the same reason; keep the two in step.

     The PR's own CI still runs the full matrix regardless, so this only trims the local gate; it never lowers what actually guards main. When in doubt, run full make ci.

   • Re-lint new Swift files without the cache. make ci's lint leg is swiftlint --strict . (Makefile), and SwiftLint caches results (~/Library/Caches/SwiftLint). On newly-added .swift files this has been seen to report a false green locally — passing file_length / type_body_length that the PR's CI Lint job (a clean checkout, no cache) then fails on. So when the diff adds any new .swift file (git diff --name-only --diff-filter=A origin/main...HEAD | grep -q '\.swift$'), run a cache-bypassing lint before trusting the gate:

     swiftlint lint --strict --no-cache .
     

     Fix anything it flags (oversized files: split, or add a // swiftlint:disable directive matching the AccountService+Pagination.swift precedent) and re-run. This catches file-size violations locally instead of on a CI round-trip.

5. (skip in reviewed mode or when no reviewable code changed) Run the /review-changes skill — it scales the review to the diff (a single code-reviewer for a small change, the fan-out + adversarial-verify Workflow for a large one), follows .github/CODE_REVIEW.md, and returns a severity-graded report

6. (skip in reviewed mode or when no reviewable code changed) Summarize the code review findings:

   • List any critical or high-severity issues that should be addressed
   • List any medium-severity suggestions for improvement
   • Note any low-severity or stylistic recommendations

7. (skip in reviewed mode or when no reviewable code changed) If there are critical/high-severity issues:

   • Recommend specific changes needed
   • Ask user for confirmation before proceeding (fix issues or continue anyway)
   • If user wants to fix issues, stop and let them address the feedback

8. Ensure a clean working tree before pushing. Re-run git status; commit anything still outstanding (e.g. review fixes from steps 5–7, or make ci fixes) so the push includes everything. The tree must be clean before proceeding. Then run git diff origin/main...HEAD to understand all changes going into the PR.

9. Analyze the commits and changes to generate an appropriate title and summary

10. Push the current branch to remote (git push -u origin <branch> if not yet pushed; otherwise git push — use git push --force-with-lease if you rebased in step 3)

11. Create a PR with the GitHub MCP — mcp__github__create_pull_request (owner/repo from the origin remote, base: main, head: <branch>, plus title/body). The branch must already be pushed (step 10). If the call fails with 401/403 (PAT expired or missing scope), fall back to gh pr create with the same title/body.

    Title — MUST start with a gitmoji prefix matching the change:

    | Emoji | Code | Use for | |-------|------|---------| | ✨ | :sparkles: | New features | | 🐛 | :bug: | Bug fixes | | 📝 | :memo: | Documentation updates | | ♻️ | :recycle: | Refactoring | | ✅ | :white_check_mark: | Adding/updating tests | | 🔧 | :wrench: | Configuration changes | | ⚡️ | :zap: | Performance improvements | | 🎨 | :art: | Code style/formatting |

    Example: ✨ Add createdBy property to TVSeries.

    Body — fill this skeleton, keeping only the sections that apply, and end with the attribution line exactly as shown.

    Closes #NNN is required whenever the work has a tracked issue — drop the line only when it genuinely has none. It is not decoration: GitHub uses it to close the issue on merge, which is what carries the board item to Done, and /watch-pr reads it to move that item to In review when the PR goes green (see .github/ISSUE_FILING.md → Board status — the column lifecycle). Omit it and the issue stays open after merge and never leaves its column — silently, since nothing fails.

    ## Summary
    
    Closes #NNN.
    
    [Brief description of what this PR does and why]
    
    ## Changes
    
    **New Model/Feature/Component:**
    - ✨ [Description]
    
    **Existing Files:**
    - 📝 [Description]
    
    **Tests:**
    - ✅ [Description of test coverage]
    
    **Documentation:**
    - 📚 [Description]
    
    ## Benefits
    
    - **[Benefit Category]**: [Description]
    
    🤖 Generated with [Claude Code](https://claude.com/claude-code)
    

    The harness appends a claude.ai/code session link after the attribution line — that is expected; leave it in place.

$ARGUMENTS