Finishing a development branch

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 finishing-a-development-branch skill to complete this work."

The Process

Step 1: Verify Tests

Before presenting options, verify tests pass:

# Run project's test suite
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 1.5.

Step 1.5: Pre-Merge Checklist

After tests pass but before presenting options, verify:

Code Quality:

• No TODO comments that should be resolved before merge
• No console.log debugging statements in production code
• Error handling covers expected failure modes
• Lint and type checking pass

Security Quick Check:

• No secrets in code or version control
• Input validation on user-facing endpoints
• See references/security-checklist.md for full checklist

If any items fail, fix them before proceeding to Step 2.

Step 2: Determine Base Branch

# Try common base branches
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 4 options:

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?

Don't add explanation - keep options concise.

Step 4: Execute Choice

Option 1: Merge Locally

# Switch to base branch
git checkout <base-branch>

# Pull latest
git pull

# Merge feature branch
git merge <feature-branch>

# Verify tests on merged result
<test command>

# If tests pass
git branch -d <feature-branch>

Before merging/pushing, verify commit hygiene:

• Each commit does one logical thing (atomic commits)
• Commit messages explain the why, not just the what
• No formatting changes mixed with behavior changes
• No secrets in any commit

Then: Cleanup worktree (Step 5)

Option 2: Push and Create PR

# Push branch
git push -u origin <feature-branch>

# Create PR
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
<2-3 bullets of what changed>

## Test Plan
- [ ] <verification steps>
EOF
)"

Before merging/pushing, verify commit hygiene:

• Each commit does one logical thing (atomic commits)
• Commit messages explain the why, not just the what
• No formatting changes mixed with behavior changes
• No secrets in any commit

Then: Cleanup worktree (Step 5)

Option 3: Keep As-Is

Report: "Keeping branch <name>. Worktree preserved at <path>."

Don't cleanup worktree.

Option 4: Discard

Confirm first:

This will permanently delete:
- Branch <name>
- All commits: <commit-list>
- Worktree at <path>

Type 'discard' to confirm.

Wait for exact confirmation.

If confirmed:

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

Then: Cleanup worktree (Step 5)

Step 5: Cleanup Worktree

For Options 1, 2, 4:

Check if in worktree:

git worktree list | grep $(git branch --show-current)

If yes:

git worktree remove <worktree-path>

For Option 3: Keep worktree.

If not using a worktree (working directly on a branch), skip Step 5. The pre-merge checklist (Step 1.5) and completion options (Steps 2-4) still apply regardless of whether a worktree is involved.

Step 6: Update Backlog & Changelog

After completing the chosen option (merge, PR, keep, or discard):

1. Update backlog: Read docs/super-agent-skills/backlogs.md. Mark any related "In Progress" items as complete ([x]). Move completed items to the "Completed" section with today's date.
2. Update changelog: Append a one-line entry to docs/super-agent-skills/changelog.md under [Unreleased] describing what was shipped.
3. Suggest next: If the backlog "In Progress" is now empty, suggest the next item from "Up Next":

   "Backlog and changelog updated. Next in backlog: [next item]. Want to start on it?"

Step 7: Capture Learnings

Before moving on, reflect on this work phase:

Question	If yes →
Did the user correct you about a convention?	Add to CLAUDE.md ## Gotchas
Did a command fail due to project-specific setup?	Add to CLAUDE.md ## Commands
Did the code reviewer flag a pattern violation?	Add to .claude/rules/ as a path-scoped rule
Did the self-healing review loop hit 3 rounds?	Note that the spec/plan was ambiguous — add clarity for next time
Did you make the same mistake twice in this session?	Add to CLAUDE.md ## Gotchas (high priority — this will recur)

If any apply, offer to persist:

"I noticed [learning]. Want me to add this to CLAUDE.md so I remember next time?"

Only persist things Claude would get wrong without being told. Don't add obvious conventions Claude already knows.

Quick Reference

Option	Merge	Push	Keep Worktree	Cleanup Branch
1. Merge locally	✓	-	-	✓
2. Create PR	-	✓	✓	-
3. Keep as-is	-	-	✓	-
4. Discard	-	-	-	✓ (force)

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 4 structured options

Automatic worktree cleanup

• Problem: Remove worktree when might need it (Option 2, 3)
• Fix: Only cleanup for Options 1 and 4

No confirmation for discard

• Problem: Accidentally delete work
• Fix: Require typed "discard" confirmation

Anti-Rationalizations

Thought	Reality
"Tests pass, good enough to merge"	Tests are necessary but not sufficient. Check the pre-merge checklist.
"I'll remove the console.logs later"	Remove them now. They'll ship to production otherwise.
"The TODOs are for future work"	If they must be resolved before this feature works correctly, resolve them now.
"One big commit is fine"	One big commit is impossible to review, debug, or revert. Split into atomic commits.

Red Flags

Never:

• Proceed with failing tests
• Merge without verifying tests on result
• Delete work without confirmation
• Force-push without explicit request

Always:

• Verify tests before offering options
• Present exactly 4 options
• Get typed confirmation for Option 4
• Clean up worktree for Options 1 & 4 only

Integration

Called by:

• subagent-driven-development (Step 7) - After all tasks complete
• executing-plans (Step 5) - After all batches complete

Pairs with:

• using-git-worktrees - Cleans up worktree created by that skill