/fix-pr

name: fix-pr
description: Reads all unresolved review comments and threads on a change (PR/MR) — and its failing CI checks, which count as feedback too — implements the fixes, pushes, and replies to each thread. Tracker- and host-agnostic — GitHub via gh is the factory default; docs/agents/code-host.md overrides. Use when user says "fix pr comments", "address review", "/fix-pr", or wants to respond to PR review feedback.

Fix PR

Reads review comments, implements fixes, pushes, replies to threads.

**Contract doc.** Change mechanics come from the repo's `docs/agents/code-host.md` — read that file first if present. The commands below are the **GitHub factory defaults** (`gh`), used verbatim when that doc is absent or confirms GitHub; when it defines a different mechanic for an operation (checkout, read feedback, reply, publish commits), the doc wins. "PR" below means whatever the code host calls a reviewable change.

**Its annexes are deferred, not optional.** `code-host.md` links phase annexes — `code-host-ci.md` above all — with the phase that opens each one spelled out. **Do not read an annex at the start**: open it at the step that names it, and not before. A worker that reads them all up front pays for the whole contract in its first turn to use a quarter of it.

Invoke

/fix-pr         # fixes current branch PR
/fix-pr 42      # fixes PR #42

Flow

1. Identify and check out the PR

Get the change metadata — GitHub default:

gh pr view <PR> --json number,title,headRefName,state

Refuse if PR is closed or merged.

If the current branch is not the PR branch (the /developer pipeline runs this in a fresh worktree), first confirm **where you are**:

git rev-parse --path-format=absolute --git-dir --git-common-dir   # two different paths = linked worktree

`--path-format=absolute` is not optional: without it git prints whichever form is shortest from your cwd, so from a subdirectory of the primary checkout the two answers differ (`/abs/path/.git` vs `../.git`) and the check reads a primary checkout as a worktree.

As a /developer worker you must be in a linked worktree; if both paths are equal you are in the user's primary checkout — do not check anything out, end with `RESULT blocked reason=escaped worktree`. Then check out the change per the code-host doc's fix-that-pushes checkout. GitHub default:

gh pr checkout <PR>

If that fails with `already used by worktree` (normal under /developer — the PR branch is checked out in the build worker's worktree):

git fetch origin pull/<PR>/head:fix/pr-<PR>
git checkout fix/pr-<PR>

Two separate calls — the worktree sandbox refuses them joined with `&&`.

If `fix/pr-<PR>` is refused too — an earlier fix cycle's worktree still holds it — use `fix/pr-<PR>-r2` (then `-r3`, and so on) in both commands. Never invent a name outside `fix/pr-<PR>*`: it is what the pipeline's cleanup matches. When the caller names the local branch instead — /developer uses `agent/developer/fix-pr-<PR>` — use that name, with the same `-r2`, `-r3` suffixes.

Push later with `git push origin HEAD:<pr-branch>` instead of a plain push.

Never `git checkout main` — in a linked worktree it fails because `main` is checked out in the primary worktree.

2. Read all feedback

Per the code-host doc's read-feedback operation. GitHub default:

# Top-level comments
gh pr view <PR> --comments

# Review threads (inline)
gh api repos/{owner}/{repo}/pulls/<PR>/comments \
  --jq '[.[] | {id, path, line, body, in_reply_to_id}]'

# Review summaries
gh api repos/{owner}/{repo}/pulls/<PR>/reviews \
  --jq '[.[] | select(.body != "") | {id, state, body}]'

Collect: unresolved inline threads, review summary comments, top-level PR comments.

**Red CI is feedback too.** The `/developer` pipeline dispatches a fix job for a failing build as well as for a review, and a build that broke after a CLEAN review has **no threads at all**. So before concluding there is nothing to act on:

• If the task prompt named a failing job (`The PR's CI is red: <url>`), that

**is** your feedback — the failing checks are the work, whether or not any thread exists.

• Otherwise, if you found no threads and no comments, read the change's checks

before giving up. **This is the step that opens `docs/agents/code-host-ci.md`** (the code-host doc's CI annex) if the repo has one — take its "read the checks" operation from there. GitHub default:

  gh pr checks <PR> --json name,state,link --jq \
    '[.[] | select(.state != "SUCCESS" and .state != "SKIPPED")]'

Refuse only when **all** of it comes back empty: no threads, no comments, and either green checks or no CI. Then there is genuinely nothing to fix.

When the CI is what you are fixing, first check the failing job **actually executed**, per the CI annex's classify-a-red operation (GitHub default: `gh run view <run-id> --json jobs` — a failed job with zero steps never started). A job the CI could not start (runner offline, minutes exhausted) is not fixable from a worktree, and no amount of waiting turns it green: stop and report `RESULT blocked reason=ci-infra <one line naming the cause>` instead of waiting for it or re-running it. Otherwise, get the failure's detail from the job itself (`gh run view --log-failed`, or the job URL) rather than re-running the whole suite locally to reproduce it — you still run the project's checks once after the fix, in step 3.

3. Implement fixes

• Address every unresolved comment, except those labelled `[note]`: a review

by review-pr labels each finding, and `[blocking]` and `[fix]` are both work for you. A `[fix]` the summary lists without an inline thread is work too. Leave `[note]` findings alone unless the task prompt asks for them

• Keep changes minimal — only what feedback requests
• A finding that names several locations is fixed at all of them; grep the

files you touch for further instances of the same patter