Consolidate Branches Skill

Announce at start: "I'm using the consolidate-branches skill to merge your PR branches."

Overview

This skill consolidates multiple PR branches onto a target branch using jj's multi-parent rebase with intelligent conflict resolution. The primary use case is when you have multiple feature branches with expected conflicts that need to be merged together.

Key principle: Understand the intent behind each branch's changes and intelligently combine them, not just mechanically merge.

Workflow

Phase 1: Discovery

Discover all branches that might need consolidation:

1. •Run jj git fetch to sync with remote
2. •Display branch structure:
   bash

   JJ_CONFIG= jj log -r "trunk()..@ | trunk() | @.."
   

3. •Parse the output to identify candidate branches
4. •Show branches with metadata:
   • •Branch name
   • •Number of commits
   • •Last modified date (if available)
   • •Brief description from first/last commit

Output: Present a clear list of discovered branches to the user.

Phase 2: Selection

Let the user choose what to consolidate:

1. •

   Use AskUserQuestion tool with:

   • •Multi-select question for branch selection
   • •Separate question for target branch (suggest "main" as default)
2. •

   Validate selections:

   • •At least 2 branches must be selected
   • •Target branch must exist
   • •Selected branches should differ from target
3. •

   Show confirmation summary:

   code

   Consolidating branches [branch-a, branch-b, branch-c] onto main
   

Ask: "Ready to proceed with consolidation?"

Phase 3: Analysis

Before merging, understand each branch's intent:

For each selected branch:

1. •

   Read commit messages:

   bash

   jj log -r <branch>
   

2. •

   Examine changes:

   bash

   jj diff -r <branch>
   

3. •

   Categorize the changes:

   • •What files are affected?
   • •What type of change? (feature, bugfix, refactor, docs, etc.)
   • •What is the goal of this branch?
4. •

   Document intent for later conflict resolution

Output: Create a mental model of what each branch is trying to accomplish.

Phase 4: Consolidation

Perform the multi-parent rebase:

1. •

   Create new working commit on target:

   bash

   jj new <target-branch>
   

2. •

   Multi-parent rebase to combine all branches:

   bash

   jj rebase -r @ -d <branch1> -d <branch2> -d <branch3> ...
   

3. •

   Check the result:

   • •Did the rebase succeed?
   • •Are there conflicts?

Phase 5: Intelligent Conflict Resolution

This is the core value of the skill.

When conflicts occur:

1. •

   Identify conflicting files:

   • •List all files with conflicts
   • •Categorize by severity/complexity
2. •

   For each conflicting file:

   a. Show conflict context:

   • •Display the conflicting sections from each branch
   • •Show surrounding code for context

   b. Analyze intent:

   • •What was each branch trying to accomplish in this file?
   • •Are the changes complementary or contradictory?
   • •Can both goals be achieved simultaneously?

   c. Propose resolution:

   • •Draft a merge that preserves both/all intents
   • •Explain the reasoning behind the resolution
   • •If intents are contradictory, explain the trade-offs and recommend the best approach

   d. Apply resolution:

   • •Edit the file to implement the proposed merge
   • •Remove conflict markers
   • •Ensure code is syntactically correct

   e. Document resolution:

   • •Track what conflict was resolved
   • •Record why this resolution was chosen
   • •Note any assumptions made
3. •

   Present resolutions to user:

   • •Summarize all conflicts found
   • •Explain how each was resolved
   • •Show the reasoning behind decisions
   • •Ask for validation: "Do these conflict resolutions look correct?"
4. •

   Iterate if needed:

   • •If user requests changes, revise resolutions
   • •Re-apply and re-validate

Key Guidelines:

• •Don't just pick one side arbitrarily
• •Look for ways to combine both changes
• •Preserve functionality from all branches
• •Maintain code quality and consistency
• •When uncertain, explain options to user

Phase 6: Verification

Verify all changes from all branches are present:

1. •

   Code presence check for each branch:

   bash

   jj diff -r <branch>
   

   • •Compare against final consolidated result
   • •Verify the changes are present
   • •Report any missing changes
2. •

   Generate summary report:

   • •List all branches consolidated
   • •Show total number of commits included
   • •List conflicts resolved with explanations
   • •Display final diff of consolidated changes:
     bash

     jj diff -r <target-branch>..@
     

3. •

   Sanity checks:

   • •Are there any remaining conflict markers?
   • •Does the code appear syntactically correct?
   • •Are imports/dependencies resolved?

Phase 7: Completion

Leave the workspace ready for user review:

1. •

   Summary message:

   code

   Branch consolidation complete!
   
   Consolidated branches: [list]
   Total commits: [count]
   Conflicts resolved: [count]
   
   The changes are ready for your review.
   

2. •

   Next steps guidance:

   • •"Review the changes with jj diff"
   • •"When satisfied, you can:"
     • •"Create a commit with jj commit -m 'your message'"
     • •"Create a PR"
     • •"Make further edits"
   • •"The workspace is ready for your action"
3. •

   Don't auto-commit: User maintains full control

Error Handling

If fetch fails

• •Report the error
• •Ask if user wants to continue without fetching
• •Explain risks of stale branch info

If no branches found

• •Report that no branches were found
• •Suggest checking if branches are pushed to remote
• •Offer to show current branch status

If multi-parent rebase fails

• •Report the specific error
• •Check if it's due to conflicts or other issues
• •Guide user through resolution

If conflicts seem irresolvable

• •Explain why the conflict is challenging
• •Present the conflicting code from each branch
• •Ask user for guidance on resolution strategy
• •Offer to abort if user prefers manual merge

Key Principles

1. •Understanding over mechanics: Always analyze intent before merging
2. •Preserve all functionality: Don't drop changes from any branch
3. •Clear communication: Explain what you're doing and why
4. •User control: Present resolutions for validation, don't auto-commit
5. •Safety first: Verify changes, check for missing code
6. •Helpful guidance: Provide clear next steps

Success Criteria

The consolidation is successful if:

• •All selected branches are merged
• •All conflicts are intelligently resolved
• •All changes from all branches are present
• •Code is syntactically correct
• •User understands what was done and why
• •Workspace is clean and ready for review