create-pr

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.