Skip to content

Existing merge or conflict recovery

Explain an unmerged entry such as UU as "This local file still contains an unresolved merge conflict, so I cannot safely switch this working copy to the PR version yet." Keep it separate from a failed remote fetch: resolving the conflict does not prove the fetch will succeed. Do not claim a pull caused the conflict or that the merge belongs to this task without evidence.

Inspect unmerged paths and read-only operation state, including MERGE_HEAD when present, current HEAD, and available pre-merge evidence. UU alone does not establish that a merge is still in progress; determine whether this is a merge, another Git operation, or unresolved index state before proposing a command. Identify intended changes and pre-existing changes to preserve. Do not treat unrelated dirty files as a checkout blocker or tell the user only to "resolve or abort in your own workflow".

A merge in progress is task-owned only when this remediation run's own merge-resolution.json records status=in-progress for it, its recorded pre_merge_head equals current HEAD, its recorded target_oid equals MERGE_HEAD, and the attached branch matches this run's checkout receipt. Matching branch or target identities without that record are not task-owned: a merge the user started toward the same target, or a checkout already conflicted before this run started a merge, needs the decision below. When this evidence proves the same task-owned merge and its resolution intent is unambiguous, automatically finish the task-owned merge under the authorization recorded when it started, including its checked local commit, without a question; preserve unrelated work and any explicit denial or no-commit instruction. Otherwise give an evidence-backed recommendation and one concrete choice among the applicable options; omit unsupported options and explain missing evidence:

  • Finish the existing merge: describe the identified merge, affected files, intended resolution, verification, and any local commit. Offer agent-owned resolution when the merge's purpose and ownership are known; reuse the recorded authorization for the same task-owned merge; obtain only genuinely missing authorization for unrelated scope or resolution intent.
  • Abort the existing merge: offer only when an active merge is verified and the user wants to cancel it. Explain that abort attempts to return to the pre-merge state, can discard conflict-resolution work, and may not restore pre-existing changes exactly. Establish a preservation plan and obtain explicit authorization before aborting; never promise lossless recovery or abort automatically.
  • Defer: preserve current work and continue permitted diagnosis or user-accepted report discussion; PR code edits remain paused. State the exact missing evidence or decision if neither finish nor abort can yet be proposed safely.

Only when the recommended action lacks recorded authorization, after showing its concrete scope and effects, ask only the matching question through User Questions: Authorize finishing this existing merge and the described local commit? when a commit is needed, Authorize resolving these existing conflicts without committing? when no commit is proposed, or Authorize aborting this existing merge with the stated preservation plan?. Pass Approve and Deny as separate canonical options to the selected permitted native control. An Approve authorizes only the described action; a Deny selects Defer, preserves current state, and permits only the stated unaffected work. Do not ask all questions in succession or reprompt an action already authorized.

When verification identifies a repair outside the authorized scope, finish the permitted diagnosis and show the concrete proposed repair, affected paths, evidence, checks, and effect of declining. Ask only for the missing scope expansion through User Questions with separate canonical options Approve and Deny. Generated repair questions follow the same native routing as the merge question; do not append a keyed slash-separated authorization menu to the status message. Keep dependent repair or commit work pending until an explicit bound answer arrives, and reuse any previously granted commit authorization.

Resolving files while a merge remains in progress is partial recovery, not a completed merge. Continue to its first unmet checkpoint: if the required commit was not authorized, ask for that specific commit decision and explain that finding edits remain paused; if already authorized, complete and verify it. No-commit authorization never implies commit permission or satisfies merge-resolution.json.status=completed.

Once an authorized recovery succeeds, resume the active code-remediate workflow from its first unmet checkpoint under existing authorization. Preserve the resolved work and revalidate affected source and operation-state evidence; recollect missing or stale PR evidence and verify the current PR head when required by that checkpoint. For an already-authorized target integration, preserve and verify its recorded merge result rather than replacing it with the unmerged PR head. Continue the normal merge-prestage, findings-selection, implementation, and completion gates as applicable; do not stop at conflict resolution or ask the user to rerun the skill. A merge repaired by the user is a resume checkpoint, not proof that earlier fetch or source-validation failures are resolved. If an independent blocker remains, diagnose and explain only that unmet condition and its next action.

Retain local-checkout.json and after-checkout worktree-preflight.json as pre-merge source receipts. merge-resolution.json.pre_merge_head must match the collected PR head and its target_oid the captured target; a completed authorized integration's post_merge_head/merge_commit records the starting revision for finding edits. Verify current HEAD against that recorded revision before resuming, preserving subsequent authorized finding changes and their closure-log evidence. Never rewrite the pre-merge receipt to pretend the merged commit was the PR head, or recollect by replacing an authorized merge merely to satisfy a source-receipt check.