---
name: finishing-development-branches
description: Use after implementation is complete and before merging, pushing, opening a Gitea pull request, or cleaning up a feature branch or worktree.
license: MIT
source: https://github.com/obra/superpowers/blob/main/skills/finishing-a-development-branch/SKILL.md
---

# Finishing Development Branches

Completion and integration are different decisions. A green feature branch
does not authorise merging, pushing, deleting branches, or removing worktrees.
Verify the exact tree, identify its provenance, then let the user choose the
integration action.

## 1. Establish the state

From the feature workspace, record:

```bash
git status --short
git branch --show-current
git rev-parse HEAD
git rev-parse --show-toplevel
git rev-parse --git-dir
git rev-parse --git-common-dir
git remote -v
```

Determine the intended base branch from the brief, branch upstream, merge
base, or conversation. If it is not confirmed, ask. Do not assume `main`.

Stop if the tree contains unexplained changes. They may belong to the user or
another delegate; do not stage, discard, or fold them into the integration.

## 2. Verify the branch tip

Run the project’s required targeted and full regression checks on the current
`HEAD`. Read their actual output. For higher-risk changes, run the relevant
end-to-end path as required by `verification-before-completion`.

Also inspect what will integrate:

```bash
git log --oneline <base>..HEAD
git diff --check <base>...HEAD
git diff --stat <base>...HEAD
```

If a check fails, report the failure and stop. Do not offer integration of a
known-red branch.

## 3. Present the integration choices

Report the confirmed base, branch/commit, test evidence, and whether this is a
linked worktree. Then offer only applicable choices:

1. Merge locally into the confirmed base.
2. Push the feature branch and open a Gitea pull request.
3. Keep the branch and workspace unchanged for later review.

Wait for the user’s choice. Do not infer permission to push or merge from a
request to implement or commit. Never offer deletion as routine cleanup.

## 4. Execute only the chosen action

### Merge locally

Before pulling or contacting a remote, confirm that updating the base from the
remote is wanted. From the primary checkout:

```bash
git switch <base>
git merge <feature-branch>
```

Do not use a strategy flag merely to avoid conflicts. If conflicts occur,
follow `resolving-merge-conflicts`; never abort the merge/rebase. Re-run the
full verification suite on the merged tree because the result is a different
tree from the tested feature tip.

### Push and create a Gitea pull request

Confirm the remote and branch names before pushing. Never force-push to solve
a rejection; inspect the remote divergence and ask if rewriting remote history
would be required. Follow repository/Gitea templates and report the pull
request URL. Keep the feature workspace for review fixes.

### Keep as-is

Report the branch name, commit, and full workspace path. Make no cleanup
changes.

## 5. Cleanup is separately authorised

Remove a linked worktree or delete a branch only after its work is safely
integrated, or after the user explicitly asks to discard it. Before a discard,
show the exact branch, worktree path, and commits that would become
unreferenced; require an explicit confirmation naming those targets.

Never clean unrelated or merely “stale-looking” worktrees. Never use
force-deletion for normal cleanup. After any authorised cleanup, verify with
`git worktree list` and `git branch --list` and report what was removed.

## Stop conditions

Stop and preserve all state when:

- tests or merged-result verification fail;
- the base branch is uncertain;
- the remote has diverged;
- conflicts are unresolved;
- the tree contains unexplained changes;
- the requested action would delete or rewrite work without explicit consent.