pm-branches

name	pm-branches
description	Use this skill when creating a git branch for a Linear or GitHub issue, writing a PR description, opening a pull request, or linking a PR to its tracked issue. Trigger phrases "create a branch", "new branch for this issue", "branch for
version	0.44.4

PM Branches & PR Linking

Enforce consistent branch naming and PR descriptions that trigger Linear's auto-close via PR link.

Usage

/pm-branches [<issue-id>] [<type>] [<short-description>]

Workflow-driven (no flags) — inputs are gathered from the branch/context:

• <issue-id> (Linear ID e.g. ENG-42 or GitHub #42, required) — the tracked issue to branch for and Closes in the PR. If untracked, file it first via pm-issues.
• <type> (one of feat fix chore refactor docs test, optional) — branch-name prefix; defaults from the nature of the change.
• <short-description> (2-4 words, lowercase, hyphenated, optional) — the branch-name suffix.
• PR title/body (derived) — title is <issue-id>: <concise title>; body uses the PR description template and ends with Closes <issue-id>.
• Runs git checkout -b, git push -u origin <branch>, and gh pr create.

Core Rule: 1 PR = 1 Issue

One PR closes one Linear issue. If extra work surfaces mid-PR:

• Bug found → new issue, fix in separate PR first, rebase your feature branch
• Scope creep → use pm-pivot
• Tiny cleanup (<10 lines, directly related) → include it; if you have to explain why it's in this PR, it belongs in its own issue

For larger features, use Linear's parent/sub-issue hierarchy. Parent issue needs no PR — it closes when all sub-issues close. Each sub-issue gets its own branch (feat/NTH-44-auth-middleware) and PR with Closes <SUB-ID>.

PR Scope

Target: ~200-400 lines changed. Under 200 is ideal. Over 500 warrants a check-in.

Before opening a PR, verify every changed file relates to the issue's acceptance criteria, there are no unrelated changes, and test changes match code changes.

Check in with the user after completing the core change, when the diff crosses ~300 lines, or when unexpected complexity appears. If the diff exceeds ~500 lines, suggest splitting into a shippable subset + follow-up issue.

---

Branch Naming Convention

Format: <type>/<LINEAR-ID>-<short-description>

• type = feat, fix, chore, refactor, docs, test
• LINEAR-ID = the Linear issue identifier (e.g., ENG-42)
• short-description = 2-4 words, lowercase, hyphenated

Examples:

feat/ENG-42-auth-middleware-refactor
fix/ENG-45-pagination-off-by-one
chore/ENG-51-update-dependencies

Creating a Branch

git checkout -b feat/ENG-42-auth-middleware-refactor

Always confirm the Linear issue ID before creating the branch. If the work isn't tracked yet, use the pm-issues skill to create the issue first.

---

PR Description Template

## Summary
[1-3 bullet points describing what changed and why]

## Changes
- [Specific change 1]
- [Specific change 2]

## Testing
- [ ] [How to verify this works]
- [ ] [Edge cases tested]

Closes ENG-42

Critical: The Closes <ID> line at the end of the PR description is what triggers Linear to auto-close the issue when the PR merges. Always include it. One PR, one Closes line.

---

Opening a PR

When the user says "open a PR" or "push this up":

1. Confirm the Linear issue ID from the current branch name or context
2. Check the current branch has been pushed: git push -u origin <branch>
3. Draft the PR description using the template above
4. Show the user the description for review
5. Create the PR:

   gh pr create \
     --title "<LINEAR-ID>: <concise title>" \
     --body "<description with Closes ENG-XX>"
   

PR Title Format

ENG-42: Refactor auth middleware to support OAuth

The Linear ID at the front of the title makes it easy to scan in GitHub's PR list.

---

Verifying the Link

After creating the PR, confirm the Linear issue shows the PR as attached:

get_issue { id: "<issue_id>" } → check attachments or relations

If Linear doesn't pick it up automatically within a few minutes, the Closes keyword in the PR body is what matters — Linear scans it on merge.