branch-pr

name	branch-pr
description	Create pull requests with Conventional Commits and issue-first checks. Trigger: creating branches, opening PRs, or preparing changes for review.
license	Apache-2.0
metadata	{"author":"gentleman-programming","version":"1.0"}

When to Use

Load this skill when:

• Creating a branch for a new fix or feature
• Opening a pull request
• Preparing changes for review

Hard Rules

1. Branch from main — always pull latest before branching.
2. Conventional Commits — all commit messages must follow the format below.
3. 400-line review budget — keep PRs within 400 changed lines (additions + deletions) or split using chained-pr.
4. Link the issue — include Closes/Fixes/Resolves #<N> in the PR body when an issue exists.
5. No force-push to main/master — protected branch.

Branch Naming

<type>/<short-description>

Type	Example
feat/	feat/voice-recording
fix/	fix/duplicate-insert
docs/	docs/api-reference
refactor/	refactor/extract-query
chore/	chore/bump-deps

Rules: all lowercase, hyphens as separators, no spaces or uppercase.

Conventional Commits Format

<type>(<optional-scope>): <description>

Type	Purpose
feat	New feature
fix	Bug fix
docs	Documentation only
refactor	Code change, no behavior change
chore	Maintenance, deps, tooling
test	Adding or updating tests
ci	CI configuration

Breaking change: add ! after type — feat(cli)!: rename flag.

PR Body Template

## Summary

<!-- What this PR does and why. -->

## Changes

| File / Area | What Changed |
|-------------|-------------|
| `path/to/file` | Brief description |

## Test Plan

- [ ] Tests pass locally
- [ ] Manually tested

## Linked Issue

Closes #<N>

Decision Gates

Change type	Commit type	Branch prefix
New feature or capability	feat	feat/
Bug fix	fix	fix/
Breaking API change	feat! or fix!	same prefix
Documentation only	docs	docs/
Code cleanup, no behavior change	refactor	refactor/
Dependencies, tooling	chore	chore/
Tests only	test	test/
PR exceeds 400 lines	split using chained-pr skill	—

Output Contract

Return:

1. Branch name — <type>/<short-description> (lowercase, hyphens)
2. Commit message(s) — <type>(<scope>): <description> per Conventional Commits
3. PR body — filled from the template with Summary, Changes table, Test Plan, and Closes #N

Gotchas

• Using feat for a bug fix inflates the changelog — use fix even if the fix adds new validation logic
• Writing the PR body before checking line count — always run gh pr view --json additions,deletions first
• Omitting Closes #N when an issue exists — the issue never auto-closes and stays open in the backlog
• Branch name with uppercase or spaces breaks some CI systems — always lowercase with hyphens

Commands

# Branch from main
git checkout main && git pull
git checkout -b feat/<description>

# Check lines before PR
gh pr view <PR_NUMBER> --json additions,deletions

# Open PR
gh pr create --title "feat(scope): description" --body "$(cat pr-body.md)"