finishing-a-development-branch

Files (1)

• SKILL.md

SKILL.md (first lines)

# Finishing a Development Branch

## Overview

**Core principle:** Verify tests → Detect environment → Follow requested outcome → Clean up safely.

**Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work."

## Step 1: Verify Tests

Run the project's full test suite (`npm test` / `cargo test` / `pytest` / `go test ./...`).

**If tests fail**, report the failures and stop — the menu comes after a green suite:

```
Tests failing (<N> failures). Must fix before completing:

[Show failures]
```

**If tests pass:** continue to Step 2.

## Step 2: Detect Environment

```bash
GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
# Capture now, while still inside the workspace — Step 5 changes directory
# before cleanup (Step 6) needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)
```

**Detached HEAD** (`git branch --show-current` prints nothing, common in
harness-managed worktrees): create a branch now with
`git switch -c <descriptive-branch>`. Commits left on a detached HEAD are
lost when the host deletes its worktree. If branch creation is blocked (e.g.
by a sandbox), report the detached state and the head SHA, and stop.

This determines how cleanup works:

| State | Cleanup |
|-------|---------|
| `GIT_DIR == GIT_COMMON` (normal repo) | No worktree to clean up |
| `GIT_DIR != GIT_COMMON` | Provenance-based (see Step 6) |

## Step 3: Determine Base Branch

The base branch is whatever this work forked from — usually named in the
plan, the conversation, or the branch's upstream. If it is not already
known, derive it from merge-base, upstream tracking, and repository defaults.
If those disagree, stop before merging or opening a PR and report the
ambiguity: integrating into the wrong base is expensive to undo.

## Step 4: Select Requested Integration

Follow the requested outcome already present in the task or repository
instructions:

- If the request includes opening a PR, push and create the PR.
- If the request includes local integration, merge locally.
- If no integration side effect was requested, keep the branch and worktree,
  report their state, and stop. Do not turn completion into a permission menu.

Publishing, merging, or deleting work without that outcome being requested
requires new authority. Preserve the branch instead of asking a routine
completion question.

## Step 5: Execute Choice

### Option 1: Merge Locally

```bash
# Get main repo root for CWD safety
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

# Worked in a linked worktree? The main checkout belongs to your human
# partner: merge there only if it is clean and already on the base branch.
git status --porcelain            # must print nothing
git branch --show-current         # must print <base-branch>
# Worked in the main checkout itself? Switch it: git checkout <base-branch>

# Merge first — verify success before removing anything
git pull
git merge <feature-branch>

# Verify tests on merged result
<test command>
```

If you worked in a linked worktree and the main checkout has uncommitted
changes or is on another branch, do not switch or stash it: report and stop.

If tests fail on the merged result: stop, leave the worktree and branch in
place, and investigate — nothing has been pushed, so the merge is local
and recoverable.

Once the merged result is green: clean up the worktree (Step 6), then
delete the branch:

```bash
git branch -d <feature-branch>
```

### Option 2: Push and Create PR

```bash
git push -u origin <feature-branch>
```

Then create the pull/merge request against <base-branch> with the forge's
tooling — its CLI if one is available, or the creation URL most forges
print when you push — following the repo's PR template and conventions if
present, and report the URL to your human partner.

Keep the worktree — your human partner iterates on PR feedback there.

### Option 3: Keep As-Is

From basnijholt/baspowers, MIT.

More from basnijholt/baspowers