/finishing-a-development-branch

name: finishing-a-development-branch
description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup

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

The Process

Step 1: Verify Tests

**Before presenting options, verify tests pass:**

# Run project's test suite
npm test / cargo test / pytest / go test ./...

**If tests fail:**

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

[Show failures]

Cannot proceed with merge/PR until tests pass.

Stop. Don't proceed to Step 2.

**If tests pass:** Run pre-merge checklist:

# Check for duplicate beads (clean up before merge)
bd find-duplicates

If `bd find-duplicates` reports issues, fix them before proceeding. Then continue to Step 2.

A green suite is necessary but not sufficient: do not merge if a requirement was dropped or a security regression remains (Production-Grade Doctrine).

Step 2: Detect Environment

Run the following to determine the git context:

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)
IS_WORKTREE=$( [ "$GIT_DIR" != "$GIT_COMMON" ] && echo "yes" || echo "no" )
IS_DETACHED=$( git symbolic-ref HEAD >/dev/null 2>&1 && echo "no" || echo "yes" )
# Capture now, while still inside the workspace — Step 5 changes directory
# before Step 6 needs this value
WORKTREE_PATH=$(git rev-parse --show-toplevel)

| Context | Detection | Menu | |---------|-----------|------| | Normal repo | `IS_WORKTREE=no`, `IS_DETACHED=no` | Full 3 options | | Named-branch worktree | `IS_WORKTREE=yes`, `IS_DETACHED=no` | Full 3 options | | Detached HEAD | `IS_DETACHED=yes` | Reduced 2 options (no "Merge locally") |

Step 3: Determine Base Branch

# Try common base branches
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null

Or ask: "This branch split from main - is that correct?"

Step 3.5: Docs-Audit Gate

document-release must have run on this branch — evidence: a `docs:` commit in `git log <base>..HEAD` not followed by later code commits, or a clean-audit statement from this session. Missing or in doubt → invoke `beads-superpowers:document-release` now (its empty-check exits cheaply when the diff is doc-irrelevant; when in doubt, run the audit). If the audit cannot complete, neither silently pass nor block: prepend "⚠️ docs audit could not complete: <reason>" to the Step 4 options question — the user decides.

Step 4: Present Options

**Use your structured question tool** to present options. Do NOT present choices as plain prose when your harness has a question tool; without one, numbered list + STOP. A skipped, dismissed, or auto-resolved answer is not consent — stop and ask in plain text.

**For normal repo or named-branch worktree** (`IS_DETACHED=no`), present all 3 options:

{
  "questions": [{
    "question": "Implementation complete. How would you like to finish this branch?",
    "header": "Branch",
    "options": [
      {
        "label": "Merge locally",
        "description": "Merge back to <base-branch>, run tests on result, delete feature branch"
      },
      {
        "label": "Create Pull Request",
        "description": "Push branch to origin and open a PR via your forge's CLI or the URL it prints on push"
      },
      {
        "label": "Keep as-is",
        "description": "Leave the branch and worktree intact — handle it later"
      }
    ],
    "multiSelect": false
  }]
}

**For detached HEAD** (`IS_DETACHED=yes`), present 2 options (omit "Merge locally"):

{
  "questions": [{
    "question": "Implementation complete. How would you like to finish this work?",
    "header": "Branch",
    "options": [
      {
        "label": "Create Pull Request",
        "description": "Push branch to origin and open a PR via your forge's CLI or the URL it prints on push"
      },
      {
        "label": "Keep as-is",
        "description": "Leave the worktree intact — handle it later"
      }
    ],
    "multiSelect": false
  }]
}

Note: Merge is unavailable because HEAD is detached — there is no branch to merge.

**Don't add explanation** — the tool options are self-describing. Map the user's selection to the corresponding option in Step 5.

Step 5: Execute Choice

Option 1: Merge Locally

# Leave the worktree first — checkout, merge, and worktree removal all have to
# run from the main repo root, and Step 6 needs the path captured in Step 2
MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

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

# Verify tests on merged result
<test command>

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) **first** — git refuses to delete a branch that is still checked out in a live worktree — then delete the branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

# Push branch — IS_DETACHED was captured in Step 2
if [ "$IS_DETACHED" = "yes" ]; then
  # No branch to name from a detached HEAD — push an explicit refspec:
  git push origin HEAD:refs/heads/<new-branch>
else
  git push -u origin <feature-branch>
fi

# Create PR/MR via the forge's CLI (detected from the origin remote)
REMOTE_URL=$(git remote get-url origin)
case "$REMOTE_URL" in
  *github.com*)
    gh pr create