Creating Pr

⚠️ CRITICAL CONSTRAINTS

No Claude Code Footer Policy

YOU MUST NEVER add Claude Code attribution to pull requests.

• ❌ NO "🤖 Generated with [Claude Code]" in PR titles or descriptions
• ❌ NO "Co-Authored-By: Claude <noreply@anthropic.com>" in PR content
• ❌ NO Claude Code attribution, footer, or branding of any kind

Pull requests are public code review documents and must remain clean and professional.

---

GitHub PR Creation Workflow

Execute GitHub Pull Request workflows with automatic repository detection, branch management, and intelligent PR content generation.

Usage

This skill is invoked when:

• User runs /create-pr or /git:create-pr command
• User requests to create a pull request
• User asks to open a PR or push changes for review

How It Works

This skill handles the complete PR workflow:

1. Repository Detection - Detect current repository context (root or submodule) 2. Branch Validation - Verify not on protected branch, check for uncommitted changes 3. Branch Pushing - Ensure branch exists on remote 4. Existing PR Detection - Check if PR already exists for current branch 5. PR Content Generation - Create title and description from commits 6. PR Creation - Create or update PR using GitHub CLI

Supported Arguments

Parse arguments from user input:

• No arguments: Auto-detect repository and create PR to main branch
• `<scope>`: Direct PR for specific repository (root, submodule-name)
• `--draft`: Create as draft PR
• `--base <branch>`: Target branch (default: main)
• Combinations: <scope> --draft, root --base staging, etc.

Prerequisites

GitHub CLI Required: Must have gh installed and authenticated

# Install GitHub CLI (if not installed)
# macOS: brew install gh
# Linux: See https://cli.github.com/

# Authenticate
gh auth login

PR Creation Workflow Steps

Step 1: Parse Arguments

Extract scope, draft flag, and base branch from user input:

# Parse arguments
SCOPE=""
DRAFT_FLAG=""
BASE_BRANCH="main"

# Example parsing:
# "root --draft" → SCOPE="root", DRAFT_FLAG="--draft", BASE_BRANCH="main"
# "--base staging" → SCOPE="", DRAFT_FLAG="", BASE_BRANCH="staging"
# "my-service --draft --base develop" → SCOPE="my-service", DRAFT_FLAG="--draft", BASE_BRANCH="develop"

Step 2: Detect Repository Context

Find monorepo root and determine current repository:

# Find monorepo root (handles submodules)
if SUPERPROJECT=$(git rev-parse --show-superproject-working-tree 2>/dev/null) && [ -n "$SUPERPROJECT" ]; then
    # We're in a submodule
    MONOREPO_ROOT="$SUPERPROJECT"
else
    # We're in root or standalone repo
    MONOREPO_ROOT=$(git rev-parse --show-toplevel)
fi

# Get current working directory
CURRENT_DIR=$(pwd)

# Determine repository context
if [ -n "$SCOPE" ]; then
    # User specified scope
    if [ "$SCOPE" = "root" ]; then
        REPO_PATH="$MONOREPO_ROOT"
    else
        REPO_PATH="$MONOREPO_ROOT/$SCOPE"
    fi
else
    # Auto-detect from current directory
    # If in submodule, use submodule path
    # If in root, use root path
    if [[ "$CURRENT_DIR" == "$MONOREPO_ROOT" ]]; then
        REPO_PATH="$MONOREPO_ROOT"
    else
        # Find which submodule we're in
        REPO_PATH=$(git -C "$CURRENT_DIR" rev-parse --show-toplevel)
    fi
fi

# Validate repository
if [ ! -d "$REPO_PATH/.git" ]; then
    echo "❌ Error: Not a valid git repository: $REPO_PATH" >&2
    exit 1
fi

Step 3: Validate Branch State

Check current branch and uncommitted changes:

# Change to repository directory
cd "$REPO_PATH"

# Get current branch
CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD)

# Check if on protected branch
if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
    echo "❌ Cannot create PR from protected branch: $CURRENT_BRANCH" >&2
    echo "" >&2
    echo "Please create a feature branch first:" >&2
    echo "  git checkout -b feature/your-feature-name" >&2
    echo "" >&2
    exit 1
fi

# Check for uncommitted changes
UNCOMMITTED=$(git status --porcelain)
if [ -n "$UNCOMMITTED" ]; then
    echo "❌ Error: You have uncommitted changes" >&2
    echo "" >&2
    echo "Please commit or stash your changes before creating a PR:" >&2
    git status --short
    echo "" >&2
    exit 1
fi

# Check if branch has commits ahead of base
COMMITS_AHEAD=$(git rev-list --count "$BASE_BRANCH..HEAD" 2>/dev/null || echo "0")
if [ "$COMMITS_AHEAD" = "0" ]; then
    echo "❌ Error: No commits to create PR from" >&2
    echo "Current branch '$CURRENT_BRANCH' has no commits ahead of '$BASE_BRANCH'" >&2
    exit 1
fi

echo "ℹ️  Branch: $CURRENT_BRANCH ($COMMITS_AHEAD commits ahead of $BASE_BRANCH)"

Step 4: Push Branch to Remote

Ensure branch exists on remote:

# Check if branch exists on remote
REMOTE_BRANCH=$(git ls-remote --heads origin "$CURRENT_BRANCH" 2>/dev/null)

if [ -z "$REMOTE_BRANCH" ]; then
    echo "ℹ️  Branch not on remote, pushing..."
    git push -u origin "$CURRENT_BRANCH" || {
        echo "❌ Failed to push branch to remote" >&2
        exit 1
    }
    echo "✅ Branch pushed to origin/$CURRENT_BRANCH"
else
    # Check if local is behind remote
    LOCAL_HASH=$(git rev-parse HEAD)
    REMOTE_HASH=$(git rev-parse "origin/$CURRENT_BRANCH" 2>/dev/null || echo "")

    if [ "$LOCAL_HASH" != "$REMOTE_HASH" ]; then
        echo "ℹ️  Local branch differs from remote, pushing..."
        git push origin "$CURRENT_BRANCH" || {
            echo "❌ Failed to push branch to remote" >&2
            exit 1
        }
        echo "✅ Branch updated on remote"
    else
        echo "ℹ️  Branch already up to date on remote"
    fi
fi

Step 5: Check for Existing PR

Detect if PR already exists for this branch:

# Check for existing PR using GitHub CLI
EXISTING_PR=$(gh pr view "$CURRENT_BRANCH" --json number,title,url 2>/dev/null || echo "")

if [ -n "$EXISTING_PR" ]; then
    # PR exists - extract info
    PR_NUMBER=$(echo "$EXISTING_PR" | jq -r '.number')
    PR_TITLE=$(echo "$EXISTING_PR" | jq -r '.title')
    PR_URL=$(echo "$EXISTING_PR" | jq -r '.url')

    echo ""
    echo "ℹ️  Existing PR found:"
    echo "  #$PR_NUMBER: $PR_TITLE"
    echo "  $PR_URL"
    echo ""

    # Use AskUserQuestion to ask user what to do
    # Options:
    # 1. Update PR (regenerate title/body and update)
    # 2. View PR in browser (open URL)
    # 3. Cancel (do nothing)

    # If user chooses "Update PR":
    # - Generate new title and body (Steps 6-7)
    # - Update PR using: gh pr edit "$PR_NUMBER" --title "..." --body "..."
    # - Show success message

    # If user chooses "View PR":
    # - Open PR URL in browser: gh pr view --web

    # If user chooses "Cancel":
    # - Exit gracefully
fi

Step 6: Generate PR Title

Analyze commits to create conventional PR title:

# Get all commits from base branch to current branch
COMMITS=$(git log "$BASE_BRANCH..HEAD" --oneline)
COMMIT_COUNT=$(echo "$COMMITS" | wc -l | tr -d ' ')

echo "ℹ️  Analyzing $COMMIT_COUNT commits..."

# Get the first commit message (most recent)
LATEST_COMMIT=$(git log -1 --pretty=%B)

# Detect commit type from latest commit or analyze all commits
# Try to extract type from conventional commit format
if echo "$LATEST_COMMIT" | grep -qE '^(feat|fix|docs|refactor|test|chore|perf|ci|build):'; then
    # Extract type and description from conventional commit
    COMMIT_TYPE=$(echo "$LATEST_COMMIT" | grep -oE '^[a-z]+' | head -1)
    COMMIT_DESC=$(echo "$LATEST_COMMIT" | sed -E 's/^[a-z]+(\([^)]+\))?:\s*//')
else
    # Analyze changes to determine type
    ALL_COMMITS=$(git log "$BASE_BRANCH..HEAD" --pretty=%B)

    if echo "$ALL_COMMITS" | grep -qi "fix\|bug"; then
        COMMIT_TYPE="fix"
    elif echo "$ALL_COMMITS" | grep -qi "feat\|feature\|add"; then
        COMMIT_TYPE="feat"
    elif echo "$ALL_COMMITS" | grep -qi "docs\|documentation"; then
        COMMIT_TYPE="docs"
    elif echo "$ALL_COMMITS" | grep -qi "refactor"; then
        COMMIT_TYPE="refactor"
    elif echo "$ALL_COMMITS" | grep -qi "test"; then
        COMMIT_TYPE="test"
    else
        COMMIT_TYPE="feat"
    fi

    # Generate description from branch name or commit
    COMMIT_DESC=$(echo "$LATEST_COMMIT" | head -1 | sed 's/^\s*//')
fi

# Generate PR title (capitalize first letter)
PR_TITLE="$COMMIT_TYPE: $COMMIT_DESC"

echo "ℹ️  Generated PR title: $PR_TITLE"

Step 7: Generate PR Body

Create PR description with summary and test plan:

# Generate PR body with summary from commits
PR_BODY="## Summary

"

# Add commit summaries
if [ "$COMMIT_COUNT" -eq 1 ]; then
    # Single commit - use full message
    PR_BODY+="$LATEST_COMMIT

"
else
    # Multiple commits - list them
    PR_BODY+="This PR includes $COMMIT_COUNT commits:

"
    while IFS= read -r commit; do
        PR_BODY+="- $commit
"
    done <<< "$COMMITS"
    PR_BODY+="
"
fi

# Add test plan section
PR_BODY+="## Test Plan

- [ ] Code builds successfully
- [ ] Tests pass
- [ ] Manual testing completed
- [ ] Documentation updated (if needed)

## Changes

"

# List changed files
CHANGED_FILES=$(git diff --name-only "$BASE_BRANCH..HEAD")
while IFS= read -r file; do
    PR_BODY+="- \`$file\`
"
done <<< "$CHANGED_FILES"

echo ""
echo "Generated PR description:"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo "$PR_BODY"
echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
echo ""

Step 8: Create PR

Use GitHub CLI to create the PR:

# IMPORTANT: No Claude Code attribution in PR content

# Build gh pr create command
GH_CMD="gh pr create --title \"$PR_TITLE\" --body \"$PR_BODY\" --base \"$BASE_BRANCH\""

# Add draft flag if specified
if [ "$DRAFT_FLAG" = "--draft" ]; then
    GH_CMD+=" --draft"
fi

# Execute PR creation
eval "$GH_CMD" || {
    echo "❌ Failed to create PR" >&2
    exit 1
}

# Get PR URL
PR_URL=$(gh pr view --json url -q '.url')

echo ""
echo "✅ Pull Request created successfully!"
echo ""
echo "PR URL: $PR_URL"
echo ""
echo "Next steps:"
echo "  - Review PR in browser: gh pr view --web"
echo "  - Check CI status: gh pr checks"
echo "  - Request reviews: gh pr ready (if draft)"
echo ""

Alternative: Update Existing PR

If updating an existing PR (user chose "Update" in Step 5):

# Update PR title and body
gh pr edit "$PR_NUMBER" --title "$PR_TITLE" --body "$PR_BODY" || {
    echo "❌ Failed to update PR" >&2
    exit 1
}

echo "✅ Pull Request #$PR_NUMBER updated successfully!"
echo "PR URL: $PR_URL"

PR Title Generation Rules

The skill generates PR titles following conventional commit format:

Important Notes

1. GitHub CLI Required: Must have gh installed and authenticated

   gh auth login

2. Branch Protection: Cannot create PR from main/master branch

3. Existing PRs: Automatically detects and offers to update existing PRs

4. Commit-Based Content: PR title and body generated from commit messages

5. Works Anywhere: Executes from any directory, resolves paths absolutely

6. Submodule Support: Can create PRs for both root repository and submodules

7. Clean PR Content: No Claude Code attribution in PR titles or descriptions

GitHub CLI Commands Used

This skill uses the following gh commands:

# Check for existing PR
gh pr view <branch> --json number,title,url

# Create new PR
gh pr create --title "..." --body "..." --base <branch> [--draft]

# Update existing PR
gh pr edit <number> --title "..." --body "..."

# View PR in browser
gh pr view --web

# Check PR status
gh pr checks

Supporting Documentation

For detailed information, see:

• [WORKFLOW.md](WORKFLOW.md) - Step-by-step PR creation process including repository detection, branch management, and GitHub CLI integration
• [EXAMPLES.md](EXAMPLES.md) - Real-world PR scenarios covering features, bug fixes, drafts, and submodule PRs
• [TROUBLESHOOTING.md](TROUBLESHOOTING.md) - Common issues and solutions for GitHub CLI errors, authentication, and branch conflicts

GitHub Pull Request Creation: Examples

This document provides real-world examples of PR creation with the creating-pr skill.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md.

---

Example 1: Simple Feature PR

Scenario

Created a feature branch with authentication code, ready to create PR.

Command

/create-pr

Execution

Repository Detection:

Detected: myapp (root repository)
Branch: feat/003-user-authentication
Remote: origin

Branch Status:

✅ Not a protected branch
✅ Branch has 3 commits ahead of main

Push to Remote:

Branch not on remote, pushing...
✅ Pushed: origin/feat/003-user-authentication

PR Detection:

Checking for existing PR...
✅ No existing PR found

Content Generation:

Title: feat(auth): add user authentication

Body:
## Summary
- Implemented OAuth2 authentication flow
- Added token refresh mechanism
- Added comprehensive auth tests

## Test Plan
- [ ] Test OAuth2 login with Google provider
- [ ] Verify token refresh on expiration
- [ ] Run auth test suite: `npm test auth`

PR Creation:

Creating pull request for feat/003-user-authentication → main...

✅ Pull Request #43 created
   https://github.com/user/myapp/pull/43

Output

──────────────────────────────────
✅ Pull Request Created Successfully

#43: feat(auth): add user authentication
URL: https://github.com/user/myapp/pull/43

Next steps:
- View PR: gh pr view 43 --web
- Request review: gh pr review 43 --request @teammate
──────────────────────────────────

---

Example 2: Bug Fix PR

Scenario

Fixed a critical bug, need to create PR quickly.

Command

/create-pr

Execution

Commits on branch:

3e2f1a9 fix(auth): resolve null pointer in token validation
7a8b3c4 test(auth): add test for null token case

Generated PR:

Title: fix(auth): resolve null pointer in token validation

Body:
## Summary
- Added null safety checks in TokenValidator
- Fixed NPE when token is expired
- Added test coverage for edge case

## Test Plan
- [ ] Verify fix with expired tokens
- [ ] Run unit tests: `npm test auth`
- [ ] Manual testing in staging

Output

✅ PR #44 created
   URL: https://github.com/user/myapp/pull/44
   Labels: bug, auth

---

Example 3: Update Existing PR

Scenario

PR already exists, made additional commits after code review feedback.

Command

/create-pr

Execution

PR Detection:

Found existing PR for this branch:

#43: feat(auth): add user authentication
URL: https://github.com/user/myapp/pull/43
State: OPEN

Options:
1. Update PR (push new commits)
2. View PR in browser
3. Cancel

Choose (1/2/3): 1

Updating:

Pushing latest commits...

New commits:
  8g4b9c0 feat(auth): address PR feedback
  5h6c2d1 refactor(auth): improve error handling

✅ PR #43 updated
   2 new commits pushed
   Review comments preserved

Output

──────────────────────────────────
✅ PR Updated Successfully

#43: feat(auth): add user authentication
New commits: 2
URL: https://github.com/user/myapp/pull/43

Reviewers have been notified of the update.
──────────────────────────────────

---

Example 4: Draft PR (Work in Progress)

Scenario

Feature is not complete, want to show progress with draft PR.

Command

/create-pr --draft

Execution

Content Generation:

Title: feat(dashboard): add real-time analytics (WIP)

Body:
## Summary
- Work in progress on WebSocket connection
- Basic dashboard layout implemented
- TODO: Error handling and reconnection logic

## Test Plan
- [ ] TODO: Add WebSocket tests
- [ ] TODO: Test reconnection logic
- [ ] TODO: Manual testing

Draft Creation:

Creating draft pull request...

✅ Draft PR #45 created
   Status: DRAFT
   CI workflows will not run until marked ready

Output

──────────────────────────────────
✅ Draft Pull Request Created

#45: feat(dashboard): add real-time analytics (WIP)
URL: https://github.com/user/myapp/pull/45
Status: DRAFT

When ready for review:
  gh pr ready 45
──────────────────────────────────

---

Example 5: PR to Non-Default Branch

Scenario

Feature targets develop branch, not main.

Command

/create-pr --base develop

Execution

Branch Status:

Current: feat/005-dashboard
Base: develop (non-default)
Commits ahead: 4

PR Creation:

Creating PR: feat/005-dashboard → develop

✅ PR #46 created
   Base: develop
   Head: feat/005-dashboard

Output

──────────────────────────────────
✅ Pull Request Created

#46: feat(dashboard): add analytics
Base: develop ← feat/005-dashboard
URL: https://github.com/user/myapp/pull/46

Note: This PR will merge into develop, not main
──────────────────────────────────

---

Example 6: Submodule PR

Scenario

Made changes in a submodule, need to create PR for submodule's repository.

Command

cd plugins/arkhe-claude-plugins/
../..//create-pr

Execution

Repository Detection:

Detected: arkhe-claude-plugins (submodule)
Remote: git@github.com:user/arkhe-claude-plugins.git
Branch: feat/add-pr-skill

PR Creation:

Creating PR in submodule repository...

✅ PR #12 created
   Repository: user/arkhe-claude-plugins
   URL: https://github.com/user/arkhe-claude-plugins/pull/12

Output

──────────────────────────────────
✅ Submodule Pull Request Created

#12: feat(git): add PR creation skill
Repository: arkhe-claude-plugins
URL: https://github.com/user/arkhe-claude-plugins/pull/12

Don't forget to update the root repository
after this PR is merged!
──────────────────────────────────

---

Example 7: Combined Options (Draft + Custom Base)

Scenario

Creating WIP PR targeting staging branch.

Command

/create-pr --draft --base staging

Execution

Configuration:

Mode: Draft PR
Base: staging
Current: feat/006-payment-gateway

PR Creation:

✅ Draft PR #47 created
   Base: staging
   Status: DRAFT
   URL: https://github.com/user/myapp/pull/47

---

Example 8: Protected Branch Error

Scenario

Accidentally tried to create PR while on main branch.

Command

git checkout main
/create-pr

Execution

Branch Check:

Current branch: main

❌ Error: Cannot create PR from protected branch 'main'

Pull requests must be created from feature branches.

Suggested workflow:
1. Create feature branch:
   /create-branch <description>

2. Make your changes

3. Commit changes:
   /commit

4. Create PR:
   /create-pr

Result: Script exits, no PR created

---

Example 9: Already Pushed Branch

Scenario

Branch already exists on remote, has new local commits.

Command

/create-pr

Execution

Branch Status:

✅ Branch exists on remote
✅ Local has 2 new commits

Pushing updates...
✅ Remote updated

PR Creation:

✅ PR #48 created
   Includes latest 2 commits

---

Example 10: View Existing PR

Scenario

PR already exists, just want to view it.

Command

/create-pr

Execution

PR Detection:

Found existing PR:

#43: feat(auth): add user authentication
URL: https://github.com/user/myapp/pull/43

Options:
1. Update PR
2. View PR in browser
3. Cancel

Choose: 2

Result:

Opening PR in browser...
https://github.com/user/myapp/pull/43

(Browser opens to PR page)

---

Common Workflows

Daily Feature Development

# 1. Create feature branch
/create-branch add user dashboard

# 2. Make changes
vim src/dashboard.ts

# 3. Commit changes
/commit

# 4. Create PR
/create-pr

Bug Fix Workflow

# 1. Create fix branch
/create-branch fix login validation bug

# 2. Fix the bug
vim src/auth/login.ts

# 3. Commit fix
/commit

# 4. Create PR (automatically labeled as bug fix)
/create-pr

Draft → Ready Workflow

# 1. Create draft PR early
/create-pr --draft

# 2. Continue working, push commits
git push

# 3. When ready, convert to ready
gh pr ready <PR_NUMBER>

Multi-Repository Workflow

# 1. Work in submodule
cd plugins/arkhe-claude-plugins/
# Make changes
/commit
/create-pr

# 2. After submodule PR merges, update root
cd ../..
git submodule update --remote
/commit
/create-pr

---

Tips for Effective PRs

✅ Good Practices

1. Create from feature branches: Never from main/master 2. Write clear commits: PR title derived from commits 3. Keep PRs focused: One feature or fix per PR 4. Use draft PRs: For work in progress 5. Update existing PRs: Instead of creating duplicates 6. Target correct base: Use --base when needed

❌ Avoid

1. PRs from main branch: Will be rejected 2. Large, unfocused PRs: Split into smaller PRs 3. Missing test plans: Always include testing approach 4. Duplicate PRs: Check for existing PRs first 5. Forgotten submodule PRs: Remember to PR submodule changes

---

Summary

The creating-pr skill automates:

• ✅ Repository and branch detection
• ✅ Branch pushing to remote
• ✅ Existing PR detection and updates
• ✅ PR title/body generation from commits
• ✅ Draft and custom base branch support

Result: Professional GitHub PRs with minimal manual effort.

For detailed workflow, see WORKFLOW.md. For troubleshooting, see TROUBLESHOOTING.md.

---

Last Updated: 2025-10-27

GitHub Pull Request Creation: Troubleshooting

This document provides solutions to common issues when using the creating-pr skill.

For quick start instructions, see SKILL.md. For detailed workflow, see WORKFLOW.md. For examples, see EXAMPLES.md.

---

Common Issues

Issue 1: GitHub CLI Not Authenticated

Symptom:

❌ Error: gh: Not authenticated

To authenticate, please run: gh auth login

Cause: GitHub CLI not logged in

Solutions:

Solution A: Authenticate with GitHub

gh auth login

Interactive prompts:

? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations? HTTPS/SSH
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

! First copy your one-time code: XXXX-XXXX
Press Enter to open github.com in your browser...

Verification:

gh auth status

Expected output:

✓ Logged in to github.com as username
✓ Git operations protocol: https/ssh
✓ Token: *******************

---

Issue 2: Branch Not Pushed to Remote

Symptom:

❌ Error: Branch 'feat/003-user-auth' does not exist on remote

The script should have pushed it automatically, but failed.

Cause: Network issue or permission problem prevented push

Solutions:

Solution A: Manual Push

git push -u origin feat/003-user-auth

Solution B: Check Remote Access

# Verify remote URL
git remote -v

# Test connection
git fetch origin

# If permission denied, check SSH keys or HTTPS credentials

Solution C: Check Branch Exists Locally

# List local branches
git branch

# Ensure you're on the correct branch
git checkout feat/003-user-auth

---

Issue 3: PR Already Exists

Symptom:

Found existing PR for this branch:
#42: feat(auth): add user authentication

Cause: PR was already created for this branch

Solutions:

Solution A: Update Existing PR (Recommended)

Choose option 1 when prompted

This will push your latest commits and
update the existing PR automatically.

Solution B: View Existing PR

Choose option 2 to open PR in browser

Solution C: Close Old PR and Create New

# Close existing PR
gh pr close 42

# Create new PR
/create-pr

Note: Updating is usually better than creating a new PR

---

Issue 4: Permission Denied (Fork vs Origin)

Symptom:

❌ Error: Permission denied (publickey)
fatal: Could not read from remote repository

or

❌ Error: You don't have push access to user/repo

Cause: Trying to push to repository you don't have write access to

Solutions:

Solution A: Push to Your Fork (Correct workflow)

# Add your fork as remote if not already added
git remote add fork git@github.com:yourname/repo.git

# Push to your fork
git push -u fork feat/003-user-auth

# Create PR from fork to upstream
gh pr create --repo user/repo --head yourname:feat/003-user-auth

Solution B: Verify Remote Configuration

# Check remotes
git remote -v

# Should show:
origin  git@github.com:user/repo.git (upstream)
fork    git@github.com:yourname/repo.git (your fork)

Solution C: Fix SSH Keys

# Test SSH connection
ssh -T git@github.com

# If fails, add SSH key
ssh-keygen -t ed25519 -C "your_email@example.com"
# Add key to GitHub: Settings → SSH Keys

---

Issue 5: Base Branch Not Found

Symptom:

❌ Error: Base branch 'develop' not found in remote repository

Cause: Specified base branch doesn't exist on remote

Solutions:

Solution A: Check Available Branches

# List remote branches
git branch -r

# Common branch names:
# main, master, develop, staging, production

Solution B: Use Correct Base Branch

# If trying to use 'develop' but it doesn't exist, use 'main'
/create-pr --base main

Solution C: Create Base Branch First (If Needed)

# Checkout main
git checkout main

# Create and push develop branch
git checkout -b develop
git push -u origin develop

# Now create PR to develop
git checkout feat/003-user-auth
/create-pr --base develop

---

Issue 6: Protected Branch Error

Symptom:

❌ Error: Cannot create PR from protected branch 'main'

Pull requests must be created from feature branches.

Cause: Attempting to create PR while on main/master branch

Solutions:

Solution A: Create Feature Branch

# From main, create feature branch
/create-branch add user authentication

# Make changes
vim src/file.ts

# Commit
/commit

# Now create PR
/create-pr

Solution B: Move Changes to Feature Branch

# If you already made changes on main
git checkout -b feat/003-user-auth

# Commit changes
/commit

# Create PR
/create-pr

---

Issue 7: No Commits on Branch

Symptom:

❌ Error: No commits found on branch ahead of base

Cannot create PR without changes.

Cause: Feature branch has no commits that aren't in base branch

Solutions:

Solution A: Ensure Changes Are Committed

# Check for uncommitted changes
git status

# If changes exist, commit them
git add .
/commit

# Then create PR
/create-pr

Solution B: Check Branch Status

# Compare with base
git log main..HEAD

# Should show commits
# If empty, branch has no unique commits

---

Issue 8: gh Command Not Found

Symptom:

bash: gh: command not found

Cause: GitHub CLI not installed

Solutions:

Solution A: Install GitHub CLI (macOS)

brew install gh

Solution B: Install GitHub CLI (Linux)

# Debian/Ubuntu
sudo apt install gh

# Fedora/RHEL
sudo dnf install gh

Solution C: Install GitHub CLI (Windows)

winget install --id GitHub.cli

Verification:

gh --version

---

Issue 9: Script Not Found

Symptom:

bash: /create-pr: No such file or directory

Causes & Solutions:

Solution A: Navigate to Project Root

# Check current directory
pwd

# Navigate to project root
cd /path/to/your/project

# Verify file exists
ls -la /create-pr

Solution B: Reinstall Plugin

/plugin uninstall git@arkhe-claude-plugins
/plugin install git@arkhe-claude-plugins

Solution C: Fix Permissions

chmod +x /create-pr
Skills are loaded automatically - no manual setup needed

---

Issue 10: Network Timeout

Symptom:

❌ Error: Operation timed out
fatal: unable to access 'https://github.com/user/repo.git/'

Cause: Network connection issues

Solutions:

Solution A: Check Network Connection

# Test GitHub connectivity
ping github.com

# Test HTTPS
curl -I https://github.com

Solution B: Use SSH Instead of HTTPS

# Switch remote to SSH
git remote set-url origin git@github.com:user/repo.git

# Retry
/create-pr

Solution C: Increase Timeout

# Increase git timeout
git config --global http.postBuffer 524288000
git config --global http.timeout 300

---

Issue 11: Diverged Branches

Symptom:

❌ Error: Local branch has diverged from remote

Local and remote have different commits.

Cause: Branch history differs between local and remote

Solutions:

Solution A: Pull and Merge

git pull origin feat/003-user-auth
# Resolve any conflicts
git push

# Then create PR
/create-pr

Solution B: Rebase (Cleaner history)

git pull --rebase origin feat/003-user-auth
# Resolve conflicts if any
git push --force-with-lease

# Then create PR
/create-pr

Solution C: Force Push (Use with caution)

# Only if you're sure local is correct
git push --force origin feat/003-user-auth

# Then create PR
/create-pr

---

Issue 12: Rate Limit Exceeded

Symptom:

❌ Error: API rate limit exceeded

GitHub API rate limit: 60 requests per hour (unauthenticated)

Cause: Too many API requests without authentication or with low limit

Solutions:

Solution A: Authenticate with gh

gh auth login

Authenticated users get 5,000 requests/hour instead of 60.

Solution B: Wait for Rate Limit Reset

# Check rate limit status
gh api rate_limit

# Shows when limit resets

Solution C: Use Personal Access Token

# Create token at: github.com/settings/tokens
# Use with gh auth login

---

Quick Reference

Error Messages

Verification Commands

# Check GitHub CLI
gh auth status
gh --version

# Check git status
git status
git log main..HEAD

# Check remotes
git remote -v
git branch -r

# Check existing PRs
gh pr list
gh pr status

# Verify script
ls -la /create-pr

Debugging

Enable Verbose Output:

# Run with debugging
bash -x /create-pr

Check GitHub CLI:

# Test gh commands
gh repo view
gh pr list

---

Prevention Tips

1. Authenticate gh first: Run gh auth login once 2. Work on feature branches: Never on main/master 3. Commit before creating PR: Ensure changes are committed 4. Check for existing PRs: Use gh pr list first 5. Keep branches synced: Pull regularly from base branch 6. Use SSH keys: More reliable than HTTPS for push operations

---

Getting Help

If issues persist:

1. Check Skill Documentation: Review SKILL.md 2. Review Examples: See EXAMPLES.md 3. Verify Installation:

   gh --version
   /plugin list

4. Check GitHub Status: https://www.githubstatus.com/ 5. Reinstall Plugin:

   /plugin uninstall git@arkhe-claude-plugins
   /plugin install git@arkhe-claude-plugins

---

Last Updated: 2025-10-27

GitHub Pull Request Creation: Detailed Workflow

This document provides a detailed step-by-step breakdown of the PR creation process.

For quick start instructions, see SKILL.md.

Overview

The PR creation process follows 6 main steps:

1. Repository Detection - Auto-detect root repository and submodules 2. Branch Status Check - Verify current branch and protection rules 3. Push to Remote - Ensure branch exists on GitHub 4. PR Detection - Check for existing PR on current branch 5. PR Title/Body Generation - Create content from commits 6. PR Creation via gh - Use GitHub CLI to create/update PR

---

Step 1: Repository Detection

Automatically detect the repository structure.

Root Repository Detection

Process: 1. Find root .git directory 2. Identify repository name from git remote 3. Determine if working in root or submodule

Example:

cd /Users/you/projects/myapp/
# Root repository: myapp
# Remote: origin git@github.com:user/myapp.git

Submodule Detection

Process: 1. Check for .gitmodules in root 2. Identify current working directory location 3. Match against submodule paths 4. Determine if in submodule context

Example:

cd /Users/you/projects/myapp/plugins/arkhe-claude-plugins/
# Submodule: arkhe-claude-plugins
# Remote: origin git@github.com:user/arkhe-claude-plugins.git

Scope Handling

Interactive Mode (no arguments):

• Auto-detect from current directory
• Use that repository for PR

Direct Mode (with scope):

/create-pr root
# Force PR for root repository

/create-pr arkhe-claude-plugins
# Force PR for specific submodule

---

Step 2: Branch Status Check

Verify the current branch and protection rules.

Current Branch Detection

git branch --show-current

Example Output: feat/003-user-authentication

Protected Branch Check

Protected branches (prevented from creating PR):

• main
• master
• production
• staging (configurable)

Check Logic:

if [[ "$current_branch" == "main" || "$current_branch" == "master" ]]; then
    echo "❌ Cannot create PR from protected branch"
    echo "Suggestion: Create a feature branch first"
    exit 1
fi

Error Message:

❌ Error: Cannot create PR from main branch

Please create a feature branch:
  /create-branch <description>

Then commit your changes and try again.

Branch Tracking Status

Check if branch has remote tracking:

git rev-parse --abbrev-ref @{upstream} 2>/dev/null

Outcomes:

• Has upstream: Branch already pushed to remote
• No upstream: Branch exists locally only (needs push)

---

Step 3: Push to Remote

Ensure the current branch exists on GitHub.

Local-Only Branch

If branch not pushed:

# Check tracking
git rev-parse @{upstream} 2>/dev/null
# Returns error if no upstream

# Push with upstream tracking
git push -u origin feat/003-user-authentication

Output:

Pushing branch to remote...
✅ Branch pushed: feat/003-user-authentication

Already Pushed Branch

If branch exists on remote:

# Check if local is ahead
git rev-list @{upstream}..HEAD --count

# If ahead, push updates
git push

Output:

Branch already on remote
✅ Checking for updates...
✅ Remote is up to date

Push Conflicts

If remote has changes:

❌ Remote has changes not in local branch

Options:
1. Pull and merge: git pull origin feat/003-user-authentication
2. Rebase: git pull --rebase origin feat/003-user-authentication
3. Force push (dangerous): git push --force

---

Step 4: PR Detection

Check if a PR already exists for the current branch.

GitHub CLI Query

gh pr list --head feat/003-user-authentication --json number,title,url,state

Response (no PR):

[]

→ Proceed to create new PR

Response (PR exists):

[
  {
    "number": 42,
    "title": "feat: add user authentication",
    "url": "https://github.com/user/myapp/pull/42",
    "state": "OPEN"
  }
]

→ Offer to update existing PR

Existing PR Handling

Options Presented:

PR already exists: #42 "feat: add user authentication"
URL: https://github.com/user/myapp/pull/42

Options:
1. Update existing PR (push new commits)
2. View PR in browser
3. Cancel

Choose (1/2/3):

Update PR (Option 1):

• Push latest commits to branch
• GitHub automatically updates PR
• Comments and reviews preserved

View PR (Option 2):

• Open PR URL in browser
• Script exits

Cancel (Option 3):

• Exit without changes

---

Step 5: PR Title/Body Generation

Generate PR content from recent commits.

Title Generation

Process: 1. Get commits since branching from base 2. Analyze commit messages 3. Extract conventional commit type and scope 4. Create concise title

Example:

Commits on branch:

7f3a8b9 feat(auth): add OAuth2 login support
3e2f1a9 feat(auth): add token refresh logic
8g4b9c0 test(auth): add OAuth tests

Generated Title:

feat(auth): add user authentication

Logic:

• Use type from first commit (feat)
• Use scope from first commit (auth)
• Summarize overall changes in description
• Keep under 72 characters

Body Generation

Template:

## Summary
<1-3 bullet points summarizing changes>

## Test Plan
- [ ] TODO: Describe testing approach
- [ ] TODO: Manual testing steps
- [ ] TODO: Automated tests added

Example Body:

## Summary
- Implemented OAuth2 authentication flow
- Added token refresh mechanism
- Added comprehensive auth tests

## Test Plan
- [ ] Test OAuth2 login with Google provider
- [ ] Verify token refresh on expiration
- [ ] Run auth test suite: `npm test auth`
- [ ] Manual testing in staging environment

Interactive Approval

Script Presents:

Generated PR content:
──────────────────────────────────
Title: feat(auth): add user authentication

Body:
## Summary
- Implemented OAuth2 authentication flow
- Added token refresh mechanism
- Added comprehensive auth tests

## Test Plan
- [ ] Test OAuth2 login with Google provider
- [ ] Verify token refresh on expiration
- [ ] Run auth test suite
...
──────────────────────────────────

Proceed with this PR? (y/n/e):

Options:

• y → Create PR with this content
• n → Cancel
• e → Edit in text editor

---

Step 6: PR Creation via gh

Use GitHub CLI to create the pull request.

Basic PR Creation

gh pr create \
  --title "feat(auth): add user authentication" \
  --body "$(cat <<'EOF'
## Summary
...
EOF
)" \
  --base main

Output:

Creating pull request...

https://github.com/user/myapp/pull/43

✅ Pull request created: #43

Draft PR Creation

With `--draft` flag:

gh pr create \
  --title "..." \
  --body "..." \
  --base main \
  --draft

Output:

✅ Draft pull request created: #43
   (Will not trigger CI until marked ready for review)

Custom Base Branch

With `--base` argument:

gh pr create \
  --title "..." \
  --body "..." \
  --base develop

Output:

✅ Pull request created: #43
   Base: develop
   Head: feat/003-user-authentication

PR URL Return

Final Output:

──────────────────────────────────
✅ Pull Request Created

Number: #43
Title: feat(auth): add user authentication
URL: https://github.com/user/myapp/pull/43
Base: main ← feat/003-user-authentication

Next steps:
1. Review PR in browser: gh pr view 43 --web
2. Request reviews: gh pr review 43 --request @teammate
3. Monitor CI: gh pr checks 43
──────────────────────────────────

---

Complete Example Workflows

Example 1: Simple Feature PR

Context: Feature branch with new authentication code

Command:

/create-pr

Workflow:

Step 1: Detection

Repository: myapp (root)
Branch: feat/003-user-authentication

Step 2: Branch Check

✅ Not a protected branch
✅ Safe to create PR

Step 3: Push

Branch not on remote, pushing...
✅ Pushed to origin/feat/003-user-authentication

Step 4: PR Detection

Checking for existing PR...
✅ No existing PR found

Step 5: Content Generation

Title: feat(auth): add user authentication
Body: (generated from 3 commits)

Step 6: Creation

✅ PR created: #43
URL: https://github.com/user/myapp/pull/43

---

Example 2: Update Existing PR

Context: PR exists, made more commits

Command:

/create-pr

Workflow:

Steps 1-3: (same as Example 1)

Step 4: PR Detection

Found existing PR: #43 "feat(auth): add user authentication"

Options:
1. Update PR (push new commits)
2. View PR
3. Cancel

Choose: 1

Updating:

Pushing latest commits...
✅ PR #43 updated with 2 new commits

View updated PR:
https://github.com/user/myapp/pull/43

---

Example 3: Draft PR

Context: Work in progress, not ready for review

Command:

/create-pr --draft

Workflow:

Steps 1-5: (same as Example 1)

Step 6: Creation

✅ Draft PR created: #44
   Status: DRAFT (CI will not run)

Convert to ready for review when done:
  gh pr ready 44

---

Example 4: PR to Non-Default Branch

Context: Feature branch targets develop not main

Command:

/create-pr --base develop

Workflow:

Steps 1-5: (same as Example 1)

Step 6: Creation

✅ PR created: #45
   Base: develop ← feat/003-user-authentication

Note: Merging will update develop branch, not main

---

Example 5: Submodule PR

Context: Working in submodule, want to create PR for submodule repo

Command:

cd plugins/arkhe-claude-plugins/
../..//create-pr

Workflow:

Step 1: Detection

Repository: arkhe-claude-plugins (submodule)
Remote: git@github.com:user/arkhe-claude-plugins.git
Branch: feat/add-pr-skill

Steps 2-6: Same as root PR, but targets submodule's GitHub repo

Result:

✅ PR created in submodule repository
URL: https://github.com/user/arkhe-claude-plugins/pull/12

---

Advanced Features

Conventional Commit Detection

Automatic type/scope extraction:

Commit: feat(auth): add OAuth2
→ Type: feat
→ Scope: auth
→ Title: feat(auth): add user authentication

Supported types:

• feat, fix, docs, refactor, test, chore, perf, ci

Multi-Commit PRs

When branch has multiple commits:

• Title uses first commit's type/scope
• Body summarizes all commits
• Test plan includes all changes

Branch Protection Awareness

Checks before PR creation:

• ✅ Not on main or master
• ✅ Not on production
• ✅ Has commits ahead of base

GitHub CLI Integration

Relies on `gh` for:

• Authentication
• PR creation
• PR updates
• PR detection

Requires: gh auth login run once

---

Configuration

Environment Variables

GH_REPO (optional):

export GH_REPO=user/myapp

Explicitly set repository (useful for forks)

Base Branch Configuration

Default: main

Override:

/create-pr --base develop

Custom PR Template

Edit script to customize body template:

# In pr.sh
BODY_TEMPLATE="## Changes\n...\n\n## Testing\n..."

---

Important: No Claude Code Footer Policy

The pr.sh script generates clean PR content without any attribution.

⚠️ CRITICAL CONSTRAINT: Never add Claude Code footers or attribution to PR titles or descriptions.

Prohibited Content:

• ❌ "🤖 Generated with [Claude Code]" in PR title
• ❌ "🤖 Generated with [Claude Code]" in PR body
• ❌ "Co-Authored-By: Claude <noreply@anthropic.com>"
• ❌ Any Claude Code branding or attribution

Why This Matters:

• PRs should reflect actual contributors
• Professional appearance for code review
• Clean, focused content without marketing material

Runtime Verification: The pr.sh script automatically verifies that no footer was added to PR titles or descriptions. If detected, the script will fail with an error message.

Example of Correct PR:

Title: feat(auth): add OAuth2 login support

Body:
## Issue
- resolves: #123

## Why is this change needed?
This PR includes the following changes:
- feat(auth): implement OAuth2 flow
- feat(auth): add token refresh

## Testing
- [x] Tests added/updated
- [x] Manual testing completed

Example of Incorrect PR (will be rejected):

Title: feat(auth): add OAuth2 login support

Body:
## Issue
- resolves: #123

## Why is this change needed?
...

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---

Best Practices

1. Create feature branches: Never PR from main 2. Write clear commits: PR title derived from commits 3. Keep PRs focused: One feature per PR 4. Use draft PRs: For work-in-progress 5. Update existing PRs: Push new commits rather than creating duplicates 6. Target correct base: Use --base for non-main branches

---

Summary

The PR creation workflow automates: 1. ✅ Repository and branch detection 2. ✅ Branch pushing to remote 3. ✅ Existing PR detection 4. ✅ PR title/body generation from commits 5. ✅ GitHub CLI integration 6. ✅ Draft and custom base branch support

Result: Professional PRs with minimal manual effort.

For examples, see EXAMPLES.md. For troubleshooting, see TROUBLESHOOTING.md.

---

Last Updated: 2025-10-27