phx-pr-review

PR Review Response

Inspect unresolved pull-request review threads, triage them read-only by default,

and apply only explicitly approved fixes. GitHub mutations are never implied.

Usage

/phx-pr-review 42
/phx-pr-review 42 --fix
/phx-pr-review https://github.com/owner/repo/pull/42 --bots-only
/phx-pr-review 42 --no-resolve

Workflow

1. Resolve the PR number or URL. Prefer a runtime GitHub connector that returns

thread IDs and resolved state. Otherwise use this exact gh 2.94-compatible

fallback (requires command -v gh and gh auth status):

PR_INPUT="${1:?PR number or URL}"
if [[ "$PR_INPUT" =~ ^https://github.com/([^/]+)/([^/]+)/pull/([0-9]+) ]]; then
  OWNER="${BASH_REMATCH[1]}"; REPO="${BASH_REMATCH[2]}"; PR="${BASH_REMATCH[3]}"
else
  OWNER=$(gh repo view --json owner --jq '.owner.login')
  REPO=$(gh repo view --json name --jq '.name'); PR="$PR_INPUT"
fi
gh api graphql --paginate -F owner="$OWNER" -F repo="$REPO" -F pr="$PR"   -f query='query($owner: String!, $repo: String!, $pr: Int!, $endCursor: String) { repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { reviewThreads(first: 100, after: $endCursor) { nodes { id isResolved isOutdated path line originalLine comments(first: 100) { totalCount nodes { id databaseId body author { login __typename } replyTo { id } } } } pageInfo { hasNextPage endCursor } } } } }'
gh api graphql --paginate -F owner="$OWNER" -F repo="$REPO" -F pr="$PR"   -f query='query($owner: String!, $repo: String!, $pr: Int!, $endCursor: String) { repository(owner: $owner, name: $repo) { pullRequest(number: $pr) { reviews(first: 100, after: $endCursor) { nodes { id state body submittedAt author { login __typename } } pageInfo { hasNextPage endCursor } } } } }'

--paginate binds each returned pageInfo.endCursor to $endCursor. Filter

isResolved == false after collecting pages. Preserve thread id, root

comment id/databaseId, and author.__typename (not login suffixes).

comments(first:100) is nested and is not paginated by the outer command:

if comments.totalCount > nodes.length, report the thread as TRUNCATED and

fetch every comment page with this exact query. The outer query intentionally

omits nested comments.pageInfo so gh --paginate follows only the outer

reviewThreads.pageInfo cursor:

gh api graphql --paginate -F threadId="$THREAD_ID"   -f query='query($threadId: ID!, $endCursor: String) { node(id:$threadId) { ... on PullRequestReviewThread { comments(first:100, after:$endCursor) { totalCount nodes { id databaseId body author { login __typename } replyTo { id } } pageInfo { hasNextPage endCursor } } } } }'

Merge all comment pages in API order and deduplicate by GraphQL id (first

occurrence wins). Block triage until every truncated thread is complete. Do

not substitute issue comments for review threads.

1. Keep only unresolved threads, preserve API order, then group by path and line.

With --bots-only, use API actor type rather than a login suffix. Show one row

per thread with author, category, outdated state, and proposed action. Review

summaries are separate, non-resolvable context.

1. Gate 1 — read-only selection. Always stop after triage for an explicit list

of selected thread IDs. Selection authorizes inspection only. --fix permits

later edits but approves nothing and never selects every thread.

1. Gate 2 — edit approval. For each selected thread, read current code and

propose the exact patch. Obtain explicit edit approval before editing, or record

EDIT: NOT APPLICABLE with evidence. Then show the applied diff and run the

smallest relevant compile/test check after every code change.

1. Gate 3 — posting approval. Draft a reply only after verification. Outdated means location drift, not

addressed: require current code/diff evidence before that disposition. Show the

diff, evidence, and exact verified reply, then obtain a separate explicit posting

approval before posting. Use a connector

mutation when available, or gh api to reply to the root review comment. If

posting is unsupported or fails, report NOT POSTED with the reason.

1. Gate 4 — resolution approval. First confirm the post from the API response.

Only then request a separate resolution approval. --no-resolve always disables resolution, regardless of

any other flag or approval. Use the connector or resolveReviewThread mutation, then

confirm returned state. Never claim replied/resolved from a draft or intent.

1. Return thread | action | verification | reply | resolution, changed files,

and precise blockers. Paginated review summaries with CHANGES_REQUESTED or

an actionable non-empty body are findings even when there are zero inline

threads; report them as non-resolvable context and never call that state clean.

Do not commit or push.

Generic read-only workers may inspect independent threads when the runtime has

them, but named custom agents are not required and sequential same-session

processing is complete.

Iron Laws

1. Triage always stops for explicit thread selection — --fix permits but does

not approve edits.

1. Never post, resolve, dismiss, commit, or push without the required approval.
2. Never resolve before a successful reply and never fabricate mutation state.
3. Never claim a fix without a shown diff and successful focused verification.
4. Scrutinize bot and human findings equally; Iron Laws override suggestions.

References

• references/response-patterns.md — reply templates and tone
• references/gh-commands.md — GitHub CLI queries and mutations
• references/bot-triage.md — bot review triage