Purpose

Resolve common merge conflicts encountered when merging feature branches into merge-queue.

When To Use

•Git merge fails in merge-queue worktree
•Conflicts in observations.jsonl, uv.lock, pyproject.toml, or egg-info files
•Multiple branches queued for merging

Common Conflicts & Solutions

1. observations.jsonl (Autolearn Memory)

Symptom: "Your local changes to .opencode/memory/observations.jsonl would be overwritten" Cause: Autolearn continuously appends observations, creating drift vs feature branch Solution:

•Sync from branch: git show <branch>:.opencode/memory/observations.jsonl > .opencode/memory/observations.jsonl
•Commit changes: git add .opencode/memory/observations.jsonl && git commit -m "chore: sync observations" --no-verify
•Proceed with merge

Alternative: Add to .gitignore: ".opencode/memory/observations.jsonl"

2. uv.lock (Dependency Lock)

Symptom: "missing source field but has more than one matching package" or TOML parse error Cause: Lock file corruption from repeated merges across branches Solution:

•Remove corrupted lock: rm uv.lock
•Regenerate: uv lock
•Commit: git add uv.lock && git commit

Prevention: After each merge, run uv lock to ensure clean state

3. pyproject.toml (Dependency Conflicts)

Symptom: Merge conflict markers in dependencies section Cause: Different branches added overlapping or conflicting dependencies Solution:

•Manually edit pyproject.toml to merge all dependencies
•Accept all versions from both branches
•Example: Combine scipy, scikit-learn, matplotlib (HEAD) with fastapi, uvicorn, python-jose (branch)
•Re-generate lock: uv lock
•Commit resolved file

4. src/vibe_piper/init.py (Export List)

Symptom: Conflict in all showing duplicate feature sets Cause: Both HEAD and branch export different feature modules Solution:

•Accept BOTH sets of exports
•Merge lists to include all: External quality (HEAD) + Schema evolution (branch)
•Ensure no duplicates, maintain alphabetical grouping
•Verify all imports exist at bottom of file

5. src/vibe_piper.egg-info/* (Metadata)

Symptom: Conflict in PKG-INFO, requires.txt, SOURCES.txt Cause: Auto-generated package metadata Solution:

•Do NOT add to commit (in .gitignore)
•Accept --theirs or skip entirely
•Regenerated automatically on: uv sync, uv pip install -e .

6. .gitignore (Ignore Rules)

Symptom: Conflict on observation egg entries Cause: Both branches added different ignore patterns Solution:

•Combine patterns from both
•Example: .egg-info/ AND .opencode/memory/observations.jsonl
•Maintain both to avoid future conflicts

Procedure for Blocked Merges

Step 1: Identify Conflict Type

code

git status
git diff --name-status HEAD <branch>

Step 2: Resolve by Pattern

•observations.jsonl → Sync from branch and commit
•uv.lock → Delete and regenerate
•pyproject.toml → Manually merge dependencies
•init.py → Combine export lists
•egg-info/* → Skip (ignore)
•.gitignore → Merge patterns

Step 3: Verify Resolution

code

# Check merge succeeded
git status

# Verify no conflict markers
grep -r '<<<<<< HEAD' .

# Regenerate lock if needed
uv lock

Step 4: Commit Merge

bash

git add <resolved-files>
git commit -m "Merge <branch> into merge-queue (ticket: <ticket>)" --no-verify

Step 5: Mark Complete

bash

loom team merge <TEAM> done <ITEM_ID> --result merged --note "..."

Best Practices

•Always use --no-verify for commits in merge-queue (skips hooks)
•Commit observations.jsonl before attempting merges
•Regenerate uv.lock after pyproject.toml changes
•Test with uv sync after resolving dependency conflicts
•Document conflict resolution in done notes for future reference

Manual notes

This section is preserved when the skill is updated. Put human notes, caveats, and exceptions here.