Back to Workflow & Productivity
finishing-a-development-branch
gitmergepull requestbranch managementcode completionworkflow automationdevelopment processtesting
Install this skill
npx skills add obra/superpowersWorks across Claude Code, Cursor, Codex, Copilot & Antigravity
The finishing-a-development-branch skill acts as the final gatekeeper for code changes, ensuring that all work is validated before being integrated or discarded. By enforcing a mandatory test-verification phase before presenting workflow options, this skill prevents broken code from entering a base branch or a pull request. It systematically guides the user through common source control tasks—local merging, remote PR creation, archival, or branch deletion—while managing the lifecycle of temporary git worktrees. This skill minimizes manual overhead by handling branch switching, test re-validation, and path cleanup based on the selected outcome, ensuring developers do not leave clutter behind or commit untested changes to their repositories.
When to Use This Skill
- •Finalizing a completed feature branch after running all tests
- •Cleaning up a test environment or experimental worktree
- •Submitting a verified code change to a main branch via a pull request
- •Safely deleting local branches and associated worktrees once work is merged
How to Invoke This Skill
Example prompts that trigger this skill in Claude Code, Cursor, or Antigravity:
- “Finish up this development branch
- “I am done with this feature, what is next?
- “Close this branch and clean up
- “Merge my current work back into main
- “Handle the completion of this branch for me
Pro Tips
- 💡Always review the test failures thoroughly if the skill reports them; addressing the root cause is crucial before proceeding.
- 💡Before executing a merge, use the 'Keep the branch as-is' option to perform a manual final review or seek peer feedback if the project requires it.
- 💡Familiarize yourself with your project's specific branch naming conventions and base branches to answer any prompts accurately, ensuring correct integration paths.
What this skill does
- •Validates repository health by running test suites prior to any merge action
- •Presents a strictly defined four-option menu to avoid ambiguous branch management
- •Automates the lifecycle of feature branches including local merge, push-and-PR, or hard deletion
- •Manages Git worktree cleanup to keep the filesystem free of abandoned development contexts
- •Requires explicit verification for data-destructive actions like discarding work
When not to use it
- ✕When you are still actively developing and have not verified your code
- ✕When complex rebasing or interactive commit squashing is required before merge
Example workflow
- Initiate the skill upon task completion
- Allow the skill to execute the project's native test suite
- Review the four presented options in the chat interface
- Select the desired action (e.g., push and create PR)
- Confirm the action and allow the skill to perform the Git merge/PR/deletion
- Allow the skill to automatically remove the temporary worktree
Prerequisites
- –An initialized Git repository
- –A configured test suite command
- –Access to the GitHub CLI (gh) for PR creation
Pitfalls & limitations
- !Failing to fix test suite errors will block all completion options
- !Manual cleanup of worktrees may conflict if this skill is not used to finalize the branch
- !Accidental selection of the discard option will delete work permanently
FAQ
What happens if my tests fail during the process?
The skill stops immediately. It prevents any merging or pushing until you address the reported test failures.
Why does the skill ask for my confirmation when I choose to discard work?
This acts as a safety guard. It ensures you do not lose your commits unintentionally by requiring the specific word 'discard'.
Does this skill work with any language?
Yes, as long as you have a test command configured (e.g., npm test, pytest, go test) that the skill can execute.
When is my worktree removed?
Worktrees are removed automatically after a local merge or a discard operation, but are kept if you choose to push a PR or keep the branch as-is.
How it compares
Unlike a standard Git command, this skill forces a strict sequence of test-first validation and conditional cleanup, preventing the 'human error' of merging broken code or leaving abandoned worktrees behind.
📄 Full skill instructions — original source: obra/superpowers
# 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:**
**If tests fail:**
Stop. Don't proceed to Step 2.
**If tests pass:** Continue to Step 2.
### Step 2: Determine Base Branch
Or ask: "This branch split from main - is that correct?"
### Step 3: Present Options
Present exactly these 4 options:
**Don't add explanation** - keep options concise.
### Step 4: Execute Choice
#### Option 1: Merge Locally
Then: Cleanup worktree (Step 5)
#### Option 2: Push and Create PR
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:**
Wait for exact confirmation.
If confirmed:
Then: Cleanup worktree (Step 5)
### Step 5: Cleanup Worktree
**For Options 1, 2, 4:**
Check if in worktree:
If yes:
**For Option 3:** Keep worktree.
## 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
## 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
## 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 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/nullOr 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>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
)"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.
## 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
## 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
How to Use This Skill Unit
Option A: Project-Specific (Recommended)
- Click "Download" above
- In your project, create the directory:
.agent/skills/finishing-a-development-branch/ - Save the file as
SKILL.md - The agent will automatically discover the skill based on its description.
Option B: Global Installation (All Agents)
Save the file to these locations to make it available across all projects:
- Claude Code:
~/.claude/skills/obra/superpowers/finishing-a-development-branch/SKILL.md - Cursor:
~/.cursor/skills/obra/superpowers/finishing-a-development-branch/SKILL.md - Antigravity:
~/.gemini/antigravity/skills/obra/superpowers/finishing-a-development-branch/SKILL.md
🚀 Install with CLI:npx skills add obra/superpowers
Recommended Rules
View more rules →Python Testing Best Practices
PythonTestingQuality Assurance
You are an expert in Python testing with pytest and testing best practices. Key Principles: - Write tests before or alongside code (TDD/BDD) - Aim fo...
Next.js Testing Strategies Expert
Next.jsTestingJest
You are an expert in Next.js testing strategies and best practices. Key Principles: - Test Server and Client Components differently - Use Jest for un...
TypeScript Testing with Vitest/Jest Expert
TypeScriptTestingVitest
You are an expert in TypeScript testing with Vitest and Jest. Key Principles: - Write type-safe tests - Use proper test typing - Mock with TypeScript...
Recommended Workflows
View more workflows →Setup Husky Git Hooks
GitAutomationQuality
--- description: Automate code quality checks with pre-commit and pre-push hooks --- 1. **Install Husky**: - Install husky and lint-staged. // ...
Create GitHub PR Template
GitGitHubTeam
--- description: Standardize pull request descriptions for better code reviews --- 1. **Create Template Directory**: - GitHub looks for templates ...
E2E Testing Setup (Playwright)
TestingE2EPlaywright
--- description: Boilerplate setup for end-to-end testing --- 1. **Initialize Playwright**: - Run the init command. // turbo - Run `npm init...
