# Create Pull Request

> Creates a Pull Request using GitHub CLI with a PR summary file. Generates PR-summary.md in the feature-specs folder to avoid terminal pasting issues.

- Skill: `tomevault-io/create-pull-request-4` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/create-pull-request-4`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/create-pull-request-4/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/create-pull-request-4

---


# Create Pull Request Skill

## Purpose

This skill creates a GitHub Pull Request using the `gh` CLI tool. To avoid issues with pasting large text into the terminal, it first creates a `PR-summary.md` file in `/docs/feature-specs/${featureName}/`, then **must commit and push that summary file**, and only then runs `gh pr create` with that file as the PR body.

## Prerequisites

- GitHub CLI (`gh`) must be installed and authenticated
- Current branch must be pushed to the remote
- There must be commits to create a PR from
- The executing agent must have terminal execution tools (see [Terminal Handoff](#terminal-handoff) if you don't)

### Terminal Handoff

If you don't have terminal execution tools, hand off to the **Coder** agent with the following scope constraint:

> **Scope constraint:** Execute ONLY the git and gh CLI commands provided below. Do NOT edit code, fix warnings, refactor, or take any action beyond running these commands and reporting their output. If a command fails, report the error — do not attempt autonomous fixes.

Include in your handoff:

1. The exact commands to run (from Steps 2, 6, and 7)
2. The PR title (from Step 4)
3. The path to the PR summary file (from Step 5)
4. This scope constraint verbatim

## Workflow

### Step 1: Determine Feature Name and Base Branch

Extract the feature name from the current branch name:

- `feature/my-feature` → `my-feature`
- `bugfix/fix-description` → `fix-description`

Determine the base branch by checking which remote branches exist:

- Default to `main` if it exists
- Fall back to `develop` or `master` if `main` doesn't exist

### Step 2: Analyze Changes

Gather all context automatically:

```bash
# Get the merge base
BASE_BRANCH="main"  # or detected base branch
MERGE_BASE=$(git merge-base HEAD origin/${BASE_BRANCH})

# List all commits
git log --oneline ${MERGE_BASE}..HEAD

# Get detailed commit messages for context
git log --pretty=format:"%s%n%n%b" ${MERGE_BASE}..HEAD

# Review changed files with stats
git diff --stat ${MERGE_BASE}

# Get list of changed files by type
git diff --name-only ${MERGE_BASE}
```

### Step 3: Check Existing Documentation

Look for existing feature documentation:

1. `/docs/feature-specs/${featureName}/implementation-plan.md` - for planned changes
2. `/docs/feature-specs/${featureName}/implementation-progress.md` - for completed work
3. `/docs/feature-specs/${featureName}/low-level-design-*.md` - for design context
4. `/docs/feature-specs/${featureName}/user-stories.md` - for requirements

### Step 4: Generate PR Title

Auto-generate the PR title based on:

1. If single commit: Use the commit message subject
2. If multiple commits: Summarize the overall change based on:
   - The feature name from the branch
   - The types of files changed (e.g., "Add meter component" if UI components added)
   - Commit message patterns (e.g., "fix:", "feat:", "refactor:")

Examples:

- Branch `feature/meter-improvements` with perf commits → "Improve meter performance and accuracy"
- Branch `bugfix/slider-crash` → "Fix slider crash on invalid input"
- Branch `cs-1234-add-reverb` → "CS-1234: Add reverb effect"

### Step 5: Create PR Summary File

**⚠️ Use the `edit` tool to create this file - DO NOT use terminal commands like `echo`.**

Create the file at `/docs/feature-specs/${featureName}/PR-summary.md` using the template from [assets/PR-summary-template.md](assets/PR-summary-template.md).

**Tool usage:**

- Use the `edit` tool or equivalent file creation capability
- Never use `echo`, `cat`, or other terminal commands for file creation
- The file editor ensures proper formatting and allows immediate editing if needed

Fill in the auto-generated content for each section:

- **Summary**: Based on commit messages and changed files
- **Changes**: Grouped by area (Engine/DSP, UI, Build/Config, Documentation)
- **Commits**: List from `git log --oneline`
- **Related Documentation**: Auto-link existing feature-spec files
- **Testing**: Based on types of changes made
- **Checklist**: Standard quality checks

### Step 6: Commit and Push PR Summary (Mandatory)

**This step is required.** Always stage and commit `docs/feature-specs/${featureName}/PR-summary.md` before creating the PR to avoid leaving an unstaged summary file behind.

Run the following commands:

```bash
# Stage only the PR summary file
git add docs/feature-specs/${featureName}/PR-summary.md

# Commit only this file; safe no-op if there is nothing new to commit
git diff --cached --quiet || git commit -m "docs: add PR summary for ${featureName}"

# Push branch updates (including PR-summary commit)
git push -u origin HEAD
```

### Step 7: Create the Pull Request

Run this only after Step 6 succeeds.

Run the following commands:

```bash
# Create PR using the summary file (use relative path from repo root)
gh pr create \
  --title "${PR_TITLE}" \
  --body-file "docs/feature-specs/${featureName}/PR-summary.md" \
  --base "${BASE_BRANCH}"
```

### Step 8: Confirm Success

After successful PR creation:

1. Display the PR URL to the user
2. Optionally open the PR in the browser with `gh pr view --web`

## Error Handling

- If `gh` is not installed: Instruct user to install with `brew install gh`
- If not authenticated: Run `gh auth login`
- If branch not pushed: Push with `git push -u origin HEAD`
- If PR already exists: Inform user and provide link to existing PR

## Example Usage

**User says:** "Create a PR for my changes"

**Agent workflow:**

1. Determine feature name from branch: `feature/meter-improvements` → `meter-improvements`
2. Analyze commits: 3 commits about performance improvements
3. Check changed files: `ui/src/components/Meter.tsx`, `ui/src/lib/audio-math.ts`
4. Auto-generate title: "Improve meter performance and accuracy"
5. Create `docs/feature-specs/meter-improvements/PR-summary.md` with auto-generated content
6. Run: `git add docs/feature-specs/meter-improvements/PR-summary.md`, then `git diff --cached --quiet || git commit -m "docs: add PR summary for meter-improvements"`, then `git push -u origin HEAD`
7. Run: `gh pr create --title "Improve meter performance and accuracy" --body-file "docs/feature-specs/meter-improvements/PR-summary.md" --base main`
8. Return: "✅ PR created: https://github.com/owner/repo/pull/123"

## Notes

- Committing and pushing `docs/feature-specs/${featureName}/PR-summary.md` before `gh pr create` is mandatory
- If the feature-specs folder doesn't exist for this feature, create it
- Always use relative paths from the repository root in the `--body-file` argument
- All PR details (title, description) are auto-generated from branch changes - no user input required

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/ronhouben) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->