pr-creator

What this skill does

# pr-creator

Write PR descriptions like a developer posting in Slack, not like an AI summarizing a diff.

## Reference Files

| File | Read When |
|------|-----------|
| `references/pr-polish.md` | When the commit history is noisy, the diff exceeds 500 lines, or the user asks to polish, tidy, restructure, or split the PR |

## Rules

1. **Title**: when a Linear ID is available, prefix the title with the real ID: `<LINEAR-ID>: Add auth flow`. For example, `ABC-123: Add auth flow`. Otherwise use `Add auth flow`. Keep it under 60 chars. No periods.
2. **Body**: default to one short paragraph. Explain what changed and why it matters.
3. **No fake why.** If the reason is not clear from the prompt, Linear issue, branch, commits, or diff, leave it out.
4. **Risk only when real.** Add one short `Risk:` line only for migrations, billing/auth/permission changes, irreversible writes, wide blast radius, or subtle behavior changes.
5. **Testing only if real.** Mention testing only when it was actually run. No `Test plan` section.
6. **No file-by-file changelogs.** The diff already shows the files.
7. **End after the useful content.** No generated-by footer or co-author line.

## Anti-patterns — never write these

- "This PR implements..."
- "This change ensures..."
- "This commit introduces..."
- "Refactored X to improve Y"
- "Updated the Z component to handle..."
- "Added comprehensive test coverage for..."
- "Ensured backwards compatibility with..."
- Lines that start with a filename or path
- A "Test plan" section with checkboxes
- A long list of bullets that restates the diff

## Before / after

**Bad** (default AI behavior):

```text
Title: Implement user authentication flow with session management and error handling

## Summary
- Added new `AuthProvider` component in `src/components/AuthProvider.tsx`
  that wraps the application with authentication context
- Implemented `useAuth` hook in `src/hooks/useAuth.ts` for login, logout,
  and session refresh functionality
- Updated `src/app/layout.tsx` to include the AuthProvider wrapper
- Added error boundary handling for authentication failures
- Configured session timeout to 30 minutes with automatic refresh

## Test plan
- [ ] Verify login flow works with valid credentials
- [ ] Verify login flow shows error with invalid credentials
- [ ] Verify session persists across page refreshes
- [ ] Verify automatic logout after 30 minutes of inactivity
- [ ] Verify the auth error boundary catches and displays auth failures
```

**Good** (what this skill produces):

Assume `ABC-123` is the real Linear ID for this example:

```text
Title: ABC-123: Add auth flow with session management

Adds the auth flow needed for session-based login, including refresh, timeout handling, and a small error boundary for auth failures.
```

## Command

After analyzing the diff and drafting the title and body, create the PR:

```bash
gh pr create --title "the final title here" --body "$(cat <<'EOF'
One short paragraph that explains what changed and why it matters.
EOF
)"
```

## Workflow

1. Run `git status`, `git diff`, and `git log` to understand the changes.
2. Find a Linear ID like `ABC-123` in the branch, commits, prompt, or PR context. If none exists, leave it out.
3. Push with `-u` if the branch has no upstream.
4. Draft title and body following the rules above.
5. If the repo has a PR template, respect it, but keep each answer short and do not add extra sections.
6. If the commit history is noisy (fixup, WIP, or "address review" commits) or the diff exceeds 500 lines, load `references/pr-polish.md` and restructure before creating the PR.
7. Create the PR with `gh pr create`.
8. Return the PR URL.

Do not ask the user to confirm the description before creating. The whole point is speed.