| name | finishing-branch |
| description | Use when all epic tasks show completed, when ready to integrate after review approval, when choosing between merge / PR / keep / discard for a branch, when tests need final verification before integration, or when a merge produced conflicts that require re-testing. User phrases like "ready to merge", "open a PR", "done with this branch", "ship it". |
| user_invokable | true |
Finishing a Branch
Overview
Complete development work by verifying readiness, presenting integration options, and executing the user's choice. Handles merge, PR creation, keeping work, or discarding — with appropriate safety gates for each.
Core principle: Verify everything passes → Present options → Execute choice → Clean up only what should be cleaned up.
Announce at start: "I'm using gambit:finishing-branch to complete this work."
Rigidity Level
LOW FREEDOM — Follow the process exactly. Never skip test verification. Never discard without typed confirmation. Always use AskUserQuestion for options.
Quick Reference
| Step | Action | STOP If |
|---|
| 1. Verify Tasks | TaskList — all must be "completed" | Any task incomplete |
| 2. Verify Tests | Run full test suite (skip if review just ran it) | Any test fails |
| 3. Base Branch | Detect via git merge-base | Can't determine base |
| 4. Present Options | AskUserQuestion with 4 choices | No response |
| 5. Execute Choice | Merge / PR / Keep / Discard | Git command fails |
| 6. Cleanup | Remove worktree if applicable | Only for merge/discard |
Iron Law: Tests must be known-green BEFORE presenting options — either freshly run here (standalone invocation) or verified by gambit:review at its handoff (chained invocation). Never present options without recent green evidence.
When to Use
- All tasks for an epic show "completed"
- Implementation reviewed and ready to integrate
- After
gambit:review approves the implementation
Don't use when:
- Tasks still open → use
gambit:executing-plans
- Epic not yet reviewed → use
gambit:review first
- Tests failing → fix first
- Work still in progress
- No epic exists → use
gambit:brainstorming
The Process
Step 1: Verify All Tasks Complete
Run TaskList. All tasks must show status="completed".
If tasks still open — STOP:
Cannot finish: N tasks still open:
- [task-id]: Task Name (status: in_progress)
- [task-id]: Task Name (status: pending)
Complete all tasks before finishing.
If all complete: Read the epic with TaskGet and verify all success criteria are met.
Step 2: Verify Tests Pass
Skip this step if invoked by gambit:review. Review's handoff guarantees tests are green (either freshly run in its Step 7 after implementing improvements, or already green since review began and no code changed). Re-running here is pure redundancy. Trust review's handoff announcement and go to Step 3.
Run the full suite only when invoked standalone (user ran /gambit:finishing-branch directly without a prior review, or invoked from any path other than review's approval gate). Detect the test command from project files (go.mod → go test ./..., package.json → npm test, Cargo.toml → cargo test, pyproject.toml → pytest, Makefile → make test).
- All tests pass (or skipped because review just ran them) → Step 3
- Any test fails → STOP. Show failures. Cannot proceed until tests pass.
Step 3: Determine Base Branch
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
If this fails, ask the user what base branch to use.
Step 4: Present Options
Use AskUserQuestion — do not print options as text.
AskUserQuestion
questions:
- question: "All tasks complete, tests passing. How should we integrate?"
header: "Integration"
options:
- label: "Merge locally"
description: "Merge to <base-branch>, delete feature branch"
- label: "Create Pull Request"
description: "Push and create PR for review"
- label: "Keep as-is"
description: "Leave branch and worktree, handle later"
- label: "Discard"
description: "Delete all work (requires typed confirmation)"
multiSelect: false
STOP. Wait for user response. Do not add recommendations, defaults, or explanations.
The 4 options above are fixed. Never modify, reorder, add variants (like "merge and push"), or remove any. The "Never push main" rule means pushing is never offered — user pushes manually after merge.
Step 5: Execute Choice
Option 1: Merge Locally
-
git checkout <base-branch>
-
git pull
-
git merge <feature-branch>
-
Run tests on merged result — if tests fail, present sub-options:
- Fix failures before completing
- Abort merge (
git merge --abort)
STOP and wait for user choice.
-
git branch -d <feature-branch> (safe delete)
-
Go to Step 6
Do NOT push to remote. User pushes when ready.
Option 2: Create Pull Request
git push -u origin <feature-branch>- Read epic with
TaskGet for PR content
- Create PR:
gh pr create --title "feat: <epic-name>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets from epic requirements>
## Tasks Completed
<list from TaskList>
## Test Plan
- [ ] All tests passing
- [ ] <verification steps from epic>
EOF
)"
- Report PR URL
DONE — do NOT go to Step 6. Branch and worktree (if any) are preserved for PR feedback.
Option 3: Keep As-Is
Report: "Keeping branch <name>." If worktree exists, add: "Worktree preserved at <path>."
DONE — do NOT go to Step 6.
Option 4: Discard
- Show what will be deleted:
git log --oneline <base-branch>..HEAD
- Request typed confirmation:
This will permanently delete:
- Branch <name>
- All N commits listed above
- Worktree at <path> (if applicable)
Type 'discard' to confirm.
STOP. Wait for exact text "discard". Anything else → clarify, do not proceed.
git checkout <base-branch>git branch -D <feature-branch>- Go to Step 6
Step 6: Cleanup (Merge and Discard Only)
Only runs for Options 1 and 4. Options 2 and 3 skip this entirely.
Check if a worktree exists for this branch:
git worktree list
- Session is inside a worktree created by
EnterWorktree this session → ExitWorktree action: "remove" (for Discard, pass discard_changes: true only after the typed confirmation)
- Worktree exists from an earlier session or repo tooling (
.claude/worktrees/, .worktrees/) → return to the base branch, then git worktree remove <path>
- No worktree → skip (branch may not have used one)
Report cleanup results.
Examples
Good: Full Merge Process
Step 1: TaskList → all 4 tasks completed
Step 2: npm test → 127 tests passed
Step 3: git merge-base HEAD main → abc123
Step 4: [AskUserQuestion with 4 options]
User selects: Merge locally
Step 5: git checkout main
git pull
git merge feature-auth
npm test → 127 tests passed (verify merged result)
git branch -d feature-auth
Step 6: ExitWorktree action:"remove" (or git worktree remove for an older worktree)
Done. Feature merged to main.
Bad: Skip Tests + Cleanup PR Worktree
Step 1: Tasks complete
Step 2: SKIPPED ← WRONG: tests might fail
Step 4: User selects PR
Step 5: git push, gh pr create
git worktree remove ← WRONG: PR needs worktree
# Merged broken code. Lost worktree for PR feedback.
Good: Discard With Typed Confirmation
git log --oneline main..HEAD
→ a1b2c3d Add OAuth
→ d4e5f6g Add rate limiting
"This will permanently delete branch and 2 commits.
Type 'discard' to confirm."
User: "discard"
git checkout main && git branch -D feature-experimental
git worktree remove .claude/worktrees/experimental
Critical Rules
- Tests before options — run full suite and show output when invoked standalone; skip only when review handed off with a green-tests guarantee
- AskUserQuestion for options — never print options as text
- Typed "discard" for Option 4 — exact text, no shortcuts
- No worktree cleanup for PR or Keep — user needs it for feedback/later work
- Verify tests after merge — merged result might have conflicts
- All tasks complete first — no "mostly done" exceptions
- Never push main — not even as an option; user pushes manually
- Fixed option set — the 4 options are immutable; never add "merge and push" or other variants
Common rationalizations (all mean STOP, follow the process):
| Excuse | Reality |
|---|
| "Tests passed earlier" | RUN THEM NOW unless review just handed off with a green-tests guarantee — code might have changed |
| "User obviously wants to merge" | PRESENT ALL 4 OPTIONS — let them choose |
| "User said discard" | GET TYPED CONFIRMATION — "discard" exactly |
| "PR done, cleanup worktree" | KEEP IT — PR will need updates |
| "Tasks are mostly done" | ALL must be complete — no exceptions |
Verification Checklist
Integration
Called by:
- User via
/gambit:finishing-branch
gambit:review (after approval — the normal workflow path)- After
gambit:executing-plans → gambit:review completes
Calls:
gh CLI (PR creation)git commands (merge, branch, worktree)
Pairs with:
- The epic worktree (native
.claude/worktrees/ via ExitWorktree, or repo-managed) — cleaned up here on merge/discard
