create-pr

# Create Pull Request

Create a well-formatted GitHub pull request for the current branch. The PR description must conform to the repository's PR template (`.github/PULL_REQUEST_TEMPLATE.md`).

## Arguments

`$ARGUMENTS` can be used for special instructions, such as:
- Specifying a base branch: "use base branch: develop"
- Guiding the summary: "emphasize the performance improvements in the summary"
- Adding context: "this is part of the auth refactor epic"
- Any other guidance for PR creation

Default base branch: `main` (unless specified in arguments)

## Step 1: Gather Information

Run these commands in parallel to understand the changes:

1. **Current branch**: `git branch --show-current`
2. **Uncommitted changes**: `git status --porcelain`
3. **Commits on branch**: `git log origin/main..HEAD --oneline`
4. **File changes summary**: `git diff --stat origin/main..HEAD`
5. **Full diff**: `git diff origin/main..HEAD`
6. **Recent commit style**: `git log -5 --oneline` (to match PR title convention)
7. **Repo info**: `gh repo view --json nameWithOwner -q '.nameWithOwner'` (for constructing file URLs)

**Important checks:**
- If uncommitted changes exist, warn the user and ask if they want to commit first
- If no commits ahead of main, inform the user there's nothing to PR
- If branch isn't pushed, you'll push it in Step 4

## Step 2: Analyze and Categorize Changes

Use change types below to **decide** how to write the Changes section (flat vs grouped). You still describe testing under **Testing**, not under these buckets.

### By change type (internal checklist)
- ✨ **Added**: New files, features, capabilities
- 🔧 **Changed**: Modified existing functionality
- 🗑️ **Removed**: Deleted files or features
- 🐛 **Fixed**: Bug fixes
- 📚 **Docs**: Documentation updates
- 🧪 **Tests**: Test additions/modifications

### When to use optional grouping in **Changes**
- **Flat bullet list** (default): Small PRs, single theme, or when categories would be sparse or redundant.
- **Grouped subheadings** (`### ✨ Added`, `### 🔧 Changed`, `### 🗑️ Removed`, `### 🐛 Fixed`): Large PRs, release-note-style summaries, or clearly distinct fix + feature mixes. **Omit any empty section** — do not leave placeholder headings.

### Identify attention areas
Flag for special reviewer attention:
- Files with significant changes (>100 lines)
- Changes to base classes, interfaces, or public API
- New dependencies (`pyproject.toml`, `requirements.txt`)
- Configuration schema changes
- Security-related changes

## Step 3: Generate PR Title

Use conventional commit format matching the repo style:
- `feat:` for new features
- `fix:` for bug fixes
- `docs:` for documentation
- `refactor:` for refactoring
- `chore:` for maintenance
- `test:` for test changes

If commits have mixed types, use the primary/most significant type.

## Step 4: Create the PR

1. **Push branch** (if needed):
   ```bash
   git push -u origin <branch-name>
   ```

2. **Build the PR body** using the repository's template structure.

**Default — flat Changes** (remove the HTML comment block from the template when filling in, or replace with your bullets only):

```markdown
## 📋 Summary

[1-3 sentences: what this PR does and why. Focus on the "why".]

## 🔗 Related Issue

[Fixes #NNN or Closes #NNN — link to the issue this addresses]

## 🔄 Changes

- [Bullet list of key changes]
- [Link to key files when helpful for reviewers]
- [Reference commits for specific changes in multi-commit PRs]

## 🧪 Testing

- [x] `make test` passes
- [x] Unit tests added/updated (or: N/A — no testable logic)
- [ ] E2E tests added/updated (if applicable)

## ✅ Checklist

- [x] Follows commit message conventions
- [x] Commits are signed off (DCO)
- [ ] Architecture docs updated (if applicable)
```

**Optional — grouped Changes** (only when Step 2 criteria apply; omit empty sections):

```markdown
## 🔄 Changes

### ✨ Added
- [...]

### 🔧 Changed
- [...]

### 🐛 Fixed
- [...]
```

(Include `### 🗑️ Removed` only when something was deleted.)

If there are genuinely important attention areas for reviewers, add an **Attention Areas** section after Changes:

```markdown
## 🔍 Attention Areas

> ⚠️ **Reviewers:** Please pay special attention to the following:

- [`path/to/critical/file.py`](https://github.com/<owner>/<repo>/blob/<branch>/path/to/critical/file.py) — [Why this needs attention]
```

3. **Execute**:
   ```bash
   gh pr create --title "<title>" --body "$(cat <<'EOF'
   <body>
   EOF
   )"
   ```

4. **Return the PR URL** to the user.

## Section Guidelines

- **Summary**: Always include — be concise and focus on the "why", not just the "what"
- **Related Issue**: Always include if an issue exists. Use `Fixes #NNN` for bugs, `Closes #NNN` for features/tasks
- **Changes**: Default to a flat list. Use Added/Changed/Removed/Fixed subheadings only for large or mixed PRs; never emit empty subsection headings
- **Testing**: Check off items that apply. Mark N/A items explicitly rather than leaving them unchecked without explanation
- **Checklist**: Check off items that are true. Leave unchecked with a note if something doesn't apply
- **Attention Areas**: Only include if there are genuinely important items; omit for simple PRs
- **Links**: Include links to code and commits where helpful for reviewers:
  - **File links require full URLs** — relative paths don't work in PR descriptions
  - Link to a file: `[filename](https://github.com/<owner>/<repo>/blob/<branch>/path/to/file.py)`
  - Link to specific lines: `[description](https://github.com/<owner>/<repo>/blob/<branch>/path/to/file.py#L42-L50)`
  - Use the branch name (from Step 1) in the URL so links point to the PR's version of files
  - Reference commits: `abc1234` — GitHub auto-links short commit SHAs in PR descriptions
  - For multi-commit PRs, reference individual commits when describing specific changes

## Edge Cases

- **No changes**: Inform user there's nothing to create a PR for
- **Uncommitted work**: Warn and ask