Resolve Merge Conflicts from Parallel Agents
A conflict means two writers disagreed on the same lines. Resolve by understanding what each child was told, then produce one edit that satisfies both briefs — or an explicit decision to drop one.
Procedure
- Confirm the conflict is real and scoped:
git status --short --branchlists conflicted paths. - List the conflicted files concretely with
git diff --name-only --diff-filter=U. - Read both children's briefs (
notes/children/*.brief.md) before touching markers; intent tells you which side is correct. - View the markers with context:
git diff --checkand open each file's<<<<<<< ======= >>>>>>>block. - Prefer a union where both edits are additive (two new sections); keep both and reorder by dependency.
- Where both edited the same line, choose the version matching the frozen interface, and note the loser in
notes/merge-log.md. - Never leave a marker in place:
grep -rn '^<<<<<<<' .must return nothing after resolving. - Re-run each child's acceptance check after resolving, not just one, since the merge can break either.
- If the two intents genuinely conflict with no union, that is a spec problem: stop and ask the requester which behaviour wins.
- Commit the resolution with a message naming both child ids, so the provenance is recoverable.
Pitfalls
- Resolving by choosing "theirs" or "ours" wholesale, silently discarding a child's valid work.
- Deleting one side's block without recording why, so the rationale is unrecoverable.
- Declaring the merge clean because the file parses, when one child's feature was dropped.
- Re-running only the check for the side you kept, missing that the merge broke the other.
- Hand-resolving markers in a 500-line file and missing one, leaving the repo unbuildable.
Verification
grep -rn '^<<<<<<<' . ; python3 tools/validate.py --only foo
# passes when the marker grep is empty and both children's checks still pass
Report to the user: the conflicted paths, which child's change won on each axis, and the post-merge check output.