raoofaltaher/ultrapowers/finishing-a-development-branch

Finishing a Development Branch

Overview

Core principle: Verify tests → Verify the whole-ticket review → 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 1b: Verify the Whole-Ticket Review

This step runs in the ticket form: .agents/ultrapowers.json exists at or above the working directory, the autopilot form does not apply, and the ticket id is known: from the conversation, else from the plan path plans/<ID>/, else from the branch name matched against the tasks/ folders (the id at the start of the branch name or after a separator). Outside it, continue to Step 2.

Read reviews/<ID>/TASK-REVIEW.md under the project root, the checkout that holds this branch. Its Repositories row names each branch and the head it was reviewed at; take the entry whose branch is this branch, or whose head matches when HEAD is detached. The report is current when that head is an ancestor of HEAD (git merge-base --is-ancestor <head> HEAD) and every commit since it touches only reviews/<ID>/ (git diff --name-only <head> HEAD lists nothing else).

The verdict informs the integration decision; it never makes it. Only your human partner's instruction to skip the gate, in so many words, skips it; then the menu message says the whole-ticket review was skipped at their request. A hurry, a demo, or "every task was reviewed" is not that instruction.

Step 2: Detect Environment

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:

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, 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

In the ticket form, the whole-ticket review's result comes first, above either menu, in two lines: the Verdict: line of reviews/<ID>/TASK-REVIEW.md and its finding counts, or task-review's last message when it stopped before a verdict. On FAIL or BLOCKED, the pull request option reads Push and create a draft Pull Request (option 2, or option 1 on a detached HEAD) and Option 2 below opens it as a draft. That wording swap is the only change the menus take.

Normal repo and named-branch worktree — present exactly these 3 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)
 
Which option?

Detached HEAD — present exactly these 2 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)
 
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 your human partner explicitly asking for it (see "If your human partner asks to discard the work" below). Wait for their answer; the integration decision is theirs.

Step 5: 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>

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:

git branch -d <feature-branch>

Option 2: Push and Create PR

git push -u origin <feature-branch>
# From a detached HEAD, name the new branch on the remote:
# git push origin HEAD:refs/heads/<new-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.

In the ticket form the description quotes the Verdict: line of reviews/<ID>/TASK-REVIEW.md, or says that the whole-ticket review was skipped at your human partner's request. On a FAIL or BLOCKED verdict the pull request is a draft: gh pr create --draft, glab mr create --draft, or the forge's draft setting.

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

Option 3: Keep As-Is

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

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. Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>
 
Type 'discard' to confirm.

Wait for that exact confirmation. When it arrives:

MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
cd "$MAIN_ROOT"

Then clean up the worktree (Step 6) and force-delete the branch:

git branch -D <feature-branch>

Step 6: Cleanup Workspace

Runs for Option 1 and confirmed discards. Options 2 and 3 always preserve the worktree. Both callers have already changed directory to the main repo root — worktree removal must run from outside the worktree — and use the GIT_DIR/GIT_COMMON/WORKTREE_PATH values captured in Step 2, from before that directory change.

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

If `WORKTREE_PATH` is under `.worktrees/` or `worktrees/`: Ultrapowers created this worktree — we own cleanup:

git worktree remove "$WORKTREE_PATH"
git worktree prune  # Self-healing: clean up any stale registrations

If removal is refused (contains modified or untracked files): the worktree holds files that exist nowhere else — uncommitted plans, notes, or scratch work. Never --force on your own initiative. Show your human partner what is at stake and ask:

git -C "$WORKTREE_PATH" status --porcelain -uall

Worktree removal refused — these files were never committed:
 
<file list>
 
1. Commit them to <branch> before cleanup
2. Move them into <main repo root>
3. Delete them (unrecoverable)
 
Which?

Carry out the choice, then remove the worktree.

Otherwise: The host environment owns this workspace — leave it in place. If your platform provides a workspace-exit tool, use it.

Quick Reference

Common Rationalizations