# Resolving Rollback Conflicts > Replay a list of git-revert commits against the current base branch and resolve the conflicts, when the chat-service's automatic rollback hit a merge conflict it couldn't resolve. Load this when your developer dispatch asks you to resolve a rollback conflict (it carries BASE_BRANCH, FAILED_COMMIT, COMMITS_TO_REVERT). This is NOT a feature ticket — the workflow below replaces the normal ticket rules. - Skill: `marmelab/resolving-rollback-conflicts` (Agent Skill) - Install (CLI): `npx skillmds@latest add marmelab/resolving-rollback-conflicts` - Raw SKILL.md: https://api.skillmd.com/api/skills/marmelab/resolving-rollback-conflicts/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Productivity - Author: marmelab (https://skillmd.com/u/marmelab) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/marmelab/resolving-rollback-conflicts --- # Resolving rollback conflicts The chat-service's HTTP `/rollback` route attempted to `git revert -m 1 ` each merge commit on the base branch, and one of them conflicted. It aborted that revert and handed you the failed commit plus every commit it still had left to undo. Your job: replay them **against the current base branch**, resolving conflicts as you go. You are dispatched **alone** — no team, no peers. The merger is dispatched separately by the orchestrator after you stop. The conflict exists because a _later_ session edited the same lines this rollback wants to undo. That conflict only shows up against the current base branch — not against the stale `session/` your worktree was forked from. So your **first** step realigns your branch onto `BASE_BRANCH`; then the revert reproduces the real conflict for you to resolve, and the merger's promotion fast-forwards cleanly afterward. ## Spawn prompt — what you receive ``` ROLE: developer WORKTREE_PATH: /simple BRANCH_NAME: /simple BASE_BRANCH: FAILED_COMMIT: ("") COMMITS_TO_REVERT: - # - ... ``` **Working directory is ``** — the shared `/simple` worktree the `setup-worktree` hook creates for you. Every Bash call must `cd && …` (shell state is stateless between calls). Do NOT touch `$CLAUDE_PROJECT_DIR/src/...` — that's the base branch. ## Output contract Your very last line of output MUST be exactly one of: - `DONE: branch=/simple files=[]` - `FAILED: ` The orchestrator's STATE RB-MERGE relies on those literal prefixes. ## Workflow ### Step 0 — Realign your branch onto the base branch (do this ONCE, first) Your worktree was forked from the stale `session/`, where the conflicting later changes don't exist — revert there and it applies cleanly but the conflict resurfaces, unresolved, at promotion. Reset your branch onto the current base branch so you replay the reverts against the exact state the HTTP route hit the conflict on: ```bash cd && git reset --hard ``` This is the only branch-moving command you may run, and only here. After it, proceed to the loop below. Then, for each SHA in `COMMITS_TO_REVERT`, in the order given: ### Step 1 — Read the commit you're about to undo Before touching anything, get the canonical record of what this commit changed. This is the **ground truth** you'll use to resolve conflicts and to interpret empty reverts: ```bash cd && git show --stat # which files, how big cd && git show # full diff ``` Read the diff. Identify, in your head, **exactly** what this commit added (the `+` lines on the "after" side) and what it replaced (the `-` lines). The revert's job is to remove the `+` and put back the `-` — nothing else. ### Step 2 — Attempt the revert ```bash cd && git revert --no-edit -m 1 ``` Three possible outcomes — match yours below. ### Outcome A — Clean revert with real changes `git revert` exited 0 AND `git diff --name-only HEAD^ HEAD` is non-empty. Sanity-check: do the changed files / changed lines match what Step 1 told you to expect? If yes, go to next SHA. ### Outcome B — Empty revert (clean exit, zero changes) `git revert` exited 0 BUT `git diff --name-only HEAD^ HEAD` is empty. This means a later commit on the base branch has **already removed or transformed** the lines your target commit added. Two sub-cases: - **B1 — Pure substitution** (e.g. target said `X → Y`, current main says `Z`): the user's intent — "undo X → Y" — can sometimes still be expressed as `Z → X`. Look at Step 1's `+` strings; grep current main for them; if they're absent but the file at the same location now has a different value, that's the later commit's overwrite. Edit the file to replace that later value with the original `-` strings from Step 1. Then commit **with the revert marker** so a future rollback knows this commit was already undone: ```bash cd && git add -A && git commit -m "revert: semantic revert of " -m "This reverts commit ." ``` The second `-m` line is mandatory: the chat-service detects already-reverted commits by scanning for `This reverts commit `. Native `git revert` / `git revert --continue` write this marker automatically; a manual semantic revert must add it explicitly or the commit will be re-reverted on the next rollback. Re-check with `git diff --name-only HEAD^ HEAD` — it should be non-empty now. - **B2 — Target already fully absent** (the later commit removed the addition entirely, no equivalent value to swap): the target commit's effect is already gone from main. Nothing to revert. ```bash cd && git reset --hard HEAD^ ``` ``` FAILED: revert of produced no changes — its additions have already been removed by a later commit ``` If you're unsure which sub-case applies, prefer B2 (FAILED) — a confusing-but-honest failure is better than a hallucinated edit that touches files the user didn't expect. ### Outcome C — Conflict (non-zero exit, unmerged paths) `git status` shows `You are currently reverting commit ` plus `UU`/`AA`/`DU`/`UD` entries. ```bash cd && git status --porcelain cd && git diff --diff-filter=U ``` For each conflict file, the markers look like: ``` <<<<<<< HEAD ======= >>>>>>> parent of ... ``` **Goal**: produce a version where the target commit's `+` lines (from Step 1) are removed, but **every** later commit's contribution that you can identify is preserved. Heuristic, in order: 1. **Read both sides side-by-side**. Identify which lines come from the target commit's `+` (look at Step 1's diff) and which come from later commits. 2. **Keep**: everything on the "HEAD" side that does NOT correspond to one of the target commit's `+` lines. 3. **Drop**: the target commit's `+` lines (and only those). 4. If the target commit added a whole new function/file/component that's now referenced elsewhere, you'll need to also remove those references — but only the references that exist _because_ of the target commit. The `SubagentStop` hooks (typecheck, unit tests, e2e) run after you stop; if they fail with `Cannot find name 'X'` for some `X` that the target commit introduced, that's your signal to remove the reference. If they fail for something the target commit DIDN'T introduce, you went too far — revert your last edit. After resolving every conflict file: ```bash cd && git add -A && git revert --continue --no-edit ``` Then re-check `git diff --name-only HEAD^ HEAD`. If empty, apply the Outcome B logic. Otherwise, go to next SHA. ### Step 3 — All SHAs processed Emit the output contract: ``` DONE: branch=/simple files=[] ``` The orchestrator's STATE RB-MERGE will dispatch the single-shot merger to merge your branch back into the base. ### Step 4 — Unrecoverable failure If at any point you can't make progress (a conflict you genuinely can't read, three rounds of validation hook failures with no fix in sight, etc.): ```bash cd && git revert --abort 2>/dev/null || true ``` ``` FAILED: rollback merge failed: ``` ## NEVER while resolving a rollback conflict - ❌ Run `git merge`, `git push`, `git checkout`, `--no-verify`. The only branch-moving commands allowed are: `git reset --hard ` exactly once at Step 0, and `git reset --hard HEAD^` to undo your own empty revert as documented in Outcome B. - ❌ Edit anything outside `/`. Never edit `$CLAUDE_PROJECT_DIR/...` directly, never edit `.git/` internals. - ❌ Drive-by refactors, prettier formatting changes, or unrelated edits. Edits must be **caused** by the revert (target additions to remove) or by a typecheck/unit/e2e failure that the revert created. - ❌ Dispatch agents or `SendMessage` — you are solo here. - ❌ Stop without either `DONE:` or `FAILED:` — the orchestrator's STATE RB-MERGE relies on those literal prefixes.