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.

Decision Rubric

Use this rubric when conflict choices are ambiguous.

Terminology: "target branch" means the branch you are rebasing onto or merging into (often main).

Signals and default actions

Evidence hierarchy

Prefer stronger evidence first:

1. Passing tests tied to changed behavior 2. Explicit PR review/sign-off discussion 3. Recent commits with clear intent in message/diff 4. Local code comments and naming intent 5. Temporal recency alone (weakest; never sole justification)

Confidence scoring guidance

• High: strong evidence and behavior validated
• Medium: partial evidence; low ambiguity remains
• Low: unresolved ambiguity, missing validation, or unclear ownership

If confidence is Low, ask explicit human approval before finalizing.

Quality Gates

Run checks before each commit-producing continuation step and run full checks again after reconciliation.

Command discovery and precedence

JavaScript / TypeScript (package.json)

Determine package manager from lockfiles when possible:

• pnpm-lock.yaml → pnpm run
• yarn.lock → yarn run
• package-lock.json → npm run
• bun.lockb → bun run

Read scripts and run in this order when available:

1. typecheck (or type-check) 2. lint 3. test (or targeted test command for changed scope) 4. build 5. format:check (or formatter verification command)

If no scripts exist, report that gap explicitly.

Python (pyproject.toml, tox.ini, noxfile.py)

Run configured project commands in this order when available:

1. format/lint checks 2. type checks 3. tests 4. build/package checks

Rust (Cargo.toml)

Run when applicable:

1. cargo fmt --check 2. cargo clippy 3. cargo test 4. cargo build

Go (go.mod)

Run when applicable:

1. gofmt -l . (expect no output) 2. go vet ./... 3. go test ./... 4. go build ./...

Swift / Apple platforms (Xcode/SwiftPM)

Use configured project workflows for format/lint/type/test/build.

Reporting rules

For each command, report:

• command run
• pass/fail result
• whether it was full or targeted

Never claim success for commands not run.