This page documents the finishing-a-development-branch skill: how it gates completion on test verification, what four options it presents to the user, the Git operations performed for each option, and how worktree cleanup is handled. For the earlier phase of setting up an isolated workspace, see Using Git Worktrees. For how this skill is called from the broader workflow pipeline, see Complete Workflow Pipeline.
The finishing-a-development-branch skill is the final step in the development pipeline. It runs after all implementation tasks are complete — whether via Subagent-Driven Development or Executing Plans in Batches — and handles the transition from a feature branch back into the main codebase (or deliberate abandonment of the work).
Skill file: skills/finishing-a-development-branch/SKILL.md
Core principle: Verify tests → Present options → Execute choice → Clean up.
Callers:
| Caller Skill | Step That Triggers This Skill |
|---|---|
subagent-driven-development | Step 7 — after all tasks complete |
executing-plans | Step 5 — after all batches complete |
Diagram: finishing-a-development-branch Execution Flow
Sources: skills/finishing-a-development-branch/SKILL.md1-201
Before any option is presented, the skill runs the project's test suite. This is a hard gate — failing tests block all merge and PR operations.
Tests failing (N failures). Must fix before completing:
[Show failures]
Cannot proceed with merge/PR until tests pass.
The test command is auto-detected by project type (same pattern as using-git-worktrees):
| Project File | Test Command |
|---|---|
package.json | npm test |
Cargo.toml | cargo test |
requirements.txt / pyproject.toml | pytest |
go.mod | go test ./... |
Sources: skills/finishing-a-development-branch/SKILL.md19-39
After tests pass, the base branch is resolved before presenting options:
If the base cannot be determined automatically, the skill asks the user to confirm.
Sources: skills/finishing-a-development-branch/SKILL.md41-47
The user is presented with exactly four choices — no additional explanatory text is added:
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?
Sources: skills/finishing-a-development-branch/SKILL.md49-63
Diagram: Git Operations by Option
Sources: skills/finishing-a-development-branch/SKILL.md65-134
After merging, tests are run again on the merged result in the base branch to catch integration issues. On success, the feature branch is deleted with git branch -d (safe delete — fails if unmerged).
The PR body is generated from a template:
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
The gh CLI tool is used to create the PR. The worktree is not cleaned up, since the branch still needs review.
No Git operations. The skill reports the branch name and worktree path. The worktree is preserved so the user can return to the work.
This is a destructive operation. The skill shows what will be permanently deleted (branch name, commits, worktree path) and waits for the user to type the exact string discard before proceeding. Uses git branch -D (force delete) rather than git branch -d.
Sources: skills/finishing-a-development-branch/SKILL.md65-134
Diagram: Worktree Cleanup Decision
The cleanup check uses git worktree list to confirm the current branch is registered as a worktree before attempting removal. This pairs directly with the worktree that was created by the using-git-worktrees skill at the start of the development cycle.
Sources: skills/finishing-a-development-branch/SKILL.md136-151
| Option | Merge | Push | Worktree | Branch Delete |
|---|---|---|---|---|
| 1. Merge locally | ✓ (git merge) | — | Removed | git branch -d |
| 2. Create PR | — | ✓ (git push) | Kept | — |
| 3. Keep as-is | — | — | Kept | — |
| 4. Discard | — | — | Removed | git branch -D |
Sources: skills/finishing-a-development-branch/SKILL.md152-159
| Mistake | Problem | Correct Behavior |
|---|---|---|
| Skipping test verification | Merges broken code or creates a failing PR | Always run tests before presenting options |
| Open-ended completion question | Ambiguous user response | Present exactly 4 structured options |
| Cleaning up worktree after Option 2 | Destroys workspace needed for review iteration | Only clean up for Options 1 and 4 |
| No confirmation before discard | Accidentally deletes work | Require typed discard string |
git branch -d after discard | Fails if branch not fully merged | Use git branch -D for Option 4 |
| Merging without re-testing | Integration bugs go undetected | Re-run tests after git merge in Option 1 |
Sources: skills/finishing-a-development-branch/SKILL.md161-192
Diagram: Skill Integration Map
Sources: skills/finishing-a-development-branch/SKILL.md193-201 skills/using-git-worktrees/SKILL.md211-217
The skill defines these absolute constraints:
Never:
discard confirmationAlways:
Sources: skills/finishing-a-development-branch/SKILL.md179-192
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.