Finishing a Development Branch

Verify tests → present options → execute choice → clean up.

Checklist

1. Verify tests pass -- run full suite, show output (if project has tests)
2. Verify lint passes -- run linter, show output (if project has linter)
3. Verify build passes -- run build, show exit code (if project has build step)
4. Pre-merge review -- dispatch code-reviewer (see Step 2)
5. Update docs -- PROJECT.md, MAP.md, SESSION.md current?
6. Present options -- exactly 4 choices
7. Execute chosen option
8. Clean up -- remove worktree/branch if applicable

Step 1: Verify

Detect the base branch:

DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")

$DEFAULT_BRANCH = (git symbolic-ref refs/remotes/origin/HEAD 2>$null) -replace 'refs/remotes/origin/', '' ; if (-not $DEFAULT_BRANCH) { $DEFAULT_BRANCH = "main" }

Run the project's test suite, linter, and build. If the project doesn't have tests, a linter, or a build step configured, skip the corresponding step and note it.

# Run project's test suite (use command from PROJECT.md)
<test command per PROJECT.md>

# Run linter (if configured — use command from PROJECT.md)
<lint command per PROJECT.md>

# Run build (if configured — use command from PROJECT.md)
<build command per PROJECT.md>

If any verification fails → STOP. Do not proceed. Fix failures first.

If no test suite exists → provide manual verification evidence per GATES.md (actual command output required).

If tests pass → continue.

Clean up WIP commits: If git log --oneline $(git merge-base HEAD $DEFAULT_BRANCH)..HEAD | grep -E "^[a-f0-9]+ wip:" shows any results, clean them up before proceeding to merge or PR. To clean up WIP commits: git log --oneline $DEFAULT_BRANCH..HEAD to review, then git reset --soft $DEFAULT_BRANCH && git add -A && git commit -m 'feat: <description>' to squash into a single commit. Or keep individual commits if they are meaningful. Skip if choosing "keep branch as-is."

Step 2: Pre-Merge Code Review

Before presenting options, get a dedicated code review of the full branch diff:

1. Get the diff:

# Bash:
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
git diff $(git merge-base HEAD $DEFAULT_BRANCH) HEAD

# PowerShell:
$DEFAULT_BRANCH = (git symbolic-ref refs/remotes/origin/HEAD 2>$null) -replace 'refs/remotes/origin/', '' ; if (-not $DEFAULT_BRANCH) { $DEFAULT_BRANCH = "main" }
git diff (git merge-base HEAD $DEFAULT_BRANCH) HEAD

2. Dispatch code-reviewer (use code-reviewer agent if available, otherwise a general-purpose subagent):

## What Was Implemented
[One paragraph -- what you built]

## Requirements / Spec
[Task spec or acceptance criteria]

## Changes to Review
[git diff output]

3. Act on feedback: Fix CRITICAL/IMPORTANT issues immediately. Re-dispatch reviewer after fixes -- never skip re-review. Proceed only after APPROVED.

Step 3: Present Options

Present exactly these 4 options. Don't add explanation -- keep concise:

Verification 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?

In non-interactive or autonomous runs, default to option 3 (keep the branch) and state this choice explicitly.

Step 4: Execute

Option 1: Merge Locally

git checkout <base-branch>
git pull
git merge <feature-branch>
# If merge conflicts occur: resolve them, then run full test suite on merged result
# Run tests on merged result
<test command>
# If pass:
git branch -d <feature-branch>

Option 2: Push and Create PR

Check if gh CLI is available, then push and create PR. Adapt commands to your shell:

# Bash:
gh --version 2>/dev/null || echo "gh CLI not installed"
git push -u origin <feature-branch>
gh pr create --title "<title>" --body "<summary of changes>"

# PowerShell:
gh --version 2>$null; if (-not $?) { Write-Output "gh CLI not installed" }
git push -u origin <feature-branch>
gh pr create --title "<title>" --body "<summary of changes>"

If gh is not available, push and provide the URL to create PR in browser: https://github.com/<owner>/<repo>/compare/<branch>

Option 3: Keep As-Is

Report: "Branch <name> preserved. Resume with git checkout <name>."

Option 4: Discard

Confirm first:

This will permanently delete branch <name> and all its commits.
Type 'discard' to confirm.

Wait for typed confirmation. Then:

git checkout <base-branch>
git branch -D <feature-branch>

Transitions

Called by: mbscode:executing-plans, mbscode:subagent-driven-development, or mbscode:brainstorming (trivial tasks on feature branch) after all tasks After completion: Update SESSION.md with final state

Red Flags

Thought	Reality
"Tests probably pass"	Run them. Show output.
"I'll skip the PR description"	Write a real summary.
"Just merge, no need to ask"	Always present 4 options. User decides.
"Discard without confirming"	Always require typed confirmation.