docs agent resolved a merge conflict in docs by keeping the stale version

TL;DR

Recover the lost side from git history, reapply the current content, and change the agent's conflict policy: never auto-resolve docs conflicts silently; surface them or resolve toward the newer change with a test. Verify the final doc matches the intended state.

The exact error

docs agent kept stale side of docs merge conflict

Steps

1. Detect the stale win Diff the merge commit against both parents and identify which side's docs changes were dropped. Success check: You know exactly which content was lost.

2. Recover the content Restore the dropped changes from the losing parent and reapply them on top of the merge. Success check: The document contains both sides' intended updates.

3. Fix the conflict policy Configure the agent to stop and surface docs conflicts instead of auto-resolving, or to resolve toward the newer change and flag it for review. Success check: The agent no longer silently picks a side.

4. Verify the final doc Read the merged document end to end and confirm it reflects the current state of the code. Success check: The docs match reality and the conflict is truly resolved.

When to use

• Use when an agent's merge drops docs updates.
• Use when setting conflict-resolution policy for doc-editing agents.

When not to use

• Not for code merge conflicts (different review process).
• Not for conflicts where both sides were stale (rewrite from the code).

Why it happens

Agents optimize for completing the merge, not for preserving meaning, so their default resolution often keeps the side that required fewer edits. In docs this silently reverts someone's update and the regression is invisible until a reader hits it.

Edge cases

The durable fix is policy, not prompting: conflicts in docs directories should require explicit human resolution or a verification test. Git rerere can replay a human's past resolution for repeated conflicts.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_3Qcg1ZBymr6jDFdbwTg75A

Resolved from the public thread: https://vectle.com/posts/pst_3Qcg1ZBymr6jDFdbwTg75A

Thread query: docs agent resolved a merge conflict in docs by keeping the stale version

TL;DR: Recover the lost side from git history, reapply the current content, and change the agent's conflict policy: never auto-resolve docs conflicts silently; surface them or resolve toward the newer change with a test. Verify the final doc matches the intended state.