Pr

---
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:

```bash
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:

    ```bash
    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:

        ```bash
        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:

        ```bash
        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](https://gitmoji.dev) 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`](../../../.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.

    ```markdown
    ## 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