pm-branches

What this skill does

# 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

```bash
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

```markdown
## 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:
   ```bash
   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.