home / skills / lerianstudio / ring / finishing-a-development-branch

finishing-a-development-branch skill

safe

/default/skills/finishing-a-development-branch

This skill guides finalizing a development branch by verifying tests, presenting four options, executing chosen workflow, and cleaning up.

npx playbooks add skill lerianstudio/ring --skill finishing-a-development-branch

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.5 KB

---
name: ring:finishing-a-development-branch
description: |
  Branch completion workflow - guides merge/PR/cleanup decisions after implementation
  is verified complete.

trigger: |
  - Implementation complete (tests passing)
  - Ready to integrate work to main branch
  - Need to decide: merge, PR, or more work

skip_when: |
  - Tests not passing → fix first
  - Implementation incomplete → continue development
  - Already merged → proceed to next task

sequence:
  after: [verification-before-completion, ring:requesting-code-review]
---

# 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

Run `npm test / cargo test / pytest / go test ./...` **If tests fail:** Show failures, stop. Cannot proceed until tests pass.

### Step 2: Determine Base Branch

```bash
git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
```

### Step 3: Present Options

Present exactly these 4 options (no explanation):
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

### Step 4: Execute Choice

| Option | Commands |
|--------|----------|
| **1. Merge Locally** | `git checkout <base>` → `git pull` → `git merge <feature>` → verify tests → `git branch -d <feature>` → Cleanup worktree |
| **2. Create PR** | `git push -u origin <feature>` → `gh pr create --title "..." --body "## Summary..."` → Cleanup worktree |
| **3. Keep As-Is** | Report: "Keeping branch <name>. Worktree preserved at <path>." **Don't cleanup.** |
| **4. Discard** | **Confirm first:** "Type 'discard' to confirm." → `git checkout <base>` → `git branch -D <feature>` → Cleanup worktree |

### Step 5: Cleanup Worktree

**Options 1, 2, 4:** `git worktree list | grep $(git branch --show-current)` → if in worktree: `git worktree remove <path>`
**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

| Mistake | Problem | Fix |
|---------|---------|-----|
| Skipping test verification | Merge broken code, create failing PR | Always verify tests before offering options |
| Open-ended questions | "What should I do next?" → ambiguous | Present exactly 4 structured options |
| Automatic worktree cleanup | Remove worktree when might need it | Only cleanup for Options 1 and 4 |
| No confirmation for discard | Accidentally delete work | 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:**
- **ring:subagent-driven-development** (Step 7) - After all tasks complete
- **ring:executing-plans** (Step 5) - After all batches complete

**Pairs with:**
- **ring:using-git-worktrees** - Cleans up worktree created by that skill

Overview

This skill guides the safe completion of a development branch by enforcing test verification, presenting a fixed set of post-implementation options, executing the chosen workflow, and performing appropriate cleanup. It ensures merges, PRs, or branch deletions are done only after passing tests and with required confirmations. The flow reduces accidental data loss and supports consistent engineering practices.

How this skill works

First, it runs the project's test suite (npm/cargo/pytest/go test) and halts if any test fails, reporting failures. Next it detects the base branch (main or master) and presents exactly four options: merge locally, push and create a PR, keep the branch as-is, or discard the work. When the user chooses, it executes the corresponding git commands, verifies tests again when merging, and enforces a typed confirmation for destructive discard. Finally, it removes any worktree only for the workflows that require cleanup.

When to use it

After completing an implementation that is ready for review or integration
When you need an unambiguous, audit-friendly branch completion workflow
Before merging or opening a PR to ensure tests and cleanup rules are followed
When multiple contributors must follow consistent branch finish steps

Best practices

Always run and pass the full test suite before presenting options
Present the four structured choices exactly to avoid ambiguity
Require an explicit typed confirmation before discarding branch work
Verify tests again after a local merge before deleting the feature branch
Only remove the worktree for branches that were merged or discarded

Example use cases

Local merge: integrate a finished feature into main, run tests, and delete the feature branch and worktree
Create PR: push the feature branch and open a GitHub PR while preserving the local worktree for follow-up
Keep branch: pause work and preserve the local worktree and branch for later continuation
Discard work: confirm intent by typing 'discard', then force-delete the branch and clean up the worktree

FAQ

What happens if tests fail?

The workflow stops, reports failures, and does not present the four options until tests pass.

Which branches are considered base branches?

The skill detects the base using git merge-base with main first, falling back to master if needed.