The Superpowers Finishing a Development Branch Skill

Introduction: Why “Done” Needs a Procedure

Ask ten engineers when a task is finished and you will get ten answers, and most of them are wrong in the same direction: too early. The tests pass on a good afternoon. The commit is made. The agent — human or AI — announces victory and drifts on, leaving a branch unverified, unmerged, undocumented, or quietly deleted at the wrong moment. The Superpowers finishing a development branch skill exists to close that gap. It implements the last step of a workflow — verification, options presentation, and cleanup — as a procedure instead of a mood.

This is the twelfth article in our deep-dive series on the Superpowers skills, and it covers the one you run at the end: superpowers-finishing-a-development-branch. Every prior skill produces work; this one decides what happens to it — and refuses to let that decision happen by accident.

What the Finishing a Development Branch Skill Actually Does

The SKILL.md states the core principle in a single line: verify tests → present options → execute choice → clean up. Four beats, no improvising. The skill takes over the moment implementation is complete and hands the work one of exactly four futures — merged, proposed, parked, or deleted — after a verification gate and with your explicit choice on the record.

The most consequential design decision is subtle: the skill never auto-merges. Integration is a judgment call — straight to main? Teammate’s eyes first? Park it until someone with more context returns? — and the skill refuses to make that call alone. What it will do unilaterally is verify: no option appears on the menu until the checks actually ran. Verification is the gate; you keep the steering.

The skill lives in software-development/superpowers-finishing-a-development-branch, and it is deliberately short — it runs after every task, so it has to be cheap enough to reach for constantly.

The Finish Checklist

The skill is a five-step checklist, and each step exists to kill a specific failure mode.

Step 1 — Verify. Run the project’s test suite before anything else: pytest tests/ -q, or whatever command is native to the project. If tests fail, the process stops. Not “proceed with a caveat” — stop, fix, re-run. This single rule prevents the worst failure in agentic work: offering you a merge button on code that does not pass its own tests.

Step 2 — Summarize. Write a concise account of the work while it is still fresh: what was built and why, which key files changed, what the test coverage shows, and any deviation from the original plan. It is not busywork: the summary becomes the PR description or the handoff note if someone else inherits the branch.

Step 3 — Present exactly four options. The skill mandates a closed menu, presented verbatim:

Implementation complete and verified. 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?

Not an open-ended “so, what next?” — that phrasing invites vague answers and accidental drift. Four named, mutually exclusive options cover every intent — integrate now, integrate through review, defer, or reverse — and turn the choice into a single keystroke.

Step 4 — Execute the choice. Each option has a defined path. Merge means checkout base, pull, merge, re-run the tests on the merged result, then delete the branch. Push-and-PR means git push -u origin <branch> plus a PR built from the Step 2 summary. Keep-as-is means one clean sentence: “Keeping branch <name>. You can return to it later.” And discard — discard demands a typed confirmation:

This will permanently delete:
- Branch <name>
- All commits since branching

Type ‘discard’ to confirm.

Deleting work is the one action from which there is no apology. An agent that nukes a branch on a half-heard “yeah, get rid of it” has committed the most expensive mistake this skill exists to prevent.

Step 5 — Document the result. The skill writes a completion summary to .hermes/plans/ or memory: what was delivered, final verification status, and how it was integrated. Six months later, the answer to “what happened to that feature?” is on disk.

The skill also catalogs its own anti-patterns, and they read like a confession sheet from every rushed session:

Mistake	Fix
Skip test verification	Always verify before offering options
Open-ended “what next?”	Present exactly 4 structured options
Auto-discard without confirm	Require typed “discard” confirmation
No summary of work	Always summarize what was done

And four hard red lines: never proceed with failing tests, never merge without verifying, never delete without confirmation, never force-push without an explicit request.

Real Example: Closing Out the SYNAS Audit

Here is the checklist on a real job that was never a code branch — exactly the case that tests whether a procedure is principled or merely git-flavored.

SYNAS is our always-on home server: OpenMediaVault on Debian, running 32 Docker containers across 26 networks — monitoring (checkmk, Portainer, Tactical RMM’s ten containers), game servers (DayZ, Ark, 7 Days to Die), AI services (open-webui, rea-mcp), automation (n8n), and vaultwarden. It is fenced behind an nftables drop-only ruleset, which is precisely the kind of machine where “I think it’s fine” is not an acceptable closing statement.

The audit — storage, network topology, container health, executed with the parallel-agents pattern from a written plan — reached its finish line like any implementation would:

Verify: instead of pytest, the suite was a fresh docker ps -a | grep -ci ’up’. It returned 32 — matching the report’s headline claim of 32/32 containers up and healthy, zero unhealthy, zero restarts in 48 hours. That count was measured seconds before the claim, not recalled from earlier in the session. That is the whole difference between “I believe everything is running” and “here is the number, fresh.”
Summarize: the Step 2 artifact was the status report itself — per-task findings, resource headroom (21 GiB memory available, swap barely touched), and recommendations graded no-action / nice-to-have / watch.
Present options: with no branch, merge and discard lose their literal meaning — but the shape of the choice survives. Integrate now (fold findings into the ops record), keep as-is (leave the branch or plan for later), or discard. A read-only audit can legitimately answer “keep as-is”; what it must not do is skip the step that forces the question.
Clean up and document: the report was committed to .hermes/plans/ as the completion artifact — plan, execution record, and evidence in one place. The audit’s only mutations were explicitly listed cleanups (orphaned volumes and networks) proposed to a human, never performed silently.

Run on a feature branch instead, the identical skeleton becomes pytest, the four-option menu, and a git branch -d after a verified merge. Same discipline, different verbs.

Sidebar: The last 10% that makes the difference between ‘done’ and ‘done’. There are two dones. Little-d done means the hard part is over — the feature exists, the fix works, you could demo it right now. Capital-D Done means someone else can trust it without asking you: the tests ran fresh, the result is integrated (or deliberately parked), the branch is not lurking unmerged in the repo, and a note exists explaining what happened. Little-d done is what you feel; Capital-D done is what your team and your future self actually receive. The gap is maybe ten percent of the effort and a disproportionate share of the trust. Skipping it feels free until someone merges the wrong branch, can’t find the report, or re-diagnoses the bug you “finished” — then it is the most expensive ten percent on the project. A finish checklist is not ceremony. It is how the effort you already spent stops leaking away.

When to Use It

The skill’s trigger is deceptively broad: implementation is complete. In practice, that means more than features on branches:

Every implementation — a feature, a script, a new module. The canonical case: tests green, menu offered, branch merged or proposed, worktree and branch cleaned up.
Every bug fix — especially the “quick” ones. A two-line fix that skips verification is how a regression rides in on a commit message that says “minor fix.” The fix is done when the regression test passes fresh, not when the edit compiles.
Every config change — this is where teams are sneakiest about skipping the skill. Changing an nftables ruleset, a compose file, or a cron schedule on a box like SYNAS has more blast radius than most feature work. Verification means the service actually reloads and answers; the options menu still applies, because “should this config go to production now?” is the same question as “merge or PR?”

The pattern to internalize: if the task changed state you or anyone else depends on, it has a finish line, and this skill owns it.

Related Deep Dives in the Series

verification-before-completion is the engine inside Step 1. It is the discipline that makes “all 32/32 containers healthy” mean a command was just run and returned 32 — evidence before assertions. finishing-a-development-branch is where that discipline gets its non-negotiable enforcement point: no fresh evidence, no options menu.
requesting-code-review sits immediately upstream. Review findings get fixed while the context is hot; by the time you reach the finish checklist, the review verdict is one more piece of evidence that the work is ready to integrate.
using-git-worktrees is bookends with this skill: worktrees give you an isolated workspace to build in, and the merge-with-cleanup step deletes the feature branch and releases the worktree so the workspace ledger stays honest.
executing-plans and subagent-driven-development are the workflow front-halves this skill completes — the plan’s last checkbox is the finish checklist’s first one.
Superpowers Dispatching Parallel Agents — when parallel agents earn their overhead, and how to brief each lane.
Receiving Code Review — evaluating review findings on technical merit, not ego.

Frequently Asked Questions

Q: Why present options instead of just merging when tests pass?
Green tests prove the work is correct; they say nothing about whether it should land on main now — maybe the team freezes the branch on Fridays, maybe the feature waits on a partner’s release. The skill automates the verifiable part and keeps the judgment human.

Q: What if tests fail at Step 1?
No menu, no options, no negotiation: fix and re-verify. An option list presented over red tests trains everyone to treat your verification as decoration.

Q: Isn’t this overkill for a one-line change?
Count the cost: one test command, one sentence of summary, one menu selection. Compare it to one unverified one-line change on a firewalled production NAS. The skill was written to be run every time, not reserved for occasions.

Key Takeaways

The Superpowers finishing a development branch skill formalizes the end of work: verify tests, summarize, present exactly four options (merge / PR / keep / discard), execute the choice, document the result.
Verification gates the menu — failing tests mean the conversation stops, and merges get re-verified on the merged result.
Deletion demands a typed discard; the skill would rather annoy you than delete your afternoon.
It applies beyond git: the SYNAS audit closed the same loop with a fresh 32/32 container count and a report committed to .hermes/plans/.
Every implementation, bug fix, and config change has a finish line — the last 10% is what turns “done” into Done.

Next in this series: using git worktrees — the isolation skill that gives this one a workspace worth cleaning up. Browse the full Skills We Use series index for all nineteen articles.