LogoSkills

Merge Conflict Resolution Rules

Strategy for resolving merge conflicts in stale PRs (2+ weeks).

Strategy for resolving merge conflicts in stale PRs (2+ weeks).

Strategy by File Type#

File TypeStrategyReason
Generated files (.g.dart, .freezed.dart) --theirs (base branch) Need to regenerate based on latest code
Migration files--theirs (base branch)Ensure migration order
pubspec.yaml --theirs + manual dependency addition SDK version from base, only add PR's new dependencies
BLoC events/states Individual review Verify sealed class pattern migration
Xcode project files Manual review Watch for missing framework references
Business logic Individual review Both changes need to be reflected

โš ๏ธ Parallel Fixes for the Same Root Cause โ€” Merge the Original PR First#

When [cc-dev-cycle:discovery-audit] finds multiple instances of one bug pattern and fans them out as parallel isolation: 'worktree' branches, a problem arises if the original fix PR for the root cause is still open when the derived branches are created. Once the original PR merges, the derived branches are touching a different part of the same file โ€” if each branch also added its own regression test, the merge conflicts land in the test file only (the lib code usually auto-merges).

Real case: a derived fix PR for a nested unawaited(saveToCache) call in swr_strategy_impl.dart was editing a different function in the same file already touched by the merged original fix PRs (#7746/#7748). Resolution: 

git checkout  < derived-fix-branch > 
 git merge origin/development        # lib code merges cleanly
# only the test file conflicts โ€” manually keep BOTH test cases
dart analyze  & &   melos run test:select
git add  < test-file >   & &   git commit
git push

Checklist:

  • Before starting a fix-fanout, check whether the original fix PR for the same file/function is already merged โ€” if it's still open, merge it first when possible, before branching the derived fixes
  • If derived branches already exist when the original PR merges, merge origin/development into each derived branch first and resolve the (usually test-file-only) conflicts before opening the PR

โš ๏ธ Multi-Session / Worktree Repos โ€” Resolve in an Isolated Worktree#

This repo may have multiple Claude sessions + multiple git worktrees sharing one main working tree. Running the git checkout <PR-branch> from "Conflict Resolution Order" in the main tree risks conflicts/hijacking when another session switches branches concurrently. Do conflict resolution in an isolated worktree from the start: 

git fetch origin
git worktree add ../wt- < id >   < PR-branch > 
 git -C ../wt- < id >   submodule update --init package/{coui,open_board,co_test_gen}
git -C ../wt- < id >   merge origin/development     # resolve - >   commit - >   push here
git worktree remove ../wt- < id >

Failure modes (when done in the shared main tree)#

SymptomCauseRecovery
Commit includes many unrelated files git add -A sweeps the session's untracked stray files ( .claude/docs/** , .playwright-mcp/** , screenshots) git rm --cached -r <path> the strays -> git commit --amend (kept on disk)
Merge PR shows phantom CONFLICTING as if re-implementing all of development A concurrent branch switch at git commit --amend time loses MERGE_HEAD -> single-parent snapshot commit Keep the correct tree, rebuild a 2-parent merge: git commit-tree <tree> -p <PR-base> -p <merged-dev-tip> -m ... -> force-push by SHA (fixes merge-base)
Another session's branch points at your stray commit (hijack) commit/amend in the shared main tree moves the current branch label git fetch origin <b>:refs/remotes/origin/<b> (load object) -> git reset --hard origin/<b> (unpushed work in reflog). If the harness blocks reset --hard , delegate to the user via the ! prefix

Rule: never git add -A / commit / --amend in the shared main tree. Do cross-branch merges & conflict resolution in an isolated worktree.

Conflict Resolution Order#

The order below assumes a single session. For multi-session, run the same steps inside the isolated worktree above. 

# 1. Update development branch
git checkout development  & &   git pull

# 2. Switch to PR branch
git checkout feature/issue-XXX

# 3. Merge development (conflicts occur)
git merge development

# 4. Batch handle generated files
git checkout --theirs  ' **/*.g.dart '   ' **/*.freezed.dart '   ' **/*.module.dart ' 

 # 5. Handle pubspec.yaml
git checkout --theirs  ' **/pubspec.yaml ' 
 # Then manually re-add only the dependencies added in the PR

# 6. Review business logic files individually
# git mergetool or manual resolution in editor

# 7. Re-run code generation
melos run build

# 8. Analysis and testing
melos run analyze  & &   melos run test

Tooling degradation (GD-01): melos not installed โ†’ fall back to dart run build_runner build / dart analyze / flutter test directly (command -v melos first). A missing build tool degrades with a warning, never a hard abort.

BLoC Pattern Migration Note#

When BLoC event/state patterns changed in the base branch after PR was created:

// Previous pattern (used in PR)
@freezed
class MyEvent with _$MyEvent {
  const factory MyEvent.started() = _Started;
}

// New pattern (changed in base branch)
sealed class MyEvent extends Equatable {
  const MyEvent();
  const factory MyEvent.started() = _Started;
}

In this case, PR code must be updated to match the base branch pattern.

Post-Merge Verification# 

# 1. Verify formatting
melos run format

# 2. Static analysis
melos run analyze

# 3. Verify code generation
melos run build

# 4. Tests
melos run test