gh-withzombies-hyperpowers/skills/finishing-a-development-branch/SKILL.md

name, description

name	description
finishing-a-development-branch	Use when implementation complete and tests pass - closes bd epic, presents integration options (merge/PR/keep/discard), executes choice

<skill_overview> Close bd epic, verify tests pass, present 4 integration options, execute choice, cleanup worktree appropriately. </skill_overview>

<rigidity_level> LOW FREEDOM - Follow the 6-step process exactly. Present exactly 4 options. Never skip test verification. Must confirm before discarding. </rigidity_level>

<quick_reference>

Step	Action	If Blocked
1	Close bd epic	Tasks still open → STOP
2	Verify tests pass (test-runner agent)	Tests fail → STOP
3	Determine base branch	Ask if needed
4	Present exactly 4 options	Wait for choice
5	Execute choice	Follow option workflow
6	Cleanup worktree (options 1,2,4 only)	Option 3 keeps worktree

Options: 1=Merge locally, 2=PR, 3=Keep as-is, 4=Discard (confirm) </quick_reference>

<when_to_use>

• Implementation complete and reviewed
• All bd tasks for epic are done
• Ready to integrate work back to main branch
• Called by hyperpowers:review-implementation (final step)

Don't use for:

• Work still in progress
• Tests failing
• Epic has open tasks
• Mid-implementation (use hyperpowers:executing-plans) </when_to_use>

<the_process>

Step 1: Close bd Epic

Announce: "I'm using hyperpowers:finishing-a-development-branch to complete this work."

Verify all tasks closed:

bd dep tree bd-1  # Show task tree
bd list --status open --parent bd-1  # Check for open tasks

If any tasks still open:

Cannot close epic bd-1: N tasks still open:
- bd-3: Task Name (status: in_progress)
- bd-5: Task Name (status: open)

Complete all tasks before finishing.

STOP. Do not proceed.

If all tasks closed:

bd close bd-1

---

Step 2: Verify Tests

IMPORTANT: Use hyperpowers:test-runner agent to avoid context pollution.

Dispatch hyperpowers:test-runner agent:

Run: cargo test
(or: npm test / pytest / go test ./...)

Agent returns summary + failures only.

If tests fail:

Tests failing (N failures). Must fix before completing:

[Show failures]

Cannot proceed until tests pass.

STOP. Do not proceed.

If tests pass: Continue to Step 3.

---

Step 3: Determine Base Branch

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 4: 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 concise.

---

Step 5: Execute Choice

Option 1: Merge Locally

git checkout <base-branch>
git pull
git merge <feature-branch>

# Verify tests on merged result
Dispatch hyperpowers:test-runner: "Run: <test command>"

# If tests pass
git branch -d <feature-branch>

Then: Step 6 (cleanup worktree)

---

Option 2: Push and Create PR

Get epic info:

bd show bd-1
bd dep tree bd-1

Create PR:

git push -u origin <feature-branch>

gh pr create --title "feat: <epic-name>" --body "$(cat <<'EOF'
## Epic

Closes bd-<N>: <Epic Title>

## Summary
<2-3 bullets from epic implementation>

## Tasks Completed
- bd-2: <Task Name>
- bd-3: <Task Name>

## Test Plan
- [ ] All tests passing
- [ ] <verification steps from epic>
EOF
)"

Then: Step 6 (cleanup worktree)

---

Option 3: Keep As-Is

Report: "Keeping branch . Worktree preserved at ."

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 "discard" confirmation.

If confirmed:

git checkout <base-branch>
git branch -D <feature-branch>

Then: Step 6 (cleanup worktree)

---

Step 6: Cleanup Worktree

For Options 1, 2, 4 only:

# Check if in worktree
git worktree list | grep $(git branch --show-current)

# If yes
git worktree remove <worktree-path>

For Option 3: Keep worktree (don't cleanup). </the_process>

Developer skips test verification before presenting options # Step 1: Epic closed ✓ bd close bd-1

Step 2: SKIPPED test verification

Jump directly to presenting options

"Implementation complete. What would you like to do?

1. Merge back to main locally
2. Push and create PR ..."

User selects Option 1

git checkout main git merge feature-branch

Tests fail! Broken code now on main

<why_it_fails>

• Skipped mandatory test verification
• Merged broken code to main branch
• Other developers pull broken main
• CI/CD fails, blocks deployment
• Must revert, fix, merge again (wasted time) </why_it_fails>

**Follow Step 2 strictly:**

# After closing epic
bd close bd-1 ✓

# MANDATORY: Verify tests BEFORE presenting options
Dispatch hyperpowers:test-runner agent: "Run: cargo test"

# Agent reports
"Test suite passed (127 tests, 0 failures, 2.3s)"

# NOW present options
"Implementation complete. What would you like to do?
1. Merge back to main locally
..."

What you gain:

• Confidence tests pass before integration
• No broken code merged to main
• CI/CD stays green
• Other developers unblocked
• Professional workflow

Developer auto-cleans worktree for PR option # User selects Option 2: Create PR git push -u origin feature-auth gh pr create --title "feat: Add OAuth" --body "..."

Developer immediately cleans up worktree

git worktree remove ../feature-auth-worktree

PR gets feedback: "Please add rate limiting"

User: "Can you address the PR feedback?"

Worktree is gone! Have to recreate it

git worktree add ../feature-auth-worktree feature-auth

Lost local state, uncommitted experiments, etc.

<why_it_fails>

• Cleaned worktree when PR still active
• User likely needs worktree for PR feedback
• Have to recreate worktree for changes
• Lost any local uncommitted work
• Inefficient workflow </why_it_fails>

**Option 2 workflow (correct):**

git push -u origin feature-auth
gh pr create --title "feat: Add OAuth" --body "..."

# Report PR created
"Pull request created: https://github.com/user/repo/pull/42

Keeping worktree at ../feature-auth-worktree for PR updates."

# NO worktree cleanup
# User can address PR feedback in same worktree

Cleanup happens later when:

• PR is merged
• User explicitly requests cleanup
• User uses finishing-a-development-branch again after PR merges

What you gain:

• Worktree available for PR feedback
• No need to recreate worktree
• Preserve local state and experiments
• Efficient PR iteration workflow

Developer discards work without confirmation # User says: "Actually, discard this work"

Developer immediately executes

git checkout main git branch -D feature-experimental git worktree remove ../feature-experimental-worktree

50 commits deleted

User: "Wait, I meant discard the LAST commit, not the whole branch!"

Too late - work is gone

<why_it_fails>

• No confirmation before destructive action
• Misunderstood user intent
• Permanent data loss
• No way to recover work
• Catastrophic for user </why_it_fails>

**Option 4 workflow (correct):**

User: "Discard this work"

"This will permanently delete:
- Branch feature-experimental
- All commits:
  * a1b2c3d Add OAuth integration
  * d4e5f6g Add rate limiting
  * g7h8i9j Update tests
  ... (47 more commits)
- Worktree at ../feature-experimental-worktree

Type 'discard' to confirm."

# WAIT for exact confirmation
User types: "discard"

# NOW execute
git checkout main
git branch -D feature-experimental
git worktree remove ../feature-experimental-worktree

"Branch feature-experimental deleted."

What you gain:

• User sees exactly what will be deleted
• Explicit confirmation required
• Prevents accidental data loss
• Time to reconsider or clarify
• Safe destructive operations

<option_matrix>

Option	Merge	Push	Keep Worktree	Cleanup Branch	Cleanup Worktree
1. Merge locally	✓	-	-	✓	✓
2. Create PR	-	✓	✓	-	-
3. Keep as-is	-	-	✓	-	-
4. Discard	-	-	-	✓ (force)	✓
</option_matrix>

<critical_rules>

Rules That Have No Exceptions

1. Never skip test verification → Tests must pass before presenting options
2. Present exactly 4 options → No open-ended questions
3. Require confirmation for Option 4 → Type "discard" exactly
4. Keep worktree for Options 2 & 3 → PR and keep-as-is need worktree
5. Verify tests after merge (Option 1) → Merged result might break

Common Excuses

All of these mean: STOP. Follow the process.

• "Tests passed earlier, don't need to verify" (Might have changed, verify now)
• "User knows what they want" (Present options, let them choose)
• "Obvious they want to discard" (Require explicit confirmation)
• "PR done, cleanup worktree" (PR likely needs updates, keep worktree)
• "Too many options" (Exactly 4, no more, no less) </critical_rules>

<verification_checklist> Before completing:

• bd epic closed (all child tasks closed)
• Tests verified passing (via test-runner agent)
• Presented exactly 4 options (no open-ended questions)
• Waited for user choice (didn't assume)
• If Option 4: Got typed "discard" confirmation
• Worktree cleaned for Options 1, 4 only (not 2, 3)
• If Option 1: Verified tests on merged result

Can't check all boxes? Return to process and complete missing steps. </verification_checklist>

**This skill is called by:** - hyperpowers:review-implementation (final step after approval)

Call chain:

hyperpowers:executing-plans → hyperpowers:review-implementation → hyperpowers:finishing-a-development-branch
                         ↓
                   (if gaps found: STOP)

This skill calls:

• hyperpowers:test-runner agent (for test verification)
• bd commands (epic management)
• gh commands (PR creation)

CRITICAL: Never read .beads/issues.jsonl directly. Always use bd CLI commands.

**Detailed guides:** - [Git worktree management](resources/worktree-guide.md) - [PR description templates](resources/pr-templates.md) - [bd epic reference in PRs](resources/bd-pr-integration.md)

When stuck:

• Tasks won't close → Check bd status, verify all child tasks done
• Tests fail → Fix before presenting options (can't proceed)
• User unsure → Explain options, but don't make choice for them
• Worktree won't remove → Might have uncommitted changes, ask user