finishing-a-development-branch

Finishing a Development Branch

Overview

Guide completion of development work by verifying readiness, marking draft PRs ready, or presenting clear integration options.

Core principle: Run the local quality gate → If draft PR exists, mark ready → Otherwise 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: Check for Existing PR

First check whether the current branch already has a PR:

gh pr view --json url,isDraft,state,statusCheckRollup 2>/dev/null

If a draft PR exists: skip the option menu and go to Step 2 local quality gate.

If a non-draft PR exists: run Step 2 local quality gate and report the PR is already ready if all checks pass.

If no PR exists: continue through the standard branch finishing menu after verifying tests.

PR result reporting: In final result summaries, created, existing, or ready PRs must be reported with the full GitHub PR URL (https://github.com/<owner>/<repo>/pull/<number>). A short #123 reference is fine for intermediate progress, but not for the final PR result.

Step 2: Local Quality Gate

Use this local quality gate before marking a draft PR ready or before offering merge/PR completion options:

• No uncommitted changes (git status --short is empty)
• Cheap local smoke checks still pass
• Required project tests pass, or the user explicitly accepted relying on CI for tests that cannot be run locally
• No known local blockers remain, including failed local checks or unresolved local reviewer findings from the current workflow
• PR body links the issue/SPEC or otherwise explains the requirement source

Remote CI and GitHub checks are not part of this local quality gate. Do not wait for remote CI before marking the PR ready; CI can continue running on a ready PR.

If any local quality gate item fails, stop and report the exact blocker. Do not mark PR ready.

If a draft PR passes the local quality gate: mark it ready:

gh pr ready

Then report the full GitHub PR URL and stop. Do not present the standard option menu.

Step 3: 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 4.

If tests pass: Continue to Step 4.

Step 4: Detect Environment

Determine workspace state before presenting options:

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)

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 8)
GIT_DIR != GIT_COMMON, detached HEAD	Reduced 3 options (no merge)	No cleanup (externally managed)

Step 5: 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 6: 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 and create a Pull Request
3. Keep the branch as-is (I'll handle it later)
4. Discard this work

Which option?

Detached HEAD — present exactly these 3 options:

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

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

Which option?

Don't add explanation - keep options concise.

Step 7: Execute Choice

Option 1: Merge Locally

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

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

# Verify tests on merged result
<test command>

# Only after merge succeeds: cleanup worktree (Step 8), then delete branch

Then: Cleanup worktree (Step 8), then delete branch:

git branch -d <feature-branch>

Option 2: Push and Create PR

# Push branch
git push -u origin <feature-branch>

# Create draft PR so CI can start before human review
gh pr create --draft --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"

Do NOT clean up worktree — user needs it alive to iterate on PR feedback. After the draft PR is created, run the local quality gate before marking it ready.

Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

Don't cleanup worktree.

Option 4: Discard

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"

Then: Cleanup worktree (Step 8), then force-delete branch:

git branch -D <feature-branch>

Step 8: Cleanup Workspace

Only runs for Options 1 and 4. Options 2 and 3 always preserve the worktree.

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)
WORKTREE_PATH=$(git rev-parse --show-toplevel)

If GIT_DIR == GIT_COMMON: Normal repo, no worktree to clean up. Done.

If worktree path is under .worktrees/, worktrees/, or ~/.config/superpowers/worktrees/: Superpowers created this worktree — we own cleanup.

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"
git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

Otherwise: The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.

Quick Reference

Option	Merge	Push	Keep Worktree	Cleanup Branch
1. Merge locally	yes	-	-	yes
2. Create PR	-	yes	yes	-
3. Keep as-is	-	-	yes	-
4. Discard	-	-	-	yes (force)

Common Mistakes

Skipping test verification

• Problem: Merge broken code, create failing PR
• Fix: Always verify tests before offering options

Marking draft PR ready before local checks

• Problem: Worktree is dirty, local tests are failing, or known local reviewer findings remain
• Fix: Run the local quality gate and stop on any local blocker

Waiting for remote CI before ready

• Problem: A draft PR stays draft even though local quality gate passed
• Fix: Do not wait for remote CI before marking ready; CI can continue on the ready PR

Open-ended questions

• Problem: "What should I do next?" is ambiguous
• Fix: Present exactly 4 structured options (or 3 for detached HEAD)

Cleaning up worktree for Option 2

• Problem: Remove worktree user needs for PR iteration
• Fix: Only cleanup for Options 1 and 4

Deleting branch before removing worktree

• Problem: git branch -d fails because worktree still references the branch
• Fix: Merge first, remove worktree, then delete branch

Running git worktree remove from inside the worktree

• Problem: Command fails silently when CWD is inside the worktree being removed
• Fix: Always cd to main repo root before git worktree remove

Cleaning up harness-owned worktrees

• Problem: Removing a worktree the harness created causes phantom state
• Fix: Only clean up worktrees under .worktrees/, worktrees/, or ~/.config/superpowers/worktrees/

No confirmation for discard

• Problem: Accidentally delete work
• Fix: Require typed "discard" confirmation

Red Flags

Never:

• Proceed with failing tests
• Merge without verifying tests on result
• Delete work without confirmation
• Force-push without explicit request
• Remove a worktree before confirming merge success
• Clean up worktrees you didn't create (provenance check)
• Run git worktree remove from inside the worktree

Always:

• Verify tests before offering options
• Detect environment before presenting menu
• Present exactly 4 options (or 3 for detached HEAD)
• Get typed confirmation for Option 4
• Clean up worktree for Options 1 & 4 only
• cd to main repo root before worktree removal
• Run git worktree prune after removal