Finishing A Development Branch

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting s...

Security Scan

The skill’s instructions match its stated purpose, but the SKILL.md assumes various command-line tools and repo/auth state that are not declared and it executes potentially destructive git operations — these mismatches warrant caution before installing or running it.

Purpose & Capability

The skill name and description align with the instructions (verifying tests, choosing merge/PR/discard, cleaning worktrees). However the registry metadata declares no required binaries or env vars while the instructions clearly rely on git, git-worktree, a git remote (origin), the GitHub CLI (gh) for PR creation, and language test runners (npm/cargo/pytest/go). This is an omission/incoherence: those tools and network/auth access are realistically required to perform the tasks.

Instruction Scope

The SKILL.md stays on-task: verify tests, determine base branch, present four fixed options, and execute the chosen workflow. It explicitly requires confirmation before destructive actions (typed 'discard') and mandates test verification. Instructions do perform high-impact repo operations (merge, push, delete branch, remove worktree), which is appropriate for the skill’s purpose but must be treated as destructive by the user.

Install Mechanism

Instruction-only skill with no install steps and no code files — low installation risk. Nothing is downloaded or written by an install process according to the registry metadata.

Credentials

No environment variables or credentials are declared, yet the instructions assume authenticated access to a remote (git push, gh pr create). The GitHub CLI (gh) typically requires an authenticated session or GITHUB_TOKEN; pushing requires git remote credentials. The skill also references various language-specific test commands without declaring or checking for those runtimes. The lack of declared binaries/credentials is disproportionate to the actual requirements.

Persistence & Privilege

The skill is not force-included (always:false) and does not request persistent system-level privileges. It modifies the user's repository state (merges, deletes branches, removes worktrees) which is appropriate for its purpose but inherently destructive; this is a runtime privilege rather than a platform privilege and should be guarded by user confirmation and backups.

What to consider before installing

This skill appears to do what it says (finish a development branch) but has some important omissions and destructive actions to be aware of: - Missing declared requirements: The SKILL.md assumes git, git-worktree, the GitHub CLI (gh), and language test runners are available and that you have network/auth access to the repo, yet the skill declares no required binaries or credentials. Verify those tools are installed and authenticated before running. - Destructive operations: The skill can delete branches and remove worktrees. Ensure you have backups or that you run it on a non-critical clone first. Confirm the 'discard' confirmation behavior actually prevents accidental deletion in your environment. - Authentication: For 'gh pr create' and 'git push' to work the agent or environment must be authenticated (gh auth or GIT credentials). Decide whether you are comfortable giving the agent those capabilities; consider doing PR creation and pushes manually if you prefer. - Dry-run / review: If possible, run the steps in a dry-run mode or have the agent print the exact git commands it will run and require explicit user approval before executing them. If you intend to use this skill, require that the agent run only in an environment you control (local clone or CI job with disposable credentials), ensure gh/git are authenticated as expected, and prefer manual confirmation for any push/branch-delete operations.

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/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>

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