the-rabak/finishing-branch

Goal

Close out a feature branch with final verification, the correct shipping path, and cleanup of related artifacts.

Use this skill when

• Implementation is complete and the branch is ready to ship, merge, keep for review, or discard.
• /workflows-work is handing off to final branch completion.

Do not use this skill when

• Work is still in progress.
• You are already on the default branch with nothing to finish.
• Tests or linting are failing and have not been fixed yet.

Non-negotiable rules

• Run final tests and linting before any shipping action.
• Do not proceed if tests or linting fail.
• Stage files selectively; do not blindly commit everything.
• Ask the user which completion path they want unless the workflow is fully orchestrated and must default to PR creation.
• Include Post-Deploy Monitoring & Validation in the PR or MR description for every change.
• If a worktree was used, clean it up.
• Update the plan and execution session status if those artifacts exist.

Procedure

Execute the full source-of-truth workflow below. Preserve every conditional branch, phase, checklist, and validation step from the original instructions. When the workflow says to ask, wait, route, or run in parallel, do that exactly.

Finishing a Development Branch

A structured skill for completing work on a feature branch. Ensures all quality checks pass, presents clear options for what to do next, and handles cleanup.

Announce at start: "I'm using the finishing-branch skill to complete this work."

When to Use

• All implementation tasks are complete
• You are ready to ship or merge a feature branch
• Referenced at the end of workflows:work Phase 4
• Referenced by /lfg pipeline

When NOT to Use

• Work is still in progress (finish tasks first)
• You are on the default branch (nothing to finish)

The Process

Step 1: Final Verification

Run all quality checks and report results:

# 1. Run full test suite (detect project test command)
# npm test | pytest | cargo test | phpunit | go test | etc.

# 2. Run linting (detect project linter)
# eslint | ruff | clippy | pint | etc.

# 3. Check for uncommitted changes
git status

# 4. Check for untracked files that should be committed
git ls-files --others --exclude-standard

Report results clearly:

• Tests: X passed, Y failed (if any fail, stop here and fix first)
• Linting: pass/fail (if fail, fix first)
• Uncommitted changes: list them
• Untracked files: list them

Do NOT proceed if tests or linting fail. Fix issues first, then return to Step 1.

Step 2: Commit Remaining Changes

If there are uncommitted changes:

git add [relevant files]
git commit -m "feat(scope): final changes before merge

[description of what's included]"

Stage files selectively -- do not blindly git add . if there are files that should not be committed.

Step 3: Present Completion Options

Present the user with clear options:

Option A: Create a Pull Request (recommended for team projects)

• Push branch and generate PR description
• Include summary of changes, testing notes, screenshots (if UI)
• Include Post-Deploy Monitoring section

Option B: Merge to default branch (for solo projects or pre-approved changes)

• Verify the default branch is up to date
• Merge the feature branch
• Push the result

Option C: Keep the branch (for work that needs more review)

• Push the branch for others to review
• Do not merge yet

Option D: Discard the branch (if work is no longer needed)

• Confirm with user (this is destructive)
• Delete the branch

Ask the user which option they prefer. Do not assume.

When invoked by an orchestrator without user interaction available: Default to Option A (Create PR). Do not stall waiting for user input -- proceed with creating the PR automatically.

Step 4: Execute the Chosen Option

Option A: Create PR

git push -u origin [branch-name]

Generate a PR/MR description:

## Summary
- What was built and why
- Key decisions made

## Changes
- [List major changes with file references]

## Testing
- Tests added/modified
- Manual testing performed

## Post-Deploy Monitoring & Validation
- **What to monitor:** [logs, metrics, dashboards]
- **Expected healthy behavior:** [what success looks like]
- **Failure signals:** [what to watch for]
- **Validation window:** [how long to monitor]

## Screenshots
[If UI changes, include before/after screenshots]

---
[![Compound Engineered](https://img.shields.io/badge/Compound-Engineered-6366f1)](https://github.com/The-Rabak/compound-engineering-plugin)

Option B: Merge

# Update default branch
git checkout [default-branch]
git pull origin [default-branch]

# Merge feature branch
git merge [feature-branch] --no-ff -m "Merge [feature-branch]: [description]"

# Push
git push origin [default-branch]

# Clean up local branch
git branch -d [feature-branch]

Option C: Keep Branch

git push -u origin [branch-name]
echo "Branch pushed. Ready for review."

Option D: Discard

# Confirm with user first!
git checkout [default-branch]
git branch -D [feature-branch]
echo "Branch discarded."

Step 5: Clean Up

If a git worktree was used:

# Return to main working directory
cd [main-worktree-path]

# Remove the worktree
git worktree remove [worktree-path]

# Prune worktree references
git worktree prune

Update plan status (if a plan file was used):

• Change status: active to status: completed in the plan's YAML frontmatter
• This marks the plan as done so it is not picked up by future /workflows:work sessions

Update execution session (if STATE.md exists):

• Set status: completed in STATE.md
• Record completion timestamp

Step 6: Summary

Present a clear completion summary:

## Branch Complete: [branch-name]

- Action taken: [PR created / Merged / Kept / Discarded]
- Tests: [X passed]
- Commits: [N commits]
- Files changed: [N files]
- PR/MR: [link if created]
- Worktree: [cleaned up / N/A]
- Plan status: [updated to completed / N/A]

Required output

Return a branch-complete summary with:

• The branch name.
• The action taken.
• Test and lint results.
• Commit count or final commit.
• Files changed.
• PR or MR link if one was created.
• Worktree cleanup status.
• Plan and execution-session status updates.