/create-pr

name: create-pr
description: Create a pull request with auto-generated description, issue linking, ROADMAP updates, and PR-metadata validation.

Create Pull Request

Create a pull request from the current branch with proper formatting and issue linking.

Command Options

All flags are optional. By default, the issue number is inferred from the branch name and the PR is created as ready-to-review.

• `--issue N`: Override automatic issue linking with a specific issue number (or comma-separated list: `--issue 123,175`)
• `--skip-issue-link`: Skip issue linking entirely
• `--draft`: Create PR as draft

Your task

1. **Verify prerequisites**:

• Confirm current branch is not `main`/`master`
• Check that branch has commits ahead of base branch
• Ensure branch is pushed to remote (push if needed)

2. **Generate PR title**:

• Use branch name as fallback
• If single commit ahead: use commit message as title
• If multiple commits: create descriptive title based on branch name and commit themes
• Follow Conventional Commits format from global CLAUDE.md

3. **Analyze commits for description**:

• Get commit history: `git log origin/<base-branch>..HEAD --oneline` (use the base branch identified in step 1)
• Group commits by type (feat, fix, docs, etc.)
• Identify patterns and overall theme

4. **Create comprehensive description**:

• **Summary section**: 2-3 bullet points describing what this PR does
• **Changes section**: Categorized list of changes from commits
• **Testing section**: How the changes should be tested
• **Notes section**: Any implementation details or decisions

5. **Update ROADMAP**:

• Check if the work corresponds to a checkbox item in `docs/prd/ROADMAP.md`
• If a matching item exists, mark it complete (`[x]`) and commit the change to the branch before creating the PR
• If no matching item exists, skip this step

6. **Identify and link related issues** (discover → classify → confirm; don't rely on recall):

• **If `--skip-issue-link`**: skip this step entirely.
• **Determine the primary issue(s) P:**
• `--issue N` (accepts a comma-separated list, e.g. `--issue 123,175`) → use directly as Close targets; skip discovery.
• Otherwise extract from the branch name (`fix/gh-123-...` → P=123). If none can be determined, warn and ask whether to proceed with no linking.
• **Discover candidates mechanically** (do not depend on having read the issue earlier in the session):
• Fetch the primary issue's body and comments: `gh issue view P --json number,title,body,comments`
• Extract every `#<number>` reference from that output.
• For each referenced issue M, get its state: `gh issue view M --json number,title,state` — drop anything already closed or that is a PR.
• **Classify each open candidate by the language around the mention:**
• `closes` / `fixes` / `resolves #M`, or M is an unchecked task-list item this PR completes → **Close** (`Closes #M`)
• `part of` / `blocked by` / `relates to` / `see` / `parent #M` → **Reference** (`Refs #M`, no closing keyword)
• ambiguous → default to **Reference** and flag it
• **Confirm before creating the PR:**
• Only the primary issue P, no other open candidates → proceed silently with `Closes #P`.
• More than one candidate, or any ambiguous one → print a short table (issue · title · proposed Close/Ref) and ask for a one-line confirm/override first.
• **Format:** one keyword per line so GitHub parses them all — `Closes #N` per close target, `Refs #N` per reference.

7. **Create the PR**:

• Use `gh pr create` with generated title and description
• Set base branch (usually main/master)
• **Default to ready** (no `--draft` flag) unless `--draft` flag is explicitly passed

8. **Confirm and validate**:

• Show PR URL and title
• Confirm issue linking (e.g., "✅ Linked to issue #123" or "⚠️ No issues linked")
• **Cross-check linking:** every Close/Ref target identified in step 6 actually appears in the final description. If one is missing, warn before the PR is considered done (guards against silently dropping a second issue).
• **Validate PR metadata (warn, don't block):** confirm the title follows Conventional Commits and the description contains a closing keyword (`Closes #N`). If either is missing, surface a warning so it can be fixed before review. (These checks previously lived in the retired `/review-pr`.)

PR Description Template

## Summary

- What this PR does
- Key changes made

## Changes

- List of changes from commits

## Testing

- [ ] Tests pass
- [ ] Manual testing done

Closes #123

Example Usage

# Default: Automatically detects issue from branch name (e.g., fix/gh-123-description)
/create-pr

# Explicit issue linking (when branch name doesn't contain an issue number)
/create-pr --issue 123

# Explicit multi-issue linking (PR closes more than one issue)
/create-pr --issue 123,175

# Skip issue linking entirely
/create-pr --skip-issue-link