handle-pr-review

Fetch PR review comments, triage them (fix, challenge, or skip), apply holistic fixes, resolve threads, and post a summary.

Parameters

• pr — PR number or URL (optional; auto-detected from current branch if omitted)
• auto — true or false (default false). When true, skip the operator confirmation gate (Step 3) and proceed directly to holistic analysis and fixes. Intended for build-loop autonomous invocation.

0. Prerequisites

Verify GitHub CLI authentication before any API calls:

gh auth status

If auth fails, stop and tell the user to run gh auth login.

1. Identify PR

Detect from context (branch, parameter, or URL). Prefer:

gh pr view --json number,url,state,isDraft,baseRefName,headRefName

Fall back to gh api by head branch or listing PRs.

Check PR state before proceeding:

2. Fetch unresolved threads (GraphQL)

Use GraphQL to get review threads with thread and comment IDs (needed to resolve threads and post replies). REST does not expose isResolved or thread IDs.

gh api graphql -f query='
  query($owner:String!,$repo:String!,$pr:Int!) {
    repository(owner:$owner,name:$repo) {
      pullRequest(number:$pr) {
        reviewThreads(first:100) {
          pageInfo { hasNextPage endCursor }
          nodes {
            id
            isResolved
            isOutdated
            path
            line
            viewerCanResolve
            comments(first:30) {
              nodes {
                id
                databaseId
                body
                author { login }
                path
                line
                originalLine
                createdAt
              }
            }
          }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F pr=NUMBER

Post-fetch processing:

• Filter to isResolved === false. Collect every comment per thread together — thread context matters.
• Outdated threads (isOutdated === true): the referenced code has changed since the comment was posted. Read the current code — the concern may already be addressed. If so, resolve the thread without a code change and note it in the summary.
• Pagination: If pageInfo.hasNextPage is true, re-query with reviewThreads(first:100, after:"ENDCURSOR") using the endCursor value. Repeat until all pages are collected.

Note on IDs: The databaseId on each comment is the numeric REST ID needed for the reply endpoint in step 9. The id field is the GraphQL node ID needed for resolving threads in step 8. Keep both.

3. Triage — classify each thread

Before writing any code, read all unresolved threads and the surrounding source code, then classify each:

Ground rules:

• Every comment deserves critical evaluation. Reviewers can be wrong; the goal is the best code, not maximum compliance.
• If a thread has multiple back-and-forth replies, read the entire conversation. Earlier messages may contain agreements, context, or clarifications that change the conclusion.
• Group related threads. If 3 threads raise the same concern in different files, plan one cohesive fix, not 3 isolated patches.
• Automated comments (CodeRabbit, CodeQL, Copilot, SonarCloud, etc.): triage the same way. Bots produce false positives and suggestions that conflict with project style. Do not auto-accept.

How to challenge well:

Be respectful but direct. Cite project conventions, existing patterns, or technical reasoning.

Present the triage to the user for confirmation before proceeding:

## Triage — PR #123

**Will fix:**
- Thread 1 (`src/api.ts:42`): [summary] -> [planned change]
- Thread 3 (`src/db.ts:88`): [summary] -> [planned change]

**Will fix (adjusted):**
- Thread 5 (`src/auth.ts:15`): [summary] -> [your approach, deviation noted]

**Will challenge:**
- Thread 2 (`src/util.ts:30`): [summary] -> [draft reply]

**Will skip:**
- Thread 4: [summary] — marked optional
- Thread 6: outdated — concern addressed by commit abc1234

If auto=false (default): Wait for user confirmation before proceeding. The user may reclassify items, drop threads, or add context.

If auto=true: Log the triage for auditability (include it in the PR summary comment in Step 10), then proceed immediately — do not wait for confirmation. The operator reviews the full triage in the PR summary after the autonomous cycle completes.

4. Analyse holistically before changing code

Critical: do not fix comments one-by-one in isolation.

• Read all files touched by "Fix" threads. Understand the broader context.
• Identify dependencies between comments (e.g. a rename in file A affects an import in file B).
• Plan all changes as a cohesive set — the combined diff should leave the code in a clean, consistent state.
• If fixing one comment conflicts with another, flag it to the user.

5. Apply fixes

Make all planned changes, then verify.

Discover project tooling

Check these locations (in order) to find lint, type-check, and test commands:

1. CI config — .github/workflows/*.yml, .gitlab-ci.yml, Jenkinsfile, .circleci/config.yml
2. Task runner — Makefile, Justfile, Taskfile.yml
3. Package manager — package.json (scripts section), pyproject.toml ([tool.*] and [project.scripts]), Cargo.toml
4. Linter/checker config — .eslintrc*, tsconfig.json, ruff.toml, mypy.ini, .golangci.yml

Run the discovered lint / type-check / test suite. If no tooling is discoverable, ask the user.

Commit discipline

• One commit per logical change (conventional prefixes: fix:, refactor:, chore:).
• Group related changes into a single commit rather than one commit per comment.
• Reference the feedback being addressed in the commit message body.

6. Pre-push CI check

Before pushing, check for issues that would waste a review round:

gh pr checks NUMBER

git fetch origin BASE_BRANCH
git merge-base --is-ancestor origin/BASE_BRANCH HEAD || echo "base has diverged"

7. Push

git push origin HEAD

Use --set-upstream origin HEAD if the branch has no upstream. Do not use --force; if unavoidable, use --force-with-lease and inform the user.

8. Resolve fixed threads (GraphQL)

For each thread that was fixed, resolve it using the GraphQL node ID (id field from step 2):

gh api graphql -f query='
  mutation($threadId:ID!) {
    resolveReviewThread(input:{threadId:$threadId}) {
      thread { id isResolved }
    }
  }' -f threadId=THREAD_ID

Do not resolve threads that were challenged or skipped.

If viewerCanResolve was false for a thread, note it in the summary and move on.

9. Post challenge replies

For each "Challenge" thread, reply inline using the numeric database ID (databaseId from step 2):

gh api repos/OWNER/REPO/pulls/PR/comments/DATABASE_ID/replies \
  -f body="Your reply here"

If the thread is a top-level review comment (not an inline diff comment), fall back to:

gh api repos/OWNER/REPO/issues/PR/comments -f body="Your reply here"

10. Post summary comment

Add a PR comment summarising everything:

## Review feedback addressed (abc1234)

**Fixed:**
- `src/api.ts:42` — [brief change description]
- `src/db.ts:88` — [brief change description]

**Fixed (adjusted):**
- `src/auth.ts:15` — [what changed and why approach differs from suggestion]

**Challenged:**
- `src/util.ts:30` — [brief reasoning — see inline reply]

**Skipped (optional/nit):**
- [thread summary] — [reason]

**Outdated (already addressed):**
- [thread summary] — resolved; addressed in [commit]

Resolve the short commit SHA first, then post. Use gh pr comment with -f body or unquoted heredoc:

COMMIT_SHA=$(git rev-parse --short HEAD)
gh pr comment NUMBER --body "## Review feedback addressed ($COMMIT_SHA)
...summary...
"

Notes

• Never fix blindly. Every comment deserves critical evaluation. Reviewers can be wrong; the goal is the best code, not maximum compliance.
• Thread context matters. Read the full thread conversation, not just the last comment.
• Resolved threads: Skip entirely; do not re-open or re-evaluate.
• Dismissed reviews: If a review was dismissed, its threads may still be unresolved. Treat unresolved threads from dismissed reviews the same as any other — triage on merit.
• Multiple review rounds: If running repeatedly on the same PR, only fetch and triage new unresolved threads. Reference prior summary comments to avoid re-addressing already-handled feedback.
• Forks: gh pr view and gh api graphql work across forks transparently. Use the base repo's owner/name in API calls.
• Automated tools: CodeRabbit, CodeQL, Copilot, SonarCloud — triage the same as human feedback. Do not auto-accept bot suggestions.

Common errors and recovery: