> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/obra/superpowers/llms.txt
> Use this file to discover all available pages before exploring further.

# Finishing a Development Branch

> Complete development work by presenting structured options for merge, PR, or cleanup

Guide the completion of development work by verifying tests, presenting clear options, and handling the chosen workflow. This skill ensures work is production-ready before integration.

## Core Principle

**Verify tests → Present options → Execute choice → Clean up**

Never merge untested code. Always give clear options. Always clean up when appropriate.

<Note>
  Always announce at start: "I'm using the finishing-a-development-branch skill to complete this work."
</Note>

## The Process

### Step 1: Verify Tests

<Warning>
  Before presenting options, verify tests pass:
</Warning>

```bash theme={null}
# 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

```bash theme={null}
# 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?
```

<Tip>
  Don't add explanations - keep options concise. The user knows what they mean.
</Tip>

### Step 4: Execute Choice

<Accordion title="Option 1: Merge Locally">
  ```bash theme={null}
  # 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)
</Accordion>

<Accordion title="Option 2: Push and Create PR">
  ```bash theme={null}
  # 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)
</Accordion>

<Accordion title="Option 3: Keep As-Is">
  Report: "Keeping branch \<name>. Worktree preserved at \<path>."

  **Don't cleanup worktree.**
</Accordion>

<Accordion title="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:

  ```bash theme={null}
  git checkout <base-branch>
  git branch -D <feature-branch>
  ```

  Then: Cleanup worktree (Step 5)
</Accordion>

### Step 5: Cleanup Worktree

**For Options 1, 2, 4:**

Check if in worktree:

```bash theme={null}
git worktree list | grep $(git branch --show-current)
```

If yes:

```bash theme={null}
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 Pitfalls

<Accordion title="Skipping test verification">
  **Problem:** Merge broken code, create failing PR

  **Fix:** Always verify tests before offering options
</Accordion>

<Accordion title="Open-ended questions">
  **Problem:** "What should I do next?" → ambiguous

  **Fix:** Present exactly 4 structured options
</Accordion>

<Accordion title="Automatic worktree cleanup">
  **Problem:** Remove worktree when might need it (Option 2, 3)

  **Fix:** Only cleanup for Options 1 and 4
</Accordion>

<Accordion title="No confirmation for discard">
  **Problem:** Accidentally delete work

  **Fix:** Require typed "discard" confirmation
</Accordion>

## Decision Tree

```
Tests pass?
├─ No → Fix tests first
└─ Yes → Present 4 options
    ├─ 1. Merge locally → Merge + verify + cleanup worktree
    ├─ 2. Create PR → Push + create PR + cleanup worktree
    ├─ 3. Keep as-is → Report + keep worktree
    └─ 4. Discard → Confirm → delete branch + cleanup worktree
```

## Red Flags

<Warning>
  **Never:**

  * Proceed with failing tests
  * Merge without verifying tests on result
  * Delete work without confirmation
  * Force-push without explicit request
</Warning>

<Tip>
  **Always:**

  * Verify tests before offering options
  * Present exactly 4 options
  * Get typed confirmation for Option 4
  * Clean up worktree for Options 1 & 4 only
</Tip>

## Integration with Other Skills

<CardGroup cols={2}>
  <Card title="Called by" icon="arrow-right">
    * **subagent-driven-development** (Step 7) - After all tasks complete
    * **executing-plans** (Step 5) - After all batches complete
  </Card>

  <Card title="Pairs with" icon="link">
    * **using-git-worktrees** - Cleans up worktree created by that skill
  </Card>
</CardGroup>

## Related Skills

* [Using Git Worktrees](/skills/using-git-worktrees) - Create isolated workspaces
* [Verification Before Completion](/skills/verification-before-completion) - Verify work before claiming complete