Finishing A Development Branch

---
name: finishing-a-development-branch
description: >
  MUST USE when implementation is verified and you need to choose the
  branch outcome: merge, PR, keep, or discard. Triggers on: "merge this",
  "create a PR", "squash and merge", "we're done with this branch",
  "clean up the branch", "push this", "get it merged", after
  verification-before-completion passes. Routed by using-superpowers
  or executing-plans at completion.
---

# Finishing a Development Branch

Close development work with explicit integration choice.

## Step 1: Verify

Run full project verification before offering options.

If verification fails, stop and return to implementation.

## Step 2: Identify Base Branch

Detect merge base (`main`/`master` or repo default) and confirm if unclear.

## Step 3: Offer Exactly Four Options

1. Merge back to `<base-branch>` locally
2. Push branch and open PR
3. Keep branch/worktree as-is
4. Discard branch/worktree

## Step 4: Execute Safely

### Option 1
- Checkout base
- Pull latest
- Merge feature branch
- Re-run verification
- Remove worktree (follow "Removing a worktree" below)
- Delete merged branch

### Option 2
- Push feature branch
- Create PR with a description that includes:
  - **What changed** — one-paragraph summary of the change set
  - **Why** — the motivation or problem this solves (link to plan doc if one exists)
  - **How to verify** — exact commands or steps a reviewer can run to confirm the change works
  - **Notable decisions** — any trade-offs made, alternatives rejected, or non-obvious choices.
    If `session-log.md` has `[saved]` entries written during this branch's lifetime, extract the Decisions and Rejected bullets from the most recent entry and include them here. This ensures PR reviewers see the "why" without needing to read the log.
- Keep worktree by default (remove only if user asks; then follow "Removing a worktree" below)

### Option 3
- Keep branch and worktree
- Report exact path and branch name

### Option 4
- Show destructive impact summary. The summary names every spec and plan that only this branch holds: the paths that `git diff --name-only --diff-filter=A <base-branch>...<feature-branch> -- ":(top)docs/superpowers-orchestrator/"` prints.
- Require exact confirmation: `discard`
- Remove worktree (follow "Removing a worktree" below), then delete branch

### Removing a worktree

Options 1, 2 and 4 remove a worktree (a second working folder of the same
repository) only with this procedure.

`git worktree remove` refuses when the worktree holds a modified file. It
refuses for an untracked file only while the git setting
`status.showUntrackedFiles` is not `no`. It does not refuse for a
file that git ignores: it deletes that file with no message. Git ignores
the workspace files of this plugin (`session-log.md`, `state.md`,
`known-issues.md`, `project-map.md`), because the hooks of the plugin hide
them from git.

First take the path of the main checkout: the first line of
`git worktree list`. The session can run inside the worktree, and a git
command fails in a folder that no longer exists. So run the removal, and
every later git command, with `git -C "<main-checkout-path>"`.

Then run this check. Give the path of the worktree: without
`-C "<worktree-path>"` the command reports on the folder it runs in.

```bash
git -C "<worktree-path>" status --porcelain --ignored --untracked-files=normal
```

- The check fails (an error text, or an exit status that is not 0): do not
  remove the worktree. Show the error to the user.
- No output: run
  `git -C "<main-checkout-path>" worktree remove "<worktree-path>"`.
- Any output: do not remove the worktree yet. Each line names a file or a
  folder that the removal deletes; `!!` marks one that git ignores. Show
  the lines to the user. Say which lines are workspace files of the plugin:
  `session-log.md`, `state.md` and `known-issues.md` hold content that
  exists nowhere else. Ask the user which files to move to the main
  checkout and which files to delete.
- A file to move: move it to the same relative path in the main checkout.
  Never overwrite a file there: when the destination already exists, leave
  both files in place and ask the user what to do with them.
- After the user has answered for every line: run the removal command of
  the list item "No output". If git refuses because of a modified or an
  untracked file, the answer of the user to delete that file allows
  `--force`.
- Never pass `--force` to the removal command before the user has
  answered.

## Hard Rules

- Never merge with failing tests.
- Never delete work without explicit confirmation.
- Never force-push unless explicitly requested.

## Final Report

Include:
- Selected option
- Commands executed
- Final branch/worktree status
- PR link (if created)