---

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 code-reviewer and fixed its findings (e.g. /deliver's code-review phase), 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 Swift — code review is for Swift, so a docs-only / config-only PR needs none:

git diff --name-only origin/main...HEAD | grep -qE '\.swift$' || echo "no-swift → skip review"

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, or .github/workflows/** — 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/' \
       && echo "code/build touched → full make ci" \
       || echo "docs/config-only → fast gate"
     

     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 Swift changed) Spawn the code-reviewer agent to perform a code review of all changes (pass the git diff output as context)

6. (skip in reviewed mode or when no Swift 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 Swift 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:

    ## Summary
    
    [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)
    

$ARGUMENTS