|
| 1 | +--- |
| 2 | +description: Create a PR on GitHub for the current branch |
| 3 | +argument_hint: "[branch] [--dry] [--draft]" |
| 4 | +allowed_tools: Bash, Read, Glob, Grep, Write, AskUserQuestion, mcp__github__create_pull_request, mcp__github__list_pull_requests, mcp__github__get_file_contents, mcp__github__issue_read |
| 5 | +--- |
| 6 | + |
| 7 | +Create a PR on GitHub using the `gh` CLI for the currently checked-out branch. |
| 8 | + |
| 9 | +**Examples:** |
| 10 | +- `/pr` - Interactive mode, prompts for PR type |
| 11 | +- `/pr master` - Interactive with explicit base branch |
| 12 | +- `/pr --dry` - Generate description only, save to `.ai/` |
| 13 | +- `/pr --draft` - Create as draft PR |
| 14 | +- `/pr develop --draft` - Draft PR against non-default branch |
| 15 | + |
| 16 | +## Steps |
| 17 | + |
| 18 | +### 1. Check for Existing PR |
| 19 | +Run `gh pr view --json number,url 2>/dev/null` to check if a PR already exists for this branch. |
| 20 | +- If PR exists: Output `PR already exists: [URL]` and stop |
| 21 | +- If no PR: Continue |
| 22 | + |
| 23 | +### 2. Parse Arguments |
| 24 | +- `--dry`: Skip PR creation, only generate and save description |
| 25 | +- `--draft`: Create PR as draft |
| 26 | +- First non-flag argument: base branch (default: auto-detected, see Step 2.5) |
| 27 | +- **If no flags provided**: Use `AskUserQuestion` to prompt user: |
| 28 | + - Open PR (create and publish) |
| 29 | + - Draft PR (create as draft) |
| 30 | + - Dry run (save locally only) |
| 31 | + |
| 32 | +### 2.5. Determine Base Branch |
| 33 | +If no base branch argument provided, detect the repo's default branch: |
| 34 | +- Run: `git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'` |
| 35 | +- Use result as default (typically `main` or `master`) |
| 36 | +- If command fails, fall back to `master` |
| 37 | + |
| 38 | +### 3. Gather Context |
| 39 | +- Get current branch name: `git branch --show-current` |
| 40 | +- Extract repo identifier: `git remote get-url origin | sed 's/\.git$//' | sed -E 's#.*[:/]([^/]+/[^/]+)$#\1#'` (e.g., `synonymdev/bitkit-ios`) |
| 41 | +- Read PR template from `.github/pull_request_template.md` |
| 42 | +- Fetch 10 most recent PRs (open or closed) from the extracted repo for writing style reference |
| 43 | +- Run `git log $base..HEAD --oneline` for commit messages |
| 44 | +- Run `git diff $base...HEAD --stat` for understanding scope of changes |
| 45 | + |
| 46 | +### 4. Extract Linked Issues |
| 47 | +Scan commits for issue references: |
| 48 | +- Pattern to match: `#123` (just the issue number reference) |
| 49 | +- Extract unique issue numbers: `git log $base..HEAD --oneline | grep -oE "#[0-9]+" | sort -u` |
| 50 | +- Fetch each issue title: `gh api "repos/$REPO/issues/NUMBER" --jq '.title'` (using repo from Step 3) |
| 51 | +- These will be used to start the PR description with linking keywords (see Step 6) |
| 52 | + |
| 53 | +### 5. Identify Suggested Reviewers |
| 54 | +Find potential reviewers based on: |
| 55 | +- `.github/CODEOWNERS` file patterns (if exists) |
| 56 | +- Recent contributors to changed files: `git log --format='%an' -- $(git diff $base..HEAD --name-only) | sort | uniq -c | sort -rn | head -3` |
| 57 | +- Exclude the current user from suggestions |
| 58 | + |
| 59 | +### 6. Generate PR Description |
| 60 | +Starting from the template in `.github/pull_request_template.md`: |
| 61 | + |
| 62 | +**Title Rules:** |
| 63 | +- Format: `prefix: title` (e.g., `feat: add user settings screen`) |
| 64 | +- Keep under 50 characters |
| 65 | +- Use branch name as concept inspiration |
| 66 | +- Prefixes: `feat`, `fix`, `chore`, `refactor`, `docs`, `test` |
| 67 | + |
| 68 | +**Issue Linking (at the very start):** |
| 69 | +If linked issues were found in commit messages, begin the PR description with linking keywords: |
| 70 | +- Use `Fixes #123` for bug fixes |
| 71 | +- Use `Closes #123` for features/enhancements |
| 72 | +- One per line, before the "This PR..." opening separated by one empty line |
| 73 | +- Reference: https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/using-keywords-in-issues-and-pull-requests |
| 74 | + |
| 75 | +Example: |
| 76 | +``` |
| 77 | +Fixes #528 |
| 78 | +Closes #418 |
| 79 | +
|
| 80 | +This PR adds support for... |
| 81 | +``` |
| 82 | + |
| 83 | +**Opening Format:** |
| 84 | +- Single change: Start with "This PR [verb]s..." as a complete sentence |
| 85 | + - Example: `This PR adds a Claude Code /pr command for generating PRs.` |
| 86 | +- Multiple changes: Start with "This PR:" followed by a numbered list |
| 87 | + - Example: |
| 88 | + ``` |
| 89 | + This PR: |
| 90 | + 1. Adds a Claude Code /pr command for generating PRs |
| 91 | + 2. Fixes issue preventing Claude Code reviews to be added as PR comments |
| 92 | + 3. Updates reviews workflow to minimize older review comments |
| 93 | + ``` |
| 94 | +- Each list item should start with a verb (Adds, Fixes, Updates, Removes, Refactors, etc.) |
| 95 | +
|
| 96 | +**Description Rules:** |
| 97 | +- Base content around all commit messages in the branch |
| 98 | +- Use branch name as the conceptual anchor |
| 99 | +- Match writing style of recent PRs |
| 100 | +- Focus on functionality over technical details |
| 101 | +- Avoid excessive bold formatting like `**this:** that` |
| 102 | +- Minimize code and file references like `TheClassName` or `someFunctionName`, `thisFileName.ext` |
| 103 | +- Exception: for refactoring PRs (1:10 ratio of functionality to code changes), more technical detail is ok |
| 104 | +
|
| 105 | +**QA Notes / Testing Scenarios:** |
| 106 | +- Structure with numbered headings and steps |
| 107 | +- Make steps easily referenceable |
| 108 | +- Be specific about what to test and expected outcomes |
| 109 | +
|
| 110 | +**For library repos (has `bindings/` directory or `Cargo.toml`):** |
| 111 | +Structure QA Notes around testing and integration: |
| 112 | +
|
| 113 | +Example: |
| 114 | +``` |
| 115 | +### QA Notes |
| 116 | + |
| 117 | +#### Testing |
| 118 | +- [ ] `cargo test` passes |
| 119 | +- [ ] `cargo clippy` clean |
| 120 | +- [ ] Android bindings: `./build_android.sh` |
| 121 | +- [ ] iOS bindings: `./build_ios.sh` |
| 122 | + |
| 123 | +#### Integration |
| 124 | +- Tested in: [bitkit-android#XXX](link) |
| 125 | +- Or N/A if internal refactor with no API changes |
| 126 | +``` |
| 127 | +
|
| 128 | +**Preview Section (conditional):** |
| 129 | +Only include if the PR template (`.github/pull_request_template.md`) contains a `### Preview` heading: |
| 130 | +- Create placeholders for media: `IMAGE_1`, `VIDEO_2`, etc. |
| 131 | +- Add code comment under each placeholder describing what it should show |
| 132 | +- Example: `<!-- VIDEO_1: Record the send flow by scanning a LN invoice and setting amount to 5000 sats -->` |
| 133 | +
|
| 134 | +### 7. Save PR Description |
| 135 | +Before creating the PR: |
| 136 | +- Get next PR number: `gh api "repos/$REPO/issues?per_page=1&state=all&sort=created&direction=desc" --jq '.[0].number'` then add 1 (using repo from Step 3) |
| 137 | +- Create `.ai/` directory if it doesn't exist |
| 138 | +- Save to `.ai/pr_NN.md` where `NN` is the predicted PR number |
| 139 | +
|
| 140 | +### 8. Create the PR (unless --dry) |
| 141 | +If not dry run: |
| 142 | +```bash |
| 143 | +gh pr create --base $base --title "..." --body "..." [--draft] |
| 144 | +``` |
| 145 | +- Add `--draft` flag if draft mode selected |
| 146 | +- If actual PR number differs from predicted, rename the saved file |
| 147 | + |
| 148 | +### 9. Output Summary |
| 149 | + |
| 150 | +**If PR created:** |
| 151 | +``` |
| 152 | +PR Created: [PR URL] |
| 153 | +Saved: .ai/pr_NN.md |
| 154 | +
|
| 155 | +Suggested reviewers: |
| 156 | +- @username1 (X files modified recently) |
| 157 | +- @username2 (CODEOWNER) |
| 158 | +``` |
| 159 | + |
| 160 | +**If dry run:** |
| 161 | +``` |
| 162 | +Dry run complete |
| 163 | +Saved: .ai/pr_NN.md |
| 164 | +
|
| 165 | +To create PR: /pr [--draft] |
| 166 | +
|
| 167 | +Suggested reviewers: |
| 168 | +- @username1 (X files modified recently) |
| 169 | +- @username2 (CODEOWNER) |
| 170 | +``` |
| 171 | + |
| 172 | +**Media TODOs (only if Preview section was included):** |
| 173 | +If the PR description includes a Preview section with media placeholders, append: |
| 174 | +``` |
| 175 | +## TODOs |
| 176 | +- [ ] IMAGE_1: [description] |
| 177 | +- [ ] VIDEO_2: [description] |
| 178 | +``` |
| 179 | +List all media placeholders as TODOs with their descriptions. |
0 commit comments