flow-merge-resolver-instructions

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- flow-instructions-sentinel: flow-merge-resolver-instructions -->

# Merge-conflict resolver instructions

These instructions are read by the merge-conflict resolver subagent that
`/flow-pipeline`'s SKILL.md spawns via the Task tool when step 10's
`flow-merge-guard merge` returns a conflict-class failure. The subagent runs
in an isolated context — its file reads, per-file resolution rationale,
merge output, and the push prose stay inside its own session and are
never returned to the supervisor. The only outputs it produces are the
side effects on the worktree (file edits, the merged branch, the
push) and the structured artifact it writes to disk
(`.flow-tmp/merge-resolver-result.json`), plus a brief one-paragraph
summary it returns on completion.

The wrapper passes you these inputs in its spawn prompt:

- The verbatim `.stderr` of the failed `flow-merge-guard merge` result (the
  `gh pr merge --squash` it ran; so you can confirm the conflict class the wrapper detected).
- The PR number.
- The base branch name (typically `main`, but read from the wrapper's
  prompt — the supervisor resolved it from `gh pr view`).
- The list of conflicting file paths (from `git status --porcelain` on
  the worktree, post-merge-attempt — the supervisor may have already
  initiated `git merge`).
- The absolute worktree path (your working directory).
- The absolute path to `.flow-tmp/plan.md` (so you understand the PR's
  intent when judging conflict semantics).
- The PR description (so you understand the user-facing scope and key
  decisions).
- The absolute path to write the artifact (`ARTIFACT_PATH` —
  `.flow-tmp/merge-resolver-result.json` under the worktree).

Follow the steps below in order.

## 1. Load context

Before touching any conflict, load the inputs:

- Read the wrapper's spawn prompt for the `gh` stderr, PR number, base
  branch, conflicting file list. The stderr fingerprint matters: the
  wrapper detected one of the conflict-class patterns (see step 2's
  Detection patterns table); your own `git merge` output should match.
  If it does not — e.g. the wrapper saw "Pull Request is not mergeable"
  but your local `git merge origin/<base>` completes cleanly — the
  divergence is itself a signal (likely required-checks rather than
  textual conflict). Record this in `rejected_strategies` and proceed
  to Step 8 with `push_status: skipped`.
- Read `.flow-tmp/plan.md` and the PR description. Skim for the PR's
  intent — what the change is meant to accomplish — so semantic
  conflicts can be resolved against intent rather than textual proximity.
- Read `git log origin/<base>..HEAD --oneline` and
  `git log HEAD..origin/<base> --oneline` to see what each side has
  diverged. Cap each at 50 lines; if either side has more, summarize the
  pattern rather than enumerating.

This is read-only background — these reads stay in your context.

## 2. Verify the merge state and re-attempt if needed

The wrapper may have initiated `git merge origin/<base>` before
spawning you, leaving the worktree in mid-merge state. Run:

```bash
git status --porcelain
git rev-parse --show-toplevel  # confirm you're in the worktree
test -f "$(git rev-parse --git-path MERGE_HEAD)" && echo "merge in progress"
```

The `MERGE_HEAD` probe (not a `.git/rebase-*` directory check) is
required because in a flow worktree `.git` is a FILE pointing at
`.git/worktrees/<name>/`, not a directory. `git rev-parse --git-path
MERGE_HEAD` resolves into that per-worktree gitdir correctly; a
hardcoded `test -d .git/rebase-merge` would never fire in a worktree.

Two cases:

- **Merge in progress** (`MERGE_HEAD` exists): keep going from the
  current state. Do not run `git merge --abort` unless explicitly
  recovering from a broken state — see the Troubleshooting table below.
- **No merge in progress**: run

  ```bash
  git fetch origin "$BASE_BRANCH"
  git merge --no-edit "origin/$BASE_BRANCH"
  ```

  Capture stderr. If the merge completes without conflicts, the
  wrapper's conflict-detection was a false positive — write
  `push_status: skipped`, populate `rejected_strategies` with
  the divergence, and skip to Step 8.

### Detection patterns

The wrapper triggers the resolver when `flow-merge-guard merge` reports
`failureClass: conflict` for a `gh pr merge --squash` stderr that matches any of these fingerprints. If your local merge output also
matches, you're aligned with what the wrapper saw:

- `Pull Request is not mergeable`
- `not mergeable: the merge commit cannot be cleanly created`
- `merge conflict between`
- `CONFLICT (` (from `git merge` output — multiple variants:
  `CONFLICT (content)`, `CONFLICT (modify/delete)`, `CONFLICT (rename/rename)`)

If your local merge produces a stderr that matches NONE of these AND
no `<<<<<<<` markers exist in the worktree, the wrapper's classification
was wrong. Document this in `rejected_strategies` and exit per the
no-conflict path above.

## 3. Resolve each conflicted file

### Conflict-marker orientation (merge, not rebase)

Under `git merge origin/<base>` run FROM the pipeline branch,
`<<<<<<< HEAD` / `ours` is **THIS PR's version** and
`>>>>>>> origin/<base>` / `theirs` is **THE BASE's version** — the exact
INVERSE of a rebase, where the replayed commit is `theirs`. So
`prefer-current` takes the `HEAD` side and `prefer-incoming` takes the
`origin/<base>` side; `git checkout --ours` / `--theirs` mean the

From gavingolden/flow, MIT.

More from gavingolden/flow