insta-recipe/.system/skills/finalize_branch.md

name, description

name	description
finalize_branch	squashes all commits on current branch, merges to main and deletes current branch

Finalize Branch Skill

This skill is used to finish work on a feature by squashing all commits on the current branch into a single commit, merging it into main, and deleting the feature branch. It includes comprehensive edge case handling.

Prerequisites

• Git repository initialized
• Commits made on current feature branch
• Current branch is NOT main
• All work is committed (no uncommitted changes)
• Main branch exists

Pre-Execution Checks

Before proceeding with the finalization workflow, verify these conditions:

1. Check Current Branch

git rev-parse --abbrev-ref HEAD

Edge Case: If the output is main, abort with error: "Already on main branch. Cannot finalize main branch."

2. Check for Uncommitted Changes

git status --porcelain

Edge Case: If output is non-empty, abort with error: "Uncommitted changes detected. Commit or stash changes before finalizing branch."

3. Check for Commits to Squash

git rev-list --count main..HEAD

Edge Case: If count is 0, abort with error: "No new commits on current branch to squash. Nothing to finalize."

4. Verify Main Branch Exists

git rev-parse --verify main

Edge Case: If command fails, abort with error: "Main branch does not exist. Cannot merge into non-existent branch."

Finalization Workflow

Step 1: Fetch Latest Changes

git fetch origin

Purpose: Ensure you have the latest main branch from remote Edge Case Handling: If fetch fails, log warning but continue (local merge may still work)

Step 2: Check for Merge Conflicts

git merge-base --is-ancestor main HEAD

Edge Case: If this returns false, main has commits not in current branch:

• Run: git rebase origin/main
• If rebase fails with conflicts, abort and inform: "Rebase conflicts detected. Resolve conflicts manually before retrying finalization."

Step 3: Squash All Commits

git reset --soft main

Purpose: Moves all changes to staging area, keeping files intact Verification: Run git status to confirm all files are staged

Step 4: Create Squashed Commit

git commit -m "<commit-message>"

Edge Cases:

• If commit fails with "nothing to commit", abort: "No changes to commit after squash operation."
• Use descriptive commit message based on branch name or feature implemented

Step 5: Switch to Main Branch

git checkout main

Edge Case: If checkout fails, abort: "Failed to switch to main branch. Branch may be locked or have other issues."

Step 6: Pull Latest Main (Final Check)

git pull origin main

Edge Case Handling:

• If pull shows merge conflicts, abort: "Merge conflicts on main branch. Resolve manually before retrying."
• If pull is already up-to-date, continue normally

Step 7: Merge Feature Branch

git merge <feature-branch-name>

Edge Cases:

• If merge fails with conflicts:
  • Abort merge: git merge --abort
  • Return error: "Merge conflicts detected. Resolve manually and retry finalization."
• If merge fails with other error, abort and investigate

Step 8: Push to Remote

git push origin main

Edge Cases:

• If push is rejected (force pull needed): Abort and inform: "Main branch has remote changes. Run 'git pull origin main' and retry."
• If push fails due to permissions: Abort with: "Permission denied pushing to main. Check git credentials and permissions."

Step 9: Delete Local Feature Branch

git branch -d <feature-branch-name>

Edge Case: If deletion fails (branch not fully merged), use force deletion:

git branch -D <feature-branch-name>

Warning: Only force delete if Step 7 merge succeeded.

Step 10: Delete Remote Feature Branch (if exists)

git push origin --delete <feature-branch-name>

Edge Cases:

• If branch doesn't exist on remote, continue normally
• If deletion fails due to permissions, log warning but consider success (local cleanup done)

Rollback Procedure

If any step fails, execute rollback:

# Return to feature branch if on main
git checkout <feature-branch-name>

# Reset to pre-squash state if already squashed
git reset --hard <original-commit-before-squash>

Important: Save the original branch commit SHA before beginning squash operation for rollback capability.

Success Criteria

✅ All checks passed ✅ Commits squashed into single commit ✅ Feature branch merged into main ✅ New commit pushed to remote ✅ Feature branch deleted locally and remotely ✅ Currently on main branch with latest changes

Error Handling Summary

Error	Action
Already on main	Abort, inform user
Uncommitted changes	Abort, instruct commit/stash
No commits to squash	Abort, inform no changes
Merge conflicts	Abort, instruct manual resolution
Push rejected	Abort, pull latest and retry
Permission errors	Abort, check git credentials
Remote branch missing	Continue (non-fatal)

Logging Requirements

Log all executed commands and their outputs for audit trail and debugging purposes.