pr-create

What this skill does

# PR Creator Skill

Get changes into a PR, monitor CI, fix any failures, and notify the user when the PR is ready for review.

The user may already have commits ready on a feature branch, or may have uncommitted changes, or both. Adapt the workflow to the current state.

## Task List Integration

**CRITICAL:** Use Claude Code's task list system for progress tracking and session recovery. Use TaskCreate, TaskUpdate, and TaskList tools throughout execution.

### Task Hierarchy
```
[Main Task] "Create PR: [branch-name]"
  └── [CI Task] "CI Run #1" (status: failed, reason: lint)
      └── [Fix Task] "Fix: lint"
  └── [CI Task] "CI Run #2" (status: failed, reason: test failures)
      └── [Fix Task] "Fix: test failures"
  └── [CI Task] "CI Run #3" (status: passed)
```

**At the start, always call TaskList to check for existing PR tasks.** If a "Create PR" task exists with status in_progress, resume using the Session Recovery section below.

## Process

### Step 1: Assess Current State

**Check for a `--reviewer` argument** in the user's message. If present, store the value for use in Step 5. It may be a GitHub handle (`@username`) or a name (`Jane Doe`).

**Create the main PR task:**
```
TaskCreate:
- subject: "Create PR: [branch-name or 'pending']"
- description: "Create pull request from current changes."
- activeForm: "Checking git status"

TaskUpdate:
- taskId: [pr task ID]
- status: "in_progress"
```

Determine the base branch and current state:

```bash
git status
git diff --stat
# Detect the default branch (main, master, develop, etc.)
gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name'
git log --oneline <base-branch>..HEAD
gh pr view 2>/dev/null
```

**Determine the starting point:**

| State | Next Step |
|-------|-----------|
| On base branch with uncommitted changes | Step 2 (create branch) |
| On feature branch with uncommitted changes | Step 3 (commit) |
| On feature branch with commits, nothing uncommitted | Step 4 (sync) |
| PR already exists for this branch | Inform user, ask whether to update or monitor CI |
| No changes anywhere | Inform user "No changes detected. Nothing to do." and stop |

**Update task with branch info:**
```
TaskUpdate:
- taskId: [pr task ID]
- subject: "Create PR: [actual-branch-name]"
- metadata: {"branch": "[branch-name]", "baseBranch": "[base-branch]"}
```

### Step 2: Create Branch (if needed)

If currently on the base branch:
```bash
git checkout -b <descriptive-branch-name>
```

Use the project's branch naming conventions if documented in CLAUDE.md or AGENTS.md. Otherwise use:
- `feat/short-description` for features
- `fix/short-description` for bug fixes
- `refactor/short-description` for refactoring
- `docs/short-description` for documentation

### Step 3: Stage and Commit Changes (if needed)

**Skip this step entirely if there are no uncommitted changes.**

Stage specific files rather than using `git add -A`:

```bash
git status
git add <file1> <file2> ...
git diff --cached --stat
git commit -m "$(cat <<'EOF'
<type>: <short summary>

<optional longer description>
EOF
)"
```

Follow the project's commit conventions if documented in CLAUDE.md or AGENTS.md. Otherwise use conventional commits: `feat:`, `fix:`, `refactor:`, `docs:`, `test:`, `chore:`.

**If the commit fails due to a pre-commit hook:**
1. Read the error output to understand what the hook requires
2. Fix the flagged issues
3. Stage the fixed files
4. Create a **new** commit (do NOT amend the previous commit)

### Step 4: Sync with Base Branch (if needed)

```bash
git fetch origin
git log --oneline HEAD..origin/<base-branch> | head -20
```

**If up to date** (no output), proceed to Step 5.

**If behind**, inform the user how many commits behind and offer options using `AskUserQuestion`:

1. **Rebase** (recommended when no PR exists yet)
2. **Merge** (safer with many commits or shared branches)
3. **Skip** (proceed without syncing)

**Do NOT rebase or merge without user confirmation.**

If conflicts arise, inform the user and help resolve them.

### Step 5: Draft PR Title and Body

**Get user approval on the PR content now**, before running pre-flight checks. This keeps the user engaged while they're focused on the task.

**5a. Gather context:**

```bash
git log --oneline <base-branch>..HEAD
git diff <base-branch>...HEAD --stat
```

**5b. Draft the PR title and body:**

Follow the project's PR conventions if documented in CLAUDE.md or AGENTS.md. Otherwise:

- **Title:** Under 70 characters, describes the change
- **Body:** Start with issue references on the first line (e.g. `Closes #45`), then a structured description:

```markdown
[issue references: Fixes #...]

## Summary
<summary>

## Verification
<how to verify>
```

Summary: Give an overview of the changes in the PR. The target audience is an experienced developer who works in this code base and needs to be informed about design or architectural changes. Highlight key decisions, structures and patterns.

Verification: include an example that demonstrates the changes in the PR as seen or used by the intended audience. For code packages, include a small, reproducible exmaple. For apps and interfaces, describe the steps required to see the new behavior.

**5c. Preview and get user approval:**

**CRITICAL:** Use `AskUserQuestion` to show the user the proposed PR title and body. Also include a reviewer question in this same interaction:

- If a `--reviewer` was provided, resolve and confirm the GitHub handle (see below), then show it as part of the preview.
- If no reviewer was given, ask in the same `AskUserQuestion` call whether they want to request a review from anyone (free-text, optional).

**Resolving a reviewer by name (not handle):**
If the reviewer value doesn't look like a GitHub handle (no `@`, not clearly a username), look up the correct handle from collaborators with push access:
```bash
scripts/find-collaborator.sh {owner}/{repo} "<name>"
```
Confirm the resolved handle with the user before storing it.

Store the confirmed reviewer handle in task metadata:
```
TaskUpdate:
- taskId: [pr task ID]
- metadata: {"reviewer": "<github-handle>"}
```

Present the PR draft to the user for review. If the `plannotator-annotate` skill is available, write the PR draft to a temporary file and use the skill to request feedback from the user on the title, body, and reviewer.

Follow up with an `AskUserQuestion` call to confirm before moving forward.

1. Are you ready to create the PR with the drafted title and description?
  1. **"Looks good, proceed"** *(default)* — approve and immediately continue to Step 6
  2. **"Looks good, tell me what you'll do next"** — approve but show the plan outline before continuing
2. Do you want to request a review from anyone? (free-text, optional)

Do NOT create the PR until the user has explicitly confirmed you should proceed.

**5d. Show plan outline (only if user selected option 2):**

Present the following before continuing:

> Here's what I'll do next:
>
> 1. **Run local checks** (if available for this project)
> 2. **Push** the branch to origin
> 3. **Create the PR** as a draft with the approved title and body
> 4. **Monitor CI** and fix any failures
> 5. **Publish the PR** (remove draft status) once CI passes
> 6. **Request a review** from `@<reviewer>` (if applicable)
>
> I'll auto-fix small issues (formatting, lint, type errors, test failures). If anything bigger comes up, I'll check with you first.

After showing the outline, ask one more `AskUserQuestion` to confirm before proceeding to Step 6.

### Step 6: Run Local Pre-flight Checks

**This step catches most CI failures before pushing.**

Determine the project's local check commands by consulting (in priority order):
1. CLAUDE.md or AGENTS.md in the project root (may specify lint, test, build commands)
2. Project config files: `package.json` (scripts), `Makefile`, `pyproject.toml`, `DESCRIPTION`, `Justfile`, `Taskfile.yml`, etc.
3. CI workflow files in `.github/workflows/` to understand w