create-pr

What this skill does

# Create Pull Request

Create a PR/MR with a description that transfers your context to the reviewer. When you create a PR, you know everything about the change — the reviewer knows nothing. Your job is to bridge that gap.

Parse `$ARGUMENTS` for:
- Optional PR title (quoted string)
- `--context=path` — path to a context file with additional structured data (from player-coach or similar)
- `--no-comments` — skip inline review comments

## Phase 1: Git Mechanics

### 1. Store original branch

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

This becomes the PR target branch. All PRs go back to whatever branch you started from.

### 2. Check for existing PR/MR

```bash
# GitHub
gh pr view --json url,number 2>/dev/null

# GitLab
glab mr view --output json 2>/dev/null
```

If a PR/MR already exists:
- Store its URL, number, and base/target branch
- The current branch IS the feature branch — set `ORIGINAL_BRANCH` to the PR's base branch (from `gh pr view --json baseRefName` / MR target branch), not from `git branch --show-current`
- Skip steps 3-7 (branch, commit, push, labels are already done)
- Proceed to Phase 2 to update the description and add comments

### 3. Detect platform

```bash
REMOTE_URL=$(git remote get-url origin)
```

- Contains `github.com` → GitHub (use `gh`)
- Contains `gitlab.com` or other GitLab instance → GitLab (use `glab`)

Verify the CLI tool is installed (`which gh` / `which glab`). If not installed, provide installation instructions and stop.

### 4. Create feature branch

Generate a branch name from the PR title (if provided) or from analysis of the changes:
- New feature → `feature/brief-description`
- Bug fix → `fix/issue-description`
- Docs → `docs/update-description`
- Refactor → `refactor/component-name`

Rules: kebab-case, max 50 chars, valid git branch name. Add timestamp suffix if branch exists.

```bash
git checkout -b [branch-name]
```

### 5. Handle uncommitted changes

```bash
git status --porcelain
```

If changes exist, stage and commit on the feature branch. Generate a descriptive commit message from the changes. All commits happen on the feature branch, never the original.

### 6. Push

```bash
git push -u origin [feature-branch]
```

### 7. Fetch and filter labels

Fetch available labels first — never assume labels exist:

**GitHub:**
```bash
AVAILABLE_LABELS=$(gh label list --json name --jq '.[].name' 2>/dev/null || echo "")
```

**GitLab:**
```bash
AVAILABLE_LABELS=$(glab label list 2>/dev/null | cut -f1 || echo "")
```

If fetching fails, proceed without labels.

**Simple matching** — propose labels from:
- Branch name prefix: `feature/*` → "enhancement", `fix/*` → "bug", `docs/*` → "documentation"
- Commit message prefix: `feat:` → "enhancement", `fix:` → "bug", `docs:` → "documentation"

Only apply labels that exist in `AVAILABLE_LABELS`. If no matches, create PR without labels.

## Phase 2: Context Gathering

Understand the change deeply enough to write a useful description. Two paths depending on invocation:

### Path A: Context file provided (`--context=path`)

Read the context file. It contains structured data from the caller (e.g., player-coach):
- Plan summary
- Turn history / implementation journey
- Friction log (sticky issues, player concerns)
- Below-threshold issues
- CI failure log

Also read the diff for code-level understanding:
```bash
git diff $ORIGINAL_BRANCH..HEAD
git diff --stat $ORIGINAL_BRANCH..HEAD
```

If the context file includes a `## Testing Plan Hints` section, use those hints (user-facing flows, known edge cases, exerciser results) as a starting point for the Testing Plan.

### Path B: Standalone invocation (no context file)

Gather context yourself:

1. **Read the diff:**
   ```bash
   git diff $ORIGINAL_BRANCH..HEAD --stat
   git diff $ORIGINAL_BRANCH..HEAD
   ```
   For large diffs (20+ files), use `--stat` first and selectively read key files.

2. **Read the commit log:**
   ```bash
   git log $ORIGINAL_BRANCH..HEAD --format='%s%n%n%b---'
   ```

3. **Check for a plan file:**
   ```bash
   ls .claude/plans/*.md 2>/dev/null
   ```
   If found, read it — it explains the "why" behind the change.

4. **Check for issue references:**
   Scan commit messages for `#NNN` patterns. Fetch context:
   - GitHub: `gh issue view NNN --json title,body`
   - GitLab: `glab issue view NNN`

5. **Check for engineer skill:**
   ```bash
   ls .claude/skills/*-engineer/SKILL.md 2>/dev/null
   ```
   If found, read for architecture context.

6. **Identify testable user flows:** From the plan file (if found) and the diff, identify what the feature does from the user's perspective — what inputs it accepts, what outputs it produces, and what can go wrong. This feeds the Testing Plan section.

## Phase 3: Compose Rich PR Description

The description is the reviewer's primary entry point. Write it for someone who has zero context on this work.

### PR Title

PR titles appear in changelogs and release notes. They must be user-facing, not technical.

Write for end users: describe the user impact, not the code change. "Speed up page loading times" not "feat: implement Redis caching layer."

Templates:
- Features: "Enable [capability]", "Add support for [action]"
- Bug fixes: "Fix [user-visible problem]", "Prevent [behavior]"
- Improvements: "Improve [aspect] of [feature]", "Speed up [action]"

Avoid: class names, function names, file names, technical patterns (middleware, service, controller), implementation details (cache, queue, worker).

### PR Body Template

**Core sections (always present):**

```markdown
## Summary

{2-4 sentences: what was built/changed and WHY. Include the problem being
solved or the need being addressed. Write for someone with zero context.}

## Architecture

{ASCII diagram of component relationships, data flow, or request paths
relevant to the change. Show how the pieces fit together.

Skip this section for trivial changes (< 3 files, no new components,
pure bug fixes, config changes).}

## What Changed

{Changes grouped by component/area, not by file. Each item explains
WHAT and WHY at the component level.}

- **Area/Component**: What was done and why
- **Another area**: What was done and why
- **Tests**: Summary of test coverage added

## Reviewer Guide

{Help the reviewer navigate the change efficiently.}

- **Start here**: {entry point file/function — where to begin reading}
- **Pay attention to**: {areas that are tricky, non-obvious, or critical}
- **Design decision**: {choices made and why, alternatives considered}
```

**Testing plan (always present):**

```markdown
## Testing Plan

{A manual QA checklist for the human reviewer. Write concrete steps for
someone who has never seen this feature. Generate from the plan, the diff,
friction points (which are natural edge cases), and implementation details.}

### Happy Path
- [ ] {concrete action — "Open /settings, click 'Add API Key'"}
- [ ] {verify expected result — "Key appears in the list, status shows 'Active'"}

### Edge Cases
- [ ] {edge case — "Submit with empty required fields, verify validation errors"}
- [ ] {edge case — "Enter special characters / very long input"}
- [ ] {edge case — "Perform action while offline or with slow connection"}

### Regression Checks
- [ ] {anything that might have broken — "Existing feature X still works as before"}
```

**Additional sections when context file is provided (e.g., from player-coach):**

```markdown
## Implementation Journey

{Turn history and narrative from the context file. Include the turn table
and a brief narrative if the run was rough.}

## Friction Log

{Only if friction occurred. Each item references specific files/lines
and explains what was hard, why, and what the human should check.
Omit entirely for clean runs.}

## Below-Threshold Issues

{Issues that passed the severity bar but the reviewer may want to address.
Omit if none.}
```

### Guidance for writing the description

- **Summary**: Synthesize, don't paste. If a plan exists, distill its goals in