finishing-a-development-branch

Files (1)

• SKILL.md

SKILL.md (first lines)

# Finishing a Development Branch

## Overview

**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.

**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)
```

This determines which menu to show and how cleanup works:

| State | Menu | Cleanup |
|-------|------|---------|
| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no local merge) | Externally managed — leave in place |

## Step 3: Determine Base Branch

`<BASE_BRANCH>` comes from the repository's `Herdrpowers Configuration` section.
When it is declared, merge and PR targets are that branch — do not silently
retarget `main` because it exists. Without a declared value, 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, ask: "This branch split from
`<your best guess>` - is that correct?" Confirm before merging: merging into the
wrong base is expensive to undo.

## Step 4: Present Options

**Normal repo and named-branch worktree — present exactly these 4 options:**

```
Implementation complete. What would you like to do?

1. Merge back to <base-branch> locally
2. Push to origin and create a Pull Request
3. Push to origin only (no PR)
4. Keep the branch as-is (I'll handle it later)

Which option?
```

**Detached HEAD — present exactly these 3 options:**

```
Implementation complete. You're on a detached HEAD (externally managed workspace).

1. Push as a new branch and create a Pull Request
2. Push as a new branch only (no PR)
3. Keep as-is (I'll handle it later)

Which option?
```

Present the menu exactly as written — concise, with every option coming
from the list above. Discarding the work happens only in response to the
user explicitly asking for it (see "If the user asks to discard the work"
below).

**Present, don't presume.** Merging is one candidate among several, not the
default ending. Never merge, push, or delete anything before the user names the
option — and when they do, execute that option only.

## 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"

# Scope check — this tree should be clean; anything here was written by mistake
git status --short

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

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

**Every unexpected modification in that `git status --short` is a scope
violation, not noise.** A delegated pane whose task named a dedicated worktree
has edited the main checkout instead, and it surfaced only because `git merge`
refused with "Please commit your changes or stash them" — by which point the
stray edit was one `git stash` away from riding into the merge commit
unreviewed. Do not commit it, do not discard it: save it
(`git diff > <REPORT_DIRECTORY>/stray-<task>.patch`), restore the file, finish
the merge, and surface the patch to the user as its own decision.

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.

From transparent-pegasus/herdrpowers, MIT.

More from transparent-pegasus/herdrpowers