---
name: pr
description: Use when opening a pull request for a jj revision, including pushing it first (/pr)
argument-hint: <revision> [ready|web]
allowed-tools: [Bash(jj diff *), Bash(jj log *), Bash(jj show *), Bash(jj bookmark list *)]
---

# Create Pull Request

Create a pull request using gh for a specified revision.

## Arguments

`$ARGUMENTS`

The first word is the revision — a bookmark, change ID, revset, or commit
hash. The second is optional:
- `ready`: creates a ready-for-review PR instead of draft
- `web`: opens a prepopulated PR in the browser for manual editing instead of creating it directly

When the argument is prose instead ("open a PR for the top two commits,
ready for review"), read it as instructions and work out the revision
yourself rather than treating its first word as one. Ask when that leaves
the revision ambiguous.

A revision is required either way, and gets resolved to a bookmark for the
PR. Every `<revision>` below means the one you resolved here.

## Process

1. Gather context for the PR:
   - Run `jj log -r '<revision>' --no-graph` to check for existing bookmarks
   - Run `jj log -r trunk..<revision>` to list commits between trunk and the revision
   - Run `jj diff --from trunk --to <revision> --stat` to review all changes
2. Push revision and get bookmark name:
   - If revision has a remote-tracked bookmark: `jj git push --bookmark <name>`
   - If revision has a local-only bookmark (no `@origin`): push with
     `jj git push --named <name>=<revision>` (pushes and auto-tracks)
   - If revision has no bookmark:
     1. Using all available context — the current session (what was discussed
        and why), the full set of commits from trunk to the revision, and the
        diff — generate a short kebab-case bookmark name that summarizes the
        overall PR purpose:
        - Prefix with `alpha/` (e.g., `alpha/fix-widget-layout`)
        - Lowercase, words joined by hyphens
        - Max ~50 chars (excluding prefix), truncate at a word boundary
        - Only alphanumeric and hyphens; no leading/trailing/double hyphens
     2. If a good name was generated, check `jj bookmark list` to ensure it's
        not taken (append `-2` etc. if it is), then push with
        `jj git push --named <generated-name>=<revision>`
     3. If there isn't enough context to produce a meaningful name,
        fall back to `jj git push -c <revision>`
   - Retrieve the bookmark name from the output
3. Consider whether the pending changes should be organized into smaller, easier
   to review commits. If so, use `jj split` or `jj squash` to reorganize before
   proceeding.
4. Check for .github PR templates and follow them. For checklist items that do
   not apply, use strikethrough: `- ~~Irrelevant item~~`
5. Invoke the `technical-writing` skill before drafting any prose.
6. Generate a PR title summarizing all commits in the changeset (not just the
   most recent). The title reflects the overall change, not individual commits.
7. Draft the PR summary: one to three sentences of prose on why the change
   was made and its impact. Three is a ceiling, not a target — one sentence a
   reviewer can't reconstruct from the diff beats three that pad around it. No
   headers or bullet lists unless a repository template requires them. Include
   only an "Assisted-by" footer for attribution, no "Generated with Claude
   Code".
   - Lead with user-facing impact and the tradeoff a reviewer would question.
   - Say nothing a reader gets from the diff or the file list. No "added
     function X" or "modified file Y".
   - Link related context found in the session — "Depends on #123", "Closes
     #456", a Slack permalink. Link lines don't count toward the budget.
   - Never wrap commit SHAs or PR/issue numbers in backticks—GitHub
     auto-links raw `a1b2c3d` and `#123` but backticks prevent it
   - Do not hard-wrap prose with manual newlines; GitHub wraps Markdown
     itself, so they render as awkward mid-sentence breaks
   - Delete pass before creating the PR: cut every sentence that summarizes
     the diff, restates the title, or exists to look thorough. If one
     sentence survives, ship one.
8. **Code review**: Review the diff from trunk to the revision before opening the
   PR. Fix anything that breaks correctness; note nits for later. Read
   `jj diff --git --from trunk --to <revision>` rather than the working
   directory, which may be on a different revision. `--git` gives a standard
   unified diff with `@@` hunk headers; the default color-words format prints two
   line-number columns (old, then new) and shows `..` in the old column for added
   lines, which is easy to misread when anchoring `file:line`.
9. Create the PR: `gh pr create --head <bookmark-name> --title "<title>"` using
   a HEREDOC to pass the body.
   - If `web` was specified: add `--web` flag (without `--draft` — they're
     incompatible) to open prepopulated PR in browser for manual editing,
     then stop (skip remaining steps)
   - If `ready` was specified: create directly without `--draft`
   - Otherwise: add `--draft` flag
10. **If a Jira card is detected**, transition it to "In Review":
    - Check workspace name or bookmark for pattern like `PROJ-123` (e.g., `LDE-488`)
    - If found: `acli jira workitem transition --key <KEY> --status "In Review"`
    - If not found, skip this step silently
11. Return the PR URL