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

Worktree found → 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: git worktree remove .worktrees/auth

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

gambit:using-worktrees — cleans up worktree created by that skill

Name	finishing-branch
Description	Completes development work on a feature branch by verifying tasks and tests, then presenting integration options. Use when implementation is complete and all tasks pass, when ready to merge, create PR, or discard a branch, or after executing-plans finishes all tasks.

finishing-branch

SKILL.md