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 structured options for merge, PR, or cleanup

Security Scan

The skill's instructions are coherent for finishing a git feature branch, but the SKILL.md invokes command-line tools and network operations (git, gh, test runners, worktree removal, push/delete) while the skill metadata declares no required binaries or credentials — a mismatch that could lead to unexpected failures or credential exposure if installed without caution.

Purpose & Capability

The skill's purpose (guiding branch completion) matches the instructions (run tests, merge/push/PR/discard, clean worktrees). However the registry metadata claims no required binaries or credentials, but the SKILL.md clearly expects git, git-worktree, a test runner (npm/cargo/pytest/go), basic shell tools (grep, cat), and the GitHub CLI (gh). That mismatch is problematic: a user would reasonably expect the skill to declare these dependencies.

Instruction Scope

The instructions are narrowly scoped to finishing a branch and include sensible safeguards (test verification, typed confirmation for discard, explicit options). They instruct the agent to run destructive commands (git branch -D, git worktree remove, git push), which is appropriate for the purpose but requires explicit user consent and correct credentials. The skill does not instruct the agent to read arbitrary unrelated files or environment variables.

Install Mechanism

This is an instruction-only skill with no install spec or code files, so nothing will be downloaded or written by the skill itself. That lowers installation risk.

Credentials

The SKILL.md implicitly requires authenticated git operations and use of the GitHub CLI (gh pr create), which require credentials (git remote auth and GH credentials like GITHUB_TOKEN or gh auth). The skill metadata declares no required env vars or primary credential, so the credential needs are not surfaced to the user. This is disproportionate: pushing, PR creation, and deletions should require explicit credential declarations and clear user consent.

Persistence & Privilege

The skill is not always-enabled and does not request persistent or cross-skill modification. It does perform destructive repo operations when invoked, but it does not request elevated platform privileges or to persistently alter agent configuration.

Scan Findings in Context

[NO_FINDINGS] expected: The regex scanner found no code files — this is expected because the skill is instruction-only (SKILL.md). The absence of findings is not evidence that the instructions are harmless; review of SKILL.md is the primary signal.

What to consider before installing

This skill appears to be a focused procedure for finishing a git branch, but there are important mismatches you should address before installing: (1) The SKILL.md runs git, git-worktree, a test runner (npm/cargo/pytest/go), grep/cat, and the GitHub CLI (gh) — but the package metadata declares no required binaries. Confirm those tools are available on the agent's PATH. (2) The skill will push branches and create PRs and can delete branches or worktrees; those operations require git/remote authentication (e.g., SSH keys or HTTPS creds) and gh auth (or a GITHUB_TOKEN). The skill does not declare required environment variables for credentials. Only install if you are comfortable providing the necessary credentials and trust the agent to perform destructive actions. (3) If you plan to let the agent run autonomously, restrict its scope or require explicit user confirmations for push/delete actions; consider running the skill in a dry-run mode first. Recommended fixes before proceeding: update the skill metadata to list required binaries (git, gh, appropriate test runners) and declare that authenticated git/GH credentials are required; add explicit dry-run and verbose confirmation options; and ensure discard/push operations require interactive confirmation from the human operator.

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