reconcile-merge-conflicts

Resolve merge and rebase conflicts by preserving intent from both sides while preventing regressions.

Safety rules:

• Allow local git edits needed for reconciliation.
• Allow remote read-only git/GitHub operations (fetch, logs, PR metadata reads).
• Never run git push.
• Never run any git reset variant.

Step 1: Detect operation state and workspace safety

Run:

git status --porcelain=v1 -b
git status

Classify state:

• Active conflict state: unmerged paths exist, or git reports in-progress merge/rebase.
• No active conflict state: no unmerged paths and no in-progress operation.

If git is unavailable or the directory is not a git repo, stop and report the failure.

If no operation is active and the working tree is dirty, stop and ask user to:

1. Commit current work, or
2. Stash current work, or
3. Clean branch manually.

Do not start merge/rebase on a dirty tree.

If an operation is already active, optionally create an in-progress safety bookmark (with user confirmation):

git branch backup/conflict-reconcile/inprogress/$(git rev-parse --short HEAD)

Step 2: If no active conflict state, ask what to start

Ask user whether to:

• rebase onto branch (example: rebase main)
• merge branch (example: merge main)

Confirm current branch and intended direction first:

git branch --show-current

If current branch is not the intended source branch, stop and ask user to switch.

Before starting, create rollback branch:

git branch backup/conflict-reconcile/$(date +%Y%m%d-%H%M%S)-$(git rev-parse --short HEAD)

Tell user the backup branch name and recovery command:

git switch <backup-branch-name>

If backup branch name already exists, append a unique suffix and retry.

List all skill-created backups with:

git branch --list 'backup/conflict-reconcile/*'

Determine remote first (prefer origin if present, otherwise use the remote user specifies):

git remote

If user says rebase onto target branch, prefer up-to-date remote-tracking ref and capture evidence first:

git fetch <remote> <target-branch>
git rev-parse --short HEAD
git rev-parse --short <remote>/<target-branch>
git rebase <remote>/<target-branch>

Confirm target branch exists remotely before running. If git rev-parse --short <remote>/<target-branch> fails, stop and ask user to confirm the correct target branch name/remote.

Rebasing rewrites history. If branch is pushed/shared, ask for explicit confirmation before rebasing.

If user asks to merge target branch, prefer up-to-date remote-tracking ref and capture evidence first:

git fetch <remote> <target-branch>
git rev-parse --short HEAD
git rev-parse --short <remote>/<target-branch>
git merge <remote>/<target-branch>

Confirm target branch exists remotely before running. If user explicitly wants a local ref, follow user instruction.

Step 3: Build conflict context before editing

Run:

git diff --name-only --diff-filter=U
git log --oneline --decorate --max-count=30

For each conflicted file, inspect both sides, merge-base version, recent commits, and related PR discussion when available.

Useful commands:

# stage 1 (base), stage 2 (ours), stage 3 (theirs)
git show :1:<path>
git show :2:<path>
git show :3:<path>

Use temporal signals as evidence, not proof.

Read <skill-dir>/references/decision-rubric.md for ambiguous choices.

Step 4: Reconcile conflicts file-by-file

Default strategy:

1. Treat both sides as important.
2. Treat the target branch (often main) as canonical for current behavior.
3. Recreate source-branch intent on top of target-branch structure.
4. Avoid blind "take ours" / "take theirs" unless evidence is strong.

Prefer clean rewrites over marker patching when clearer or safer.

If source-side logic is obsolete, remove it and state evidence.

After each file resolution:

git add <file>

Continue operation:

• git rebase --continue
• for merges: git commit --no-edit (or git merge --continue when supported)

Repeat until no conflicts remain.

Before each continue/commit, verify no leftover conflict markers:

git diff --check
git grep -n '<<<<<<<\|>>>>>>>\|=======' -- .

Step 5: Run quality gates before commit-producing steps and at end

Before each commit-producing continuation step (especially git rebase --continue), run fast high-signal checks. If checks fail, stop and fix.

After all conflicts are resolved, run the full quality gate set.

Read <skill-dir>/references/quality-gates.md for command discovery and precedence.

Never claim checks passed unless actually run.

Step 6: Human review and rollback policy

Default to end-of-operation review:

1. complete reconciliation
2. run full quality gates
3. present final diff and audit report

Request mid-operation review only for high-risk areas or low confidence.

If any Low-confidence decision remains, require explicit human approval before finalizing.

Rollback options:

• active rebase: git rebase --abort
• active merge: git merge --abort (when available)
• post-operation: recover via backup branch from Step 2

Do not run destructive rollback commands automatically.

Step 7: Produce reconciliation audit report

Include:

1. Summary (operation, target branch, files reconciled)
2. Per-file decisions (final structure side, preserved intent, rationale, regression risk)
3. Confidence-ranked decisions (High/Medium/Low)
4. Risks and follow-up checks
5. Open questions by change
6. Consolidated open-question list (repeat all questions)
7. Audit evidence block with:
   • command run
   • timestamp
   • resolved target commit hash
   • confidence level
   • attribution caveat

The target commit hash must come from explicit remote-tracking ref resolution (for example git rev-parse <remote>/<target-branch>), not from FETCH_HEAD.

Attribution rule:

• Reflog proves operation sequence and repo state transitions.
• Reflog does not prove actor identity. Do not claim it does.

Output example

## Reconciliation Audit

### Summary
- Operation: rebase onto `main`
- Conflicted files: 3
- Status: rebase completed

### Confidence-ranked decisions
- High — `src/core/parser.ts`: Kept new validation flow from main and reapplied source telemetry hook.
- Medium — `src/ui/filters.tsx`: Rewrote filter composition to preserve both behaviors.
- Low — `src/legacy/adapter.ts`: Removed source fallback path; needs owner confirmation.

### Audit evidence
- Command: `git rebase origin/main`
- Timestamp (UTC): `2026-03-02T11:15:34Z`
- Target hash: `13eeb846`
- Confidence: High
- Attribution caveat: reflog confirms operation sequence, not actor identity

### Open questions (consolidated)
1. Should legacy empty-state behavior remain for anonymous users?
2. Is external consumer `X` still relying on removed fallback behavior?

Validation and exit criteria

Complete only when all are true:

• No conflicted files remain.
• Operation is complete or paused with clear next command.
• Preserved intent from both sides where applicable.
• Discarded logic has explicit evidence.
• Quality gates ran before commit-producing steps and after reconciliation, or gaps were reported.
• End-of-operation review was requested unless user opted out.
• If any Low-confidence decisions exist, explicit human approval was requested.
• Rollback path was communicated without git reset.
• No git push or git reset command was run.