finishing-a-development-branch

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 --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)" ;;
  *gitlab*)
    glab mr create --title "<title>" --description "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)" ;;
  *)
    echo "Branch pushed to origin. Open a PR/MR via your forge's web UI or CLI." ;;
esac

Keep the worktree — PR feedback gets fixed there, so it stays until the work lands.

Option 3: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

Don't cleanup worktree.

If your human partner asks to discard the work

This path exists only as a response to an explicit request to throw the work away. It is never offered in the menu.

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation.

If confirmed:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git checkout <base-branch>

Then clean up the worktree (Step 6) — git refuses to delete a branch still checked out in a live worktree — and force-delete the branch:

git branch -D <feature-branch>

Step 6: Cleanup Worktree

Runs for Option 1 and confirmed discards. Options 2 and 3 always keep the worktree — PR feedback gets fixed in it, and it stays until the work lands.

GIT_DIR == GIT_COMMON means a normal repo with no worktree to clean up — done. Otherwise check provenance before removing, using the WORKTREE_PATH captured in Step 2, from before Step 5 changed directory:

# Only remove worktrees inside .worktrees/ (created by our tooling)
case "$WORKTREE_PATH" in
  */.worktrees/*) bd worktree remove "$WORKTREE_PATH" ;;
  *) echo "WARNING: This worktree is not inside .worktrees/ — it may have been created externally. Skipping automatic removal." ;;
esac

bd worktree remove refuses while the branch has unpushed commits. Verify the work is safe first — git merge-base --is-ancestor <branch-tip> <base> — and only then re-run with --force.

Capture what you learned. At close, record durable, evidence-backed insight