branchdiff-resolve

---
name: branchdiff-resolve
description: >-
  Read open review comments and resolve them by making code fixes. Use this
  skill when the user asks to fix review comments, resolve threads, address
  feedback, or handle code review findings. Also triggers for "fix the issues",
  "address the review", "resolve comments", or any request to act on code
  review feedback from branchdiff.
user-invocable: true
---

<!-- generated by `branchdiff skill add`; re-running it replaces this file. To customise, generate under your own `--name` prefix and edit that instead. -->

# branchdiff Resolve Skill

You are reading open review threads and resolving them by making the code changes they ask for.

## Resolve is local-only

`branchdiff agent resolve` and `dismiss` change **local review state only** — they never post to or mutate the remote PR (GitHub/Bitbucket). Remote resolution is opt-in via `--sync` (off by default). Do not push, sync, or resolve anything remotely from this skill unless `--sync` was explicitly requested.

## Arguments

- `url` (optional, **preferred**) — one of three forms:
  - **branchdiff URL** — `http://localhost:5391/diff?b1=origin%2Fdevelopment&b2=origin%2Ffeature&mode=git`. The session is already running: take host+port from it, URL-decode `b1`/`b2`, and note `includeStaged=1`/`includeUnstaged=1` if present (they mirror the browser's working-changes checkboxes — when set, read an uncommitted file with `agent file --staged` or no `--ref`, never `--ref <b2>`, same as the review skill).
  - **GitHub PR URL** — `https://github.com/owner/repo/pull/123`. Auto-creates a session.
  - **Bitbucket PR URL** — `https://bitbucket.org/workspace/repo/pull-requests/123`. Same.
- `thread-id` (optional): resolve one thread instead of every open one — `/branchdiff-resolve abc123`.
- `ref` (optional, fallback): the git ref that was reviewed. A matching live session is reused; otherwise a new one starts. Single ref (`HEAD~3`, `main`, `v1.0.0`), range (`main..feature`), or two refs (`main feature`). Defaults to the working tree.
- `instructions` (optional): free-form guidance for this pass, e.g. "skip anything under ai/", "only fix must-fix threads". Apply it in addition to the workflow below.
- `notify` (optional, default off): fire desktop toasts (resolve started / complete) via `branchdiff agent notify`, so the user is pinged even away from the chat. **Standalone only** — see the gate under Instructions. Best-effort; silently skipped if the OS has no notifier.

## Session isolation (MANDATORY — do this before any `branchdiff agent` call)

Several `branchdiff` sessions run at once on one repo (two PRs in two terminals, or several automated passes in parallel). Work on exactly one and never drift onto another PR's session.

**Resolve your session selector once, before anything else.** Every command below is written with a `$SEL` placeholder — compute it first and pass it on **every** call. Do not rely on inherited environment: a sub-shell, a background Bash call, or a nested agent may not see it.

```bash
# In order of preference — stop at the first that applies:
SEL="--session $BRANCHDIFF_SESSION_ID"     # 1. pinned by the runner (branchdiff review run / auto set this)
SEL="--port $BRANCHDIFF_PORT"              # 2. else, a known port
branchdiff list --repo                     # 3. else: exactly one session live for THIS repo → take its port
SEL="--port <that one port>"
# 4. More than one live and nothing pins you → STOP and ask the human. Never guess.
```

- **Verify first:** run `branchdiff agent list $SEL` and confirm the reported ref/PR is the one you were asked to work on. If it is not, STOP.
- **Cross-check against the live server, not just the CLI's own answer.** `--port`/`--session` resolution and the server actually serving the browser for that port can disagree if a stray session row happens to share the exact same `ref` string as the real one — `agent` then silently reads/writes a different session than what anyone looking at the browser sees. Compare the `sessionId` from `curl -s http://localhost:<port>/api/info` against what `branchdiff agent list $SEL --json` operates on (each thread's `sessionId` field); if they differ, STOP and tell the user before posting or resolving anything — do not treat the CLI's own resolution as authoritative over the live server's.
- **Refresh remote state** so you work on fresh code — pulls the latest PR comments and refuses if your local branch is behind the PR head (the same pull + stale guard `review run` and `auto` apply). No-ops when the session isn't PR-linked:
  ```bash
  branchdiff agent refresh $SEL
  ```
  Add `--allow-stale` **only** if the user explicitly asked to work on the local revision despite being behind. If refresh refuses, STOP and tell the user to update their branch — do not review or fix stale code.
- Commands without a selector **refuse** when several sessions are live — that error is the safety net working, not a bug to route around. Do **not** add `--yes` to silence it; `--yes` picks the last-active session, which is exactly the drift this prevents.
- Work only on the verified session for the whole pass. Do not run bare `branchdiff` (which could start or repoint a session) mid-pass.

## CLI Reference

```bash
branchdiff agent diff [--include-staged] [--include-unstaged] $SEL  # Output unified diff for current session
branchdiff agent file <path> [--ref <ref> | --staged] $SEL  # Print <path> as it exists at <ref>, the index (--staged), or the working tree (neither)
branchdiff agent list [--status open|resolved|dismissed] [--json] $SEL
branchdiff agent comment --file <path> --line <n> [--end-line <n>] [--side new|old] --body "<text>" $SEL
branchdiff agent general-comment --body "<text>" $SEL
branchdiff agent resolve <id> [--summary "<text>"] [--sync] $SEL
branchdiff agent dismiss <id> [--reason "<text>"] [--sync] $SEL
branchdiff agent reply <id> --body "<text>" $SEL
branchdiff agent refresh [--allow-stale] $SEL   # pull remote PR comments; refuse if the branch is behind the PR head
branchdiff agent notify "<title>" "<body>" [--open-url <url>]   # desktop toast (--notify only); no $SEL — needs no session
```

- `--file`, `--line`, `--body` are required for `comment`
- `--end-line` defaults to `--line` (single-line comment)
- `--side` defaults to `new`
- `general-comment` creates a diff-level comment not tied to any file or line
- `<id>` accepts full UUID or 8-char prefix
- `resolve`/`dismiss` are local-only; `--sync` also resolves the thread on the remote PR — pass it only when the user asked for it
- `agent diff --include-staged`/`--include-unstaged` and `agent file --staged` only apply when your checked-out branch is b1 or b2 of the current session — otherwise they no-op with a warning, since staged/unstaged content doesn't belong to either side of an unrelated branch pair

## Prerequisites

1. **`branchdiff` must be runnable.** Run `which branchdiff`. Not found, but a `PATH` hint was appended below (automated runs add one)? `export PATH` with it and retry before installing anything. Still not found: `npm install -g @encryptioner/branchdiff@latest`. If that also fails (no network or permission in this sandbox), STOP and report the exact error. Same rule if a `branchdiff agent` command that worked a moment ago starts failing mid-pass: STOP. Never fall back to reading, reviewing or fixing the checkout by hand — manual work posts nothing branchdiff can track or dedupe, and reposts as a duplicate on the next automated pass.

2. **Get a session.** Start commands run via the Bash tool with `run_in_background: true`; then wait and verify with `branchdiff agent list $SEL`.
   - **branchdiff URL** — the server is already running, so just verify. Only if no session is live (or its refs don't match b1/b2), start one: `branchdiff <b1> <b2> --no-open` (e.g. `branchdiff origin/development origin/feature --no-open`; wait 2 seconds).
   - **PR URL** — `branchdiff <pr-url> --no-open` checks the PR out, derives the base/compare refs, and starts the session; wait 5–15 seconds (network calls). Needs `gh` installed and authenticated (`gh auth status`) for GitHub, or `BITBUCKET_USERNAME` + `BITBUCKET_API_TOKEN` for Bitbucket.
   - **`ref` only** — `branchdiff --no-open` (working tree), `branchdiff HEAD~3 --no-open` (a ref), or `branchdiff <base> <compare> --no-open` (branch comparison); wait 2 seconds. Or run **/branchdiff-review** first — it starts the session.

## Need more context?

Unsure about a command, flag, or workflow detail? `branchdiff review guide` prints the full agent reference — CLI commands, review/resolve workflows, multi-instance safety rules, and the import JSON schema. Read it before proceeding.

## Where your edits land (MANDATORY — settle this before the first Edit)

Reviewing only reads; resolving **writes**. An edit goes to whatever tree you are standing in, and that is not always the branch that was reviewed.

**Do not gate on the branch name.** Fixing on a branch other than b2 is routine: the fix may belong on a branch that later merges into b2, on a rebased or renamed successor, on a shared base several review branches feed from, or b2 may already be merged into where you stand. A name check rejects all of those. What matters is whether **the code the comment is about is present in the tree you are editing**.

1. **Get the reviewed refs** — `BD_B1`/`BD_B2` if set, else the session's b1/b2 from `branchdiff agent list --json $SEL`.

2. **If `BD_WORKTREE` is set, do not edit there.** That directory is a *detached* checkout branchdiff made so the reviewer could read b2 without disturbing your branch. Commits made in it belong to no branch and are lost on the next prune — change directory to a real checkout first.

3. **Establish that the reviewed code is here.**

   ```bash
   git merge-base --is-ancestor <b2> HEAD && echo "contains b2"
   ```

   Succeeds → HEAD already contains every reviewed commit; edit here (this also covers "b2 was merged into this branch"). Otherwise decide **per file, not per branch**: fetch the reviewed copy and compare it against the one on disk.

   ```bash
   branchdiff agent file <path> --ref <b2> $SEL
   ```

   - **Identical** → the reviewed code is here verbatim. Edit here.
   - **Different, but the code the comment describes is present** → the branches diverged elsewhere; the finding still applies. Edit here, judging against the surrounding code you actually see.
   - **The code the comment describes is absent** → do not guess. See step 5.

   If that fetch errors ("does not exist at ref") and the URL that started this session had `includeStaged`/`includeUnstaged` set, the file was staged or unstaged when reviewed, not committed — re-fetch with `agent file <path> --staged $SEL` or `agent file <path> $SEL` (no `--ref`) before comparing.

4. **Locate findings by code, not by line number.** Line numbers come from the b1→b2 diff and are valid only there — on any other branch, and on b2 itself after later commits, they point at the wrong place. Find the code the comment quotes or describes, confirm it is the same construct, and fix that; if you cannot find it, treat it as absent. A file that has moved on may also mean the issue is **already fixed** — check before editing, and if it is, resolve the thread with a summary saying so instead of changing anything.

5. **A thread you cannot place stops that thread, not the run.** Do not check anything out yourself; the user may have uncommitted work. Reply on the thread saying the code was not found in the current tree, naming the branch you are on and the reviewed ref, then move to the next thread. Report the unplaced threads at the end.

6. **Say where the fix landed.** If the tree you edited is not b2, include that in every `resolve --summary` — e.g. "Fixed on `<branch>`". The session records the b1→b2 comparison, so a later reader has no other way to find the fix.

## Instructions

> **Notifications (`--notify`).** Fire `branchdiff agent notify` toasts only when the user passed `--notify` **and** the `BRANCHDIFF_PASS_ID` environment variable is unset (you are standalone). If it is set, `branchdiff auto` is driving you and already fires its own toasts — skip every `agent notify` call. Reuse the session URL you already have from Prerequisites (given in a branchdiff URL, or printed in the startup banner) for `--open-url`; never call `branchdiff list` just to fire a toast.

**Start toast** (once, before Step 1, when notifications are active):
```bash
branchdiff agent notify "branchdiff: resolve started" "<PR # or ref pair>" --open-url <session-url>   # e.g. http://localhost:5391
```

### Step 1: List open threads

```bash
branchdiff agent list --status open --json $SEL
```

The JSON carries each thread's full comment body, file path, line numbers, and side. Filter to the `thread-id` argument if one was given. No open threads → tell the user there is nothing to resolve.

### Step 2: Process each thread

**Use subagents when your runtime has them and enough threads are independent** (Claude Code's Task tool, or an equivalent parallel-task mechanism) — one per thread, never two on the same file. A subagent reads, edits, and reports back what it changed; it never calls `agent resolve`/`dismiss`/`reply` itself, so exactly one actor mutates thread state: you, after reading its report. A handful of threads, or threads sharing a file, are cheaper done sequentially.

For each open thread, check the `comments` array and `author.type` field (`"user"` or `"agent"`):

a. **Skip** general comments (filePath `__general__`) — summaries, not actionable code changes.

b. **Skip** threads whose last comment is an agent reply asking the user a question ("Could you clarify...?") with no user answer yet — the agent is waiting on input. Threads where the agent left the original finding are actionable; process those.

b'. **Resolve directly, no code change, if the last comment is a human sign-off.** Most recent comment has `author.type: "user"` and signals agreement or closure ("fixed", "done", "ok", "lgtm", "not needed", "wontfix", "nvm", "please close", "thanks")? The commenter already made the call, whether or not you can find a matching code change:
   ```bash
   branchdiff agent resolve <thread-id> --summary "Resolved per <name>'s reply: \"<their words>\"" $SEL
   ```
   Move on — skip c–e for this thread.

c. **Read the comment body** and act on its intent: a suggested code change → make it; a docs suggestion → write the docs; a question implying action ("should we add X?") → treat it as a request to do that. Genuinely unclear → ask:
   ```bash
   branchdiff agent reply <thread-id> --body "Could you clarify what change you'd like here?" $SEL
   ```

d. **Read the source file** and find the construct the comment is about — search for the code it quotes or names rather than jumping to `line`, which is only accurate on b2 at review time. Read enough surrounding context to be sure it is the same construct, then edit.

e. **Resolve the thread** with a summary:
   ```bash
   branchdiff agent resolve <thread-id> --summary "Fixed: <brief description>" $SEL
   ```

   Valid concern but the fix should not be applied now? Dismiss instead:
   ```bash
   branchdiff agent dismiss <thread-id> --reason "<why it won't be addressed>" $SEL
   ```

### Project rules

**Before editing**, read every relevant CLAUDE.md (or GEMINI.md, AGENTS.md) — the root one and any in directories holding files you will change. They define import conventions, naming and type rules, framework patterns, build/test commands, and architecture constraints. **Fixes MUST comply.** If a comment suggests a change that violates a project rule, apply its intent using the project's convention instead.

If you have not yet run the "Where your edits land" checks, do them now — an edit in a detached review worktree is silently thrown away, and an edit at the comment's line number on a diverged branch lands in the wrong place.

### Step 3: Verify the fixes before resolving

A resolved thread is a claim that the code now works. Check it:

- Run the project's own checks — build, typecheck, lint, test as named in CLAUDE.md (or the `scripts` block of `package.json` / equivalent). Take the narrowest relevant one, not the full suite, unless the change is broad.
- A failure **caused by your edit** → fix it before resolving the thread.
- A failure that predates your edit → leave it alone and say so in the resolve summary. Do not expand the change to chase unrelated breakage.
- No runnable checks in the project → say that in your final message rather than implying the fixes were verified.

Only resolve threads whose fix you have actually exercised.

### Step 4: Confirm and surface the session

```bash
branchdiff agent list $SEL
branchdiff list --repo
```

Verify every applicable thread is resolved, then take the URL fresh from `branchdiff list --repo` (scoped to this repo, not every session on the machine — never a port you recall from earlier) and **always print it back to the user** so they can jump straight to the browser view.

**Completion toast** (when notifications are active, once you have the counts — reuse the start toast's URL):
```bash
branchdiff agent notify "branchdiff: resolve done" "Resolve complete — N resolved, M remaining" --open-url <session-url>   # e.g. http://localhost:5391
```

> Resolved N threads. Resolved status appears in the browser within ~2 seconds.
>
> Session: <session-url>

## Notes

- Use the 8-char prefix of the thread `id` as `<thread-id>`
- A thread can be resolved even if the fix is on a different line than the original comment
- Use `--reason` in `dismiss` to leave context for other reviewers
- Run `branchdiff agent list --status resolved` to see everything that has been resolved