finishing-a-development-branch
Use when completing work on a feature branch, preparing to merge, or cleaning up after development is done. Triggers: branch work is complete, user says "merge", "create PR", "finish branch", "done with this branch", ready for code review.
What this skill does
# Finishing a Development Branch ## Overview Provide a structured, safe process for completing work on a development branch, including verification, merge strategy selection, and cleanup. This skill ensures no branch is merged without passing tests, and every destructive operation requires explicit user confirmation. ## When to Use - All planned work on a feature branch is complete - A branch is ready for code review or merge - Cleaning up after development work is finished - Preparing a pull request for team review ## Phase 1: Verify All Tests Pass [HARD-GATE] Do NOT proceed to any merge or PR activity without passing verification. Before any merge or PR activity, invoke **verification-before-completion** to confirm: - All tests pass (unit, integration, e2e as applicable) - No lint errors or warnings - Build succeeds - No untracked files that should be committed ```bash # Run the project's full verification suite # Do NOT skip this step even if "tests were passing earlier" ``` If verification fails, STOP. Fix the failures before proceeding. Do NOT create PRs or merge branches with failing tests. **STOP — Verification must pass before continuing to Phase 2.** ## Phase 2: Determine Base Branch Identify the branch to merge into, using this detection logic: ### Auto-Detection ```bash # Check for common base branch names git branch -a | grep -E 'remotes/origin/(main|master|develop)$' # Check what branch was the fork point git log --oneline --decorate --graph HEAD...main --first-parent 2>/dev/null git log --oneline --decorate --graph HEAD...master --first-parent 2>/dev/null ``` ### Base Branch Selection Decision Table | Condition | Base Branch | Confidence | |---|---|---| | `main` exists | `main` | High | | Only `master` exists | `master` | High | | `develop` exists and project uses GitFlow | `develop` | Medium | | Multiple candidates found | Ask user | Required | | None of the above exist | Ask user | Required | ### Verify Base Branch is Up to Date ```bash git fetch origin git log HEAD..<base-branch> --oneline ``` If the base branch has advanced since the feature branch was created, inform the user. They may want to rebase or merge base into the feature branch first. ### Base Branch Divergence Decision Table | Divergence | Action | |---|---| | Base has 0 new commits | Proceed normally | | Base has 1-5 new commits | Inform user, suggest rebase | | Base has 6+ new commits | Warn user, recommend merge or rebase before proceeding | | Merge conflicts detected | STOP — resolve conflicts first | **STOP — Confirm the base branch with the user before proceeding.** ## Phase 3: Present Merge Options Present exactly these four options to the user. Do NOT add or remove options. ``` How would you like to finish this branch? A) Create PR -- push and open a pull request for review B) Merge -- merge into <base> with a merge commit C) Squash merge -- squash into one commit, merge into <base> D) Leave as-is -- keep the branch, decide later ``` ### Option Selection Decision Table | Context | Recommended Option | Why | |---|---|---| | Team project with code review | A) Create PR | Enables review workflow | | Solo project, clean history | B) Merge | Preserves full branch history | | Many WIP commits, messy history | C) Squash merge | Clean single commit on base | | Work incomplete or uncertain | D) Leave as-is | No risk, decide later | **STOP — Wait for user to select an option. Do NOT assume a default.** ## Phase 4: Execute Chosen Option ### Option A: Create Pull Request ```bash # Push the branch git push -u origin <branch-name> # Generate PR title from branch name or recent commits # Generate PR body from commit messages and diff summary gh pr create --title "<title>" --body "<body>" ``` **PR Title Generation:** - Derive from branch name: `feature/add-auth` becomes `Add authentication` - Keep under 70 characters - Use imperative mood **PR Body Generation:** - Summarize the changes (what and why) - List key modifications - Note any breaking changes - Include test plan ### Option B: Merge Locally ```bash # Switch to base branch git checkout <base-branch> # Merge feature branch git merge <feature-branch> # Delete the feature branch git branch -d <feature-branch> ``` **Confirmation required** before executing the merge. ### Option C: Squash Merge ```bash # Switch to base branch git checkout <base-branch> # Squash merge git merge --squash <feature-branch> # Commit with a comprehensive message git commit -m "<squash commit message>" # Delete the feature branch git branch -d <feature-branch> ``` **Squash commit message** should summarize all changes from the branch, not just the last commit. **Confirmation required** before executing the squash merge. ### Option D: Leave Branch As-Is No action needed. Inform the user: ``` Branch <branch-name> left as-is. You can return to it later with: git checkout <branch-name> ``` ## Phase 5: Cleanup After executing options A, B, or C, perform cleanup: ### Remove Worktree (if applicable) If the branch was developed in a git worktree: ```bash # Navigate out of the worktree first git worktree remove <worktree-path> git worktree prune ``` ### Clean Up Remote Tracking (Option B and C only) If the branch was previously pushed: ```bash # Delete remote branch after local merge git push origin --delete <branch-name> ``` **Confirmation required** before deleting remote branches. ### Verify Final State ```bash git status git log --oneline -5 ``` Confirm the base branch is in the expected state. ## Confirmation Requirements [HARD-GATE] The following operations require explicit user confirmation before execution. Do NOT proceed on assumption. Always ask. | Operation | Why Confirmation Is Required | |---|---| | Merge into base branch | Changes base branch history | | Squash merge | Loses individual commit history | | Delete local branch | Cannot be undone if not pushed | | Delete remote branch | Affects other collaborators | | Force remove worktree | May discard uncommitted changes | | Rebase onto updated base | Rewrites commit history | ## Anti-Patterns / Common Mistakes | Anti-Pattern | Why It Is Wrong | What to Do Instead | |---|---|---| | Merging without running tests | Broken code reaches base branch | Always run full verification first | | Skipping base branch freshness check | Merge conflicts discovered late | `git fetch` and check divergence | | Auto-selecting merge strategy | User may prefer different approach | Always present all four options | | Deleting branch without confirmation | Data loss risk | Ask before every deletion | | Creating PR with failing CI | Wastes reviewer time | Fix CI before creating PR | | Squash message from last commit only | Loses context of full branch work | Summarize all changes in squash msg | | Leaving stale remote branches | Cluttered repository | Clean up remote after merge | | Force-pushing after PR creation | Destroys review comments | Avoid force-push on PR branches | ## Error Handling | Error | Action | |---|---| | Merge conflicts | Report conflicts, ask user to resolve, do NOT auto-resolve | | Push rejected | Fetch and check if rebase/merge is needed | | PR creation fails | Check `gh auth status`, report error details | | Branch already deleted | Skip deletion, continue with remaining cleanup | | Tests fail | STOP immediately, do NOT merge or create PR | | Base branch does not exist on remote | Ask user to confirm the correct base | ## Integration Points | Skill | Integration | |---|---| | `verification-before-completion` | Must invoke in Phase 1 before any merge activity | | `using-git-worktrees` | Cleanup includes worktree removal if applicable | | `git-commit-helper` | Squash commit message follows conventional commit format | | `code-review` | PR creation (Option A) feeds into code review workflow | | `planning` | Branch completion is the final step of plan execution | | `deployment` | Merge to main/release may t
Related in Code Review
gstack
IncludedFast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)
startup-due-diligence
IncludedLegal due diligence review for seed-stage and Series A startups (US, Delaware C-Corp focus). Supports both investor and founder perspectives. Capabilities include: (1) Interactive document review and issue spotting; (2) Document request list generation; (3) Cap table and SAFE/convertible note analysis; (4) Red flag identification with severity ratings; (5) Diligence report generation. TRIGGERS: due diligence, DD, startup investment, cap table review, Series A, seed round, investor diligence, legal review startup, SAFE analysis, convertible note, 409A, founder vesting.
interview-master
IncludedThis skill should be used when the user asks to "generate interview questions", "prepare for interview", "optimize resume", "conduct mock interview", "analyze git commits for resume", "generate resume from code", "review my resume", or mentions interview preparation, career assistance, or extracting project experience from git history. Provides comprehensive interview and career development guidance for both job seekers and interviewers.
fix-issue
IncludedFixes GitHub issues using parallel analysis agents for root cause investigation, code exploration, and regression detection. Reads issue context from gh CLI, searches codebase and memory for related patterns, generates a fix with tests, and links the resolution back to the issue via PR. Includes prevention analysis to avoid recurrence. Use when debugging errors, resolving regressions, fixing bugs, or triaging issues.
sf-apex
IncludedGenerates and reviews Salesforce Apex code with 150-point scoring. TRIGGER when: user writes, reviews, or fixes Apex classes, triggers, test classes, batch/queueable/schedulable jobs, or touches .cls/.trigger files. DO NOT TRIGGER when: LWC JavaScript (use sf-lwc), Flow XML (use sf-flow), SOQL-only queries (use sf-soql), or non-Salesforce code.
swift-development
IncludedComprehensive Swift development for building, testing, and deploying iOS/macOS applications. Use when Claude needs to: (1) Build Swift packages or Xcode projects from command line, (2) Run tests with XCTest or Swift Testing framework, (3) Manage iOS simulators with simctl, (4) Handle code signing, provisioning profiles, and app distribution, (5) Format or lint Swift code with SwiftFormat/SwiftLint, (6) Work with Swift Package Manager (SPM), (7) Implement Swift 6 concurrency patterns (async/await, actors, Sendable), (8) Create SwiftUI views with MVVM architecture, (9) Set up Core Data or SwiftData persistence, or any other Swift/iOS/macOS development tasks.