merge-to-staging

name	merge-to-staging
description	Merge current feature branch into fresh staging branch with conflict resolution. Use when ready to deploy a feature branch to the staging environment.
allowed-tools	Bash(git status:*), Bash(git branch:*), Bash(git checkout:*), Bash(git pull:*), Bash(git merge:*), Bash(git add:*), Bash(git commit:*), Bash(git log:*), Bash(git diff:*), Bash(git push:*), Bash(git fetch:*), Bash(git remote:*), Read, Edit

Merge to Staging

You are tasked with merging the current feature branch into a fresh staging branch (recreated from remote) and pushing the changes to remote. This ensures you're always working with the latest staging state without local modifications.

Execution Paths (Automatic vs Manual)

This command supports fully automatic execution when possible:

Path A: Clean Merge (100% Automatic)

1. Prepare staging → 2. Merge → ✅ Success → 4. Verify → 5. Push → 6. Return

Zero user prompts - Completes automatically when there are no conflicts.

Path B: High-Confidence Conflicts Only (100% Automatic)

1. Prepare staging → 2. Merge → ⚠️ Conflicts → 3.1 Analyze → 3.2 Auto-resolve all → 3.5 Commit → 4. Verify → 5. Push → 6. Return

Zero user prompts - All conflicts have ≥90% confidence and are auto-resolved (formatting, non-overlapping changes, additive imports).

Path C: Complex Conflicts Present (Semi-Automatic)

1. Prepare staging → 2. Merge → ⚠️ Conflicts → 3.1 Analyze → 3.2 Auto-resolve simple → 3.3 Ask user for complex → 3.4 Apply decisions → 3.5 Commit → 4. Verify → 5. Push → 6. Return

User prompted ONLY for complex conflicts - Simple conflicts auto-resolve, you only see conflicts that require business logic decisions.

---

Process:

1. Prepare Fresh Staging Branch

• Run git fetch origin to fetch latest remote branches
• Check if local staging branch exists: git branch --list staging
• If local staging exists:
  • Run git branch -D staging to delete the local staging branch
  • Confirm deletion: "Deleted local staging branch to ensure fresh start"
• Run git checkout -b staging origin/staging to create a fresh local staging branch from remote
• Verify: "Now on a fresh staging branch tracking origin/staging"

2. Merge Feature Branch

• Run git branch --show-current to save the current feature branch name (if not already done)
• Run git merge <feature-branch-name> --no-edit to merge the feature branch
• If merge is successful, proceed to step 4
• If there are merge conflicts, proceed to step 3

3. Handle Merge Conflicts (if they occur)

3.1 Analyze All Conflicts (Deep Thinking Phase)

For each conflicted file, perform ultra-detailed analysis:

1. Read both versions completely using Read tool

2. Understand the context of changes in both versions

3. Classify the conflict into one of these categories:

   • TRIVIAL: Formatting, whitespace, comment changes only
   • SIMPLE: Non-overlapping logic changes, import additions, simple refactors
   • COMPLEX: Overlapping logic changes, business rule conflicts, architecture differences

4. Calculate confidence score (0-100%) based on:

   • 100%: Pure formatting/whitespace differences
   • 90-99%: Clear non-overlapping changes (e.g., different functions modified, additive imports)
   • 70-89%: Same area modified but changes are compatible and can be combined logically
   • 50-69%: Changes affect related logic but resolution path is unclear
   • 0-49%: Conflicting business logic, mutually exclusive changes, or unknown impact

5. Determine resolution strategy for each conflict:

Decision Tree:

Conflict Analysis
    ↓
Confidence ≥ 90% ?
    ↓
├─ YES → AUTO-RESOLVE
│   ├─ Trivial (100%): Apply feature branch version
│   ├─ Simple additive (90-99%): Merge both changes
│   └─ Log decision with clear reasoning
│
└─ NO → REQUIRES USER INPUT
    └─ Prepare detailed analysis for user review

3.2 Auto-Resolve High-Confidence Conflicts

Automatically resolve conflicts with ≥90% confidence:

For TRIVIAL conflicts (confidence = 100%):

• Formatting/whitespace only → Use feature branch version (newer)
• Run: git checkout --theirs <file>
• Log: "✓ Auto-resolved : formatting difference (kept feature branch)"

For SIMPLE conflicts (confidence = 90-99%):

Pattern 1: Non-overlapping imports/exports

Staging adds: import { A } from 'lib'
Feature adds: import { B } from 'lib'
→ Resolution: Combine both, deduplicate, sort
→ Confidence: 95%

• Read both versions
• Merge imports intelligently using Edit tool
• Log: "✓ Auto-resolved : merged imports from both branches"

Pattern 2: Different functions modified

Staging modifies: function foo()
Feature modifies: function bar()
→ Resolution: Keep both changes
→ Confidence: 95%

• Use Edit tool to combine both changes
• Log: "✓ Auto-resolved : combined independent changes"

Pattern 3: Additive changes (no deletions)

Staging adds: new field X
Feature adds: new field Y
→ Resolution: Include both additions
→ Confidence: 90%

• Merge both additions using Edit tool
• Log: "✓ Auto-resolved : included additions from both branches"

After auto-resolution:

• Run git add <file> for each resolved file
• Provide summary: "Auto-resolved X/Y conflicts with high confidence"

Determine next step:

• ✅ If ALL conflicts were auto-resolved (100% automatic path): Proceed directly to step 3.5 (skip 3.3 and 3.4)
• ⚠️ If complex conflicts remain (confidence < 90%): Continue to step 3.3

3.3 Present Complex Conflicts to User (⚠️ SKIP THIS STEP if all conflicts were auto-resolved)

If conflicts with confidence < 90% exist:

1. Create detailed analysis for each complex conflict:

🧠 COMPLEX CONFLICT ANALYSIS

File: <filename>
Confidence: <X>%
Complexity: COMPLEX

📊 STAGING VERSION (HEAD):
<show relevant code section>
Intent: <what this change tries to achieve>
Modified by: <commit info if helpful>

📊 FEATURE BRANCH VERSION:
<show relevant code section>
Intent: <what this change tries to achieve>

⚠️ CONFLICT NATURE:
<detailed explanation of why these changes conflict>

🤔 RESOLUTION OPTIONS:

Option A: Keep Feature Branch
Pros: <specific benefits>
Cons: <specific risks>
Impact: <what breaks/works>

Option B: Keep Staging
Pros: <specific benefits>
Cons: <specific risks>
Impact: <what breaks/works>

Option C: Intelligent Merge
Approach: <specific merge strategy>
Pros: <specific benefits>
Cons: <specific risks>
Requires: <manual code changes needed>

💡 RECOMMENDED ACTION: <Option X>
Reasoning: <ultra-detailed explanation of why this is best>

---

2. Present ALL complex conflicts together in one message

3. Ask user for decision with clear options:

   • "✅ Approve all recommendations" - Execute recommended actions
   • "✏️ Customize resolution for specific files" - User chooses different option per file
   • "🔍 Show full diff for " - See complete file comparison
   • "❌ Abort merge" - Cancel and return to feature branch

4. Wait for user's decision before proceeding

5. If user asks for more context:

   • Use git log <file> to show commit history
   • Use git show <commit>:<file> to see specific versions
   • Use git diff --ours --theirs <file> for detailed diff
   • Read surrounding code for additional context

3.4 Execute User-Approved Resolutions (⚠️ SKIP THIS STEP if no user input was needed)

Apply resolutions in this order:

1. Auto-resolved conflicts (already staged in 3.2 - nothing to do here)
2. User-approved complex conflicts (only if step 3.3 occurred):

For each conflict resolution:

• Keep Feature Branch: git checkout --theirs <file>
• Keep Staging: git checkout --ours <file>
• Intelligent Merge:
  • Read both versions using Read tool
  • Combine changes logically using Edit tool
  • Preserve functionality from both sides
  • Verify the merge makes sense
  • Stage with git add <file>

3. Verify all conflicts resolved:
   • Run git status to confirm no unmerged paths
   • If conflicts remain, stop and report error

3.5 Complete Merge Resolution

After resolving all conflicts:

• Run git add . to ensure all resolved files are staged
• Run git status to verify clean state
• Run git commit --no-edit to complete the merge
• If commit fails, create merge commit with: git commit -m "Merge <feature-branch> into staging"

Provide resolution summary:

✅ Conflict Resolution Complete

Total conflicts: <N>
├─ Auto-resolved (≥90% confidence): <X>
│  ├─ Trivial (formatting): <N1>
│  └─ Simple (non-overlapping): <N2>
└─ User-approved (complex): <Y>

All changes verified and committed.

4. Verify Merge Success

After successful merge:

• Run git log --oneline -5 to show recent commits
• Run git diff origin/staging --stat to show what will be pushed

5. Push to Remote Staging

• Run git push origin staging to push the merged changes
• Push should succeed since we're working with a fresh staging branch

6. Return to Feature Branch

• Run git checkout <feature-branch-name> to return to the original branch
• Confirm successful merge with a summary

7. Summary Report

Provide a clear summary:

✅ Successfully merged to staging!

Branch merged: <feature-branch-name> → staging (fresh from remote)
Commits included: <number>
Files changed: <stats>

Current status:
- ✅ Local staging branch recreated from remote
- ✅ Changes merged into fresh staging branch
- ✅ Staging pushed to remote
- ✅ You're back on your feature branch

Next steps (optional):
- Monitor staging environment for any issues
- Notify team members about staging deployment
- Test the changes on staging before production

Conflict Resolution Best Practices

Ultra-Thinking Approach

When analyzing conflicts, apply deep reasoning:

1. Read Completely: Always read both file versions in full using Read tool
2. Understand Intent: Determine what each change is trying to accomplish
3. Consider Context: Look at surrounding code, imports, dependencies
4. Check History: Use git log to understand the evolution of conflicting code
5. Analyze Impact: Consider what breaks if either version is chosen
6. Think Critically: Question assumptions - is there a better third option?

Confidence Scoring Guidelines

Be rigorous with confidence scores to ensure automatic path works correctly:

• 100%: Only formatting/whitespace → Always auto-resolve
• 95%: Different parts of file modified, zero overlap → Auto-resolve with logging
• 90%: Additive changes (both add, neither deletes) → Auto-resolve with intelligent merge
• 80%: Same function modified but changes are clearly compatible → User review needed
• 70%: Related logic modified, unclear if compatible → User review needed
• <70%: Overlapping business logic, conflicting approaches → Detailed user review required

Auto-Resolution Safety

When auto-resolving (to maintain 100% automatic path):

1. Log Every Decision: Clearly state what was done and why
2. Be Conservative: If in doubt, ask the user (lower the confidence score to <90%)
3. Preserve Both Sides: When possible, merge rather than choose
4. Verify Syntax: Ensure merged code is syntactically valid
5. Document Assumptions: State any assumptions made during resolution

User Interaction Principles

To minimize interruptions while ensuring quality:

1. Only Ask When Necessary: Don't interrupt for trivial conflicts (maintain automatic path)
2. Batch Complex Conflicts: Present all complex conflicts together in one prompt
3. Provide Context: Give enough information for informed decisions
4. Offer Clear Options: Not just "what do you want?" but "here are 3 options with pros/cons"
5. Recommend Confidently: Ultra-think first, then make a strong recommendation

Common Conflict Scenarios & Resolution Guidance

Scenario 1: Different Changes to Same Function

• Analysis: Check if changes are independent or overlapping
• Recommended Action: Intelligent merge - combine both modifications
• Plan Example: "Both versions modify error handling. Recommend merging: keep new validation from feature branch + add logging from staging."

Scenario 2: One Branch Added, Other Modified

• Analysis: Determine if modification applies to the addition
• Recommended Action: Keep feature branch addition with staging modifications
• Plan Example: "Feature branch adds new function, staging modifies similar pattern. Recommend: Keep new function and apply staging's pattern improvements."

Scenario 3: Formatting/Style Conflicts

• Analysis: Verify it's only formatting, no logic changes
• Recommended Action: Keep feature branch (newer)
• Plan Example: "Only whitespace/formatting differs. Recommend: Keep feature branch version."

Scenario 4: Dependency Version Conflicts

• Analysis: Check changelog for breaking changes between versions
• Recommended Action: Use newer version with compatibility note
• Plan Example: "package.json: staging has v2.1, feature has v2.3. No breaking changes. Recommend: Keep v2.3 from feature branch."

Scenario 5: Import/Export Conflicts

• Analysis: Identify unique vs. overlapping imports
• Recommended Action: Intelligent merge - combine and deduplicate
• Plan Example: "Both add imports. Recommend: Merge both sets, remove duplicates, sort alphabetically."

Scenario 6: Configuration Changes

• Analysis: Understand business impact of each config change
• Recommended Action: Often requires manual review
• Plan Example: "Environment config differs. Staging sets timeout=30s, feature sets timeout=60s. Recommend: Manual review needed - depends on performance requirements."

Error Handling

If git fetch origin fails:

• Check network connectivity
• Verify remote URL: git remote -v
• Check if you have access to the repository

If git branch -D staging fails:

• Branch might not exist (this is fine, continue)
• Or you might be currently on staging (shouldn't happen after step 1)

If git checkout -b staging origin/staging fails:

• Check if origin/staging exists: git branch -r | grep origin/staging
• Verify remote URL: git remote -v
• Try: git fetch origin again

Important Notes

• Communicate with team: Let others know you're merging to staging
• Never force push to staging: Unless you have explicit permission
• Keep merge commits clean: Use --no-edit for automatic merge messages
• Document complex conflict resolutions: Add comments explaining decisions

Safety Checks

Before pushing to staging:

• ✅ Merge conflicts resolved
• ✅ Fresh staging branch created from remote