---
name: pr-creation
description: >-
  Create well-structured GitHub pull requests with clear titles, summaries,
  and test plans. Use when the user asks to create a PR, open a pull request,
  push changes for review, or prepare a branch for merging.
---

# PR Creation

## PR Title

Follow the same Conventional Commits format used for commit messages:

```
<type>(<scope>): <concise description>
```

Keep it under 50 characters when possible. The title should tell a reviewer what this PR does at a glance.

## PR Description Template

```markdown
## Summary
<1-3 bullet points describing what changed and why>

## Test Plan
<How this was verified — tests added, manual steps, or both>
```

## Writing the Summary

- **What changed**: list the concrete changes, not implementation details.
- **Why**: one line of motivation if not obvious from the title.
- **Keep it short**: 1-3 bullets. If you need more, the PR may be doing too much.

Good:
```markdown
## Summary
- Add cursor-based pagination to all list endpoints
- Replace `offset`/`limit` query params with `cursor`/`pageSize`
```

Bad:
```markdown
## Summary
In this PR I refactored the pagination logic across the codebase. First I updated
the repository layer to accept cursor parameters, then I modified the service layer
to pass them through, then I updated all the handlers...
```

## Writing the Test Plan

Be specific about what was verified:

```markdown
## Test Plan
- Added unit tests for cursor encoding/decoding
- Tested manually with 10k records — no performance regression
```

If no tests were added, explain why:
```markdown
## Test Plan
- Config-only change, no logic affected
```

## Process

### Step 0: Handle Changes on master/main

Before anything else, check if the current branch is `master` or `main`:

```bash
current_branch=$(git branch --show-current)
```

If on `master`/`main` **and** there are uncommitted or staged changes:

1. Stash changes: `git stash`
2. Pull latest: `git pull origin master`
3. Create a new branch: `git checkout -b lirazh/<type>/<short-description>` (e.g., `lirazh/feat/add-auth`, `lirazh/fix/nil-pointer-users`)
4. Restore changes: `git stash pop`
5. Continue to Step 1 below.

**Never commit directly to master/main.** Always branch off first.

### Step 1: Split Large Changes into Small Commits

Before committing, analyze all changes with `git diff`. If the changes touch multiple concerns, split them into focused commits:

- Group by logical unit: one commit per feature, fix, refactor, or file group.
- Each commit should be independently meaningful — it should compile and make sense on its own.
- Use `git add -p` or `git add <specific files>` to stage changes selectively.
- Follow the [commit](../commit/SKILL.md) skill for each commit message.

Example — a change that adds a new endpoint and updates tests should become two commits:
```
feat(api): add user search endpoint
test(api): add tests for user search
```

If changes are small and cohesive, a single commit is fine.

### Step 2: Create the PR

1. Review all commits on the branch: `git log master..HEAD --oneline`
2. Review the full diff: `git diff master...HEAD`
3. Write a title that captures the primary intent.
4. Summarize changes as short bullets — focus on *what* and *why*, skip *how*.
5. Describe the test plan honestly.
6. Push and create the PR: `git push -u origin HEAD && gh pr create`

## Keeping the Description Current

The PR description must always reflect the full scope of the branch, not just the initial commit. After each new commit, the description is automatically updated as part of the [commit](../commit/SKILL.md) workflow.

When updating, re-derive the summary from `git log main..HEAD` and `git diff main...HEAD` — don't just append the new commit to the existing description. Rewrite the bullets to reflect the current state cleanly.

## Principles

- **Short, accurate, and concise.** Every sentence must add value. Cut filler, remove redundancy, say it once.
- The PR description is for the **reviewer**, not for you. Write what they need to understand the change.
- Don't repeat the diff in prose. Bullets pointing to the key decisions are enough.
- Prefer bullet points over paragraphs. No bullet should exceed one line.
- Link related issues or tickets in the summary when relevant (`Closes #123`).
- If the PR includes a breaking change, call it out explicitly at the top of the summary.