Worktree Merge

Merge parallel worktrees into unified branch after parallel implementation.

<ARH_INTEGRATION> This skill uses Adaptive Response Handler pattern for conflict resolution:

• RESEARCH_REQUEST ("research", "check", "verify") -> Dispatch subagent to analyze git history
• UNKNOWN ("don't know", "not sure") -> Dispatch analysis subagent to show context
• CLARIFICATION (ends with ?) -> Answer, then re-ask original question
• SKIP ("skip", "move on") -> Mark as manual resolution needed </ARH_INTEGRATION>

You MUST:

1. ALWAYS perform 3-way analysis - no exceptions, no shortcuts
2. Respect interface contracts - parallel work was built against explicit contracts
3. Document reasoning - every resolution decision must be justified
4. Verify everything - tests are mandatory after each round

Skipping steps = lost features. Rushing = broken integrations. Undocumented decisions = confusion. </CRITICAL>

Invariant Principles

1. Interface contracts are law - Parallel work built against explicit contracts. Violations block merge.
2. 3-way analysis mandatory - Base vs ours vs theirs. No blind ours/theirs acceptance.
3. Test after each round - Catch integration failures immediately. No "test at end" batching.
4. Dependency order prevents cascading conflicts - Merge foundations first.
5. Document every decision - Reasoning trail for each conflict resolution.

Pre-Conflict Gate

When dispatching a conflict resolution subagent:

1. The subagent prompt MUST instruct it to invoke resolving-merge-conflicts via the Skill tool
2. The subagent prompt MUST include interface contract context from the implementation plan
3. Do NOT resolve conflicts inline in the orchestrator context

If you catch yourself resolving a conflict without having loaded the skill: STOP. Dispatch a subagent that loads it. </CRITICAL>

Inputs/Outputs

Pre-Flight

If NO to any: STOP and address before proceeding.

Workflow

Phase 1: Merge Order

Build dependency graph:

Create merge plan:

## Merge Order
### Round 1 (no dependencies)
- [ ] setup-worktree -> base-branch

### Round 2 (depends on Round 1)
- [ ] api-worktree -> base-branch (parallel)
- [ ] ui-worktree -> base-branch (parallel)

### Round 3 (depends on Round 2)
- [ ] integration-worktree -> base-branch

<RULE>ALWAYS create checklist via TodoWrite before starting merge operations.</RULE>

Phase 2: Sequential Round Merging

Dispatch: /merge-worktree-execute

Phase 3: Conflict Resolution

Dispatch: /merge-worktree-resolve

Phases 4-5: Final Verification + Cleanup

Dispatch: /merge-worktree-verify

Conflict Synthesis Patterns

Error Handling

Rollback Procedure

If merge goes wrong after commit:

# Identify pre-merge commit
git log --oneline -5

# Reset to before merge (preserve working tree)
git reset --soft HEAD~1

# Or hard reset if working tree also corrupted
git reset --hard [pre-merge-commit-sha]

# Re-attempt with lessons learned

Self-Check

<RULE>Before completing worktree merge, verify ALL items. If ANY unchecked: STOP and fix.</RULE>

• Merged worktrees in dependency order?
• Ran tests after EACH round?
• Performed 3-way analysis for ALL conflicts?
• Verified interface contracts are honored?
• Ran auditing-green-mirage on tests?
• Ran code review on final result?
• Deleted all worktrees after success?
• All tests passing?

Success Criteria

• All worktrees merged into base branch
• All interface contracts verified
• All tests passing
• Code review passes
• All worktrees cleaned up
• Single unified branch ready for next steps

<FINAL_EMPHASIS> Your reputation depends on merging parallel work without losing features or introducing bugs. Every conflict requires 3-way analysis. Every round requires testing. Every merge requires verification. Interface contracts are mandatory, not suggestions. No feature left behind. No bug introduced. You'd better be sure. </FINAL_EMPHASIS>