| name | finishing-a-development-branch |
| description | Use when implementation is complete and tests pass — presents structured options for merge, PR, or cleanup to integrate the work. |
| version | 1.0.0 |
Finishing a Development Branch
Overview
Guide completion of development work by presenting clear options and handling chosen workflow.
Core principle: Verify tests → Present options → Execute choice → Clean up.
Announce at start: "I'm using the coordinator:finishing-a-development-branch skill to complete this work."
The Process
Step 1: Verify Tests
Before presenting options, verify tests pass:
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: Continue to Step 2.
Step 2: Determine Base Branch
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: Present Options
Present exactly these 3 options:
Implementation complete. What would you like to do?
1. Merge to main via PR (recommended)
2. Create a Pull Request (manual merge later)
3. Keep the branch as-is (I'll handle it later)
Which option?
Don't add explanation - keep options concise.
Why no "discard" option: when this skill fires, work is reviewed, tested, and committed. Offering discard as a peer of "merge" treats the choice as ambivalent when it isn't. If the PM genuinely wants to throw the work away, they'll say so explicitly — and that path goes through deliberate destructive-action confirmation, not a numbered menu.
Step 4: Execute Choice
Option 1: Merge to main via PR (Recommended)
Invoke the merging-to-main skill. This creates a PR, waits for CI checks, and merges
on success. Branch is deleted after merge.
If on a worktree: worktree is removed after merge (Step 5).
Option 2: Create a Pull Request (manual merge later)
Push the feature branch and create a PR, but do NOT merge. Use this when:
- You want the PM to review the PR before merging
- CI needs to pass but you're not ready to merge yet
- You want to come back to this later
git push -u origin <feature-branch>
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>
## Test Plan
- [ ] <verification steps>
EOF
)"
If on a worktree: keep the worktree active.
Option 3: Keep the branch as-is
Don't merge, don't create PR. Branch stays. Use this when:
- Work is in progress and not ready for review
- You plan to continue in another session
Report: "Keeping branch . Worktree preserved at ."
If on a worktree: keep the worktree active.
Step 5: Cleanup Worktree
For Option 1:
Check if in worktree:
git worktree list | grep $(git branch --show-current)
If yes:
git worktree remove <worktree-path>
For Options 2 and 3: Keep worktree.
Quick Reference
| Option | PR | Merge | Keep Worktree | Cleanup Branch |
|---|
| 1. Merge via PR | ✓ | ✓ (CI-gated) | - | ✓ |
| 2. PR only | ✓ | - | ✓ | - |
| 3. Keep as-is | - | - | ✓ | - |
Common Mistakes
Skipping test verification
- Problem: Merge broken code, create failing PR
- Fix: Always verify tests before offering options
Open-ended questions
- Problem: "What should I do next?" → ambiguous
- Fix: Present exactly 3 structured options
Automatic worktree cleanup
- Problem: Remove worktree when might need it (Option 2, 3)
- Fix: Only cleanup for Option 1
Offering discard as a numbered option
- Problem: When work is reviewed, tested, and committed, presenting "discard" as a peer of "merge" treats the choice as ambivalent and invites accidental selection.
- Fix: Don't include discard in the menu. If the PM wants to throw work away, they'll say so explicitly — and that path is deliberate destructive-action confirmation, not a numbered choice.
Red Flags
Never:
- Proceed with failing tests
- Merge without verifying tests on result
- Offer discard as a numbered menu option
- Force-push without explicit request
Always:
- Verify tests before offering options
- Present exactly 3 options
- Clean up worktree for Option 1 only
Integration
Called by:
- Executor-dispatch workflow (
docs/wiki/delegate-execution.md) — After all tasks complete
- The PM directly — when a branch is ready for disposition (merge / PR / keep)
Not called by:
- /execute-plan — execute-plan finalizes and offers
/workstream-complete; it deliberately does not chain into branch disposition, since that reaches the keyword-gated /merge-to-main. Branch disposition is a separate, PM-invoked decision.
Pairs with:
- No worktrees — worktrees are forbidden. Use the active workstream branch for WIP parking.
