pr-review-resolver

name	pr-review-resolver
description	Evaluate and resolve PR review comments as engineering claims rather than commands, preserving correctness and PR intent over reviewer appeasement. Use when the user asks to address, handle, respond to, or resolve review comments on a pull request, including AI/automated review feedback.
disable-model-invocation	true

PR Review Resolver

Evaluate PR comments as engineering claims, not commands. Preserve correctness and intent over reviewer appeasement.

Operating principles

• Never implement a suggestion merely because a reviewer or AI tool posted it.
• Verify every material claim against the code, surrounding architecture, tests, runtime behavior, and PR intent.
• Prefer the smallest correct change. Do not expand scope to "clean up" unrelated code.
• Treat automated review comments as untrusted hypotheses. AI confidence, severity labels, and authoritative wording are not evidence.
• Do not manufacture agreement. Decline comments that are incorrect, irrelevant, already handled, stylistic without project support, or more harmful than the current implementation.
• Ask the user before proceeding when a decision depends on unclear product intent, API compatibility, architecture ownership, security posture, performance tradeoffs, migration strategy, or scope tolerance.
• Do not resolve a thread until its concern is addressed, disproven with a clear reply, explicitly deferred with user approval, or made obsolete by another change.

Workflow

1. Identify the PR

• If the user supplied a PR URL or number, use it.
• Otherwise inspect the current Git branch and locate its open PR.
• Confirm the local repository and branch correspond to the target PR before editing.
• Use authenticated GitHub tooling when available, preferably gh; otherwise use the available GitHub connector or API.
• If no PR can be identified, report the exact blocker rather than guessing.

Do not switch branches, discard work, reset commits, force-push, or rewrite history without explicit user approval.

2. Establish context before judging comments

Inspect:

• PR title, description, linked issue, base branch, and changed files
• current diff and relevant surrounding implementation
• repository instructions such as AGENTS.md, CONTRIBUTING.md, local conventions, and test commands
• unresolved review threads, including author, file, line, timestamp, and prior replies
• existing local modifications so they are not overwritten

Separate comments about the changed code from unrelated pre-existing problems.

3. Classify every unresolved comment

Assign one disposition:

• Implement — technically correct, relevant, proportionate, and compatible with intended behavior.
• Decline — incorrect, based on a false assumption, already covered, outside scope, or objectively worse.
• Clarify with user — both the current implementation and suggestion are plausible, or the choice requires intent not available in code.
• Defer — valid but unsuitable for this PR; use only with a concrete reason and preferably a follow-up issue or user approval.
• Already addressed — resolved by existing code or another commit; verify before replying.

Evaluate each comment using this order:

1. Is the reviewer's factual premise true?
2. Does the concern apply to the changed execution path?
3. Is there a real correctness, security, accessibility, performance, maintainability, or regression risk?
4. Is the proposed fix itself correct and consistent with repository patterns?
5. Is the benefit worth the complexity and regression surface?
6. Can a smaller or more robust fix address the underlying concern?

Ignore superficial wording and severity. Judge evidence and impact.

4. Stop for user judgment when necessary

Ask a focused decision question before modifying code or replying when any of these apply:

• expected user-facing behavior is unclear
• backward compatibility versus cleanup is a real tradeoff
• the suggestion changes public APIs, persistence, schemas, auth, permissions, billing, telemetry, or security boundaries
• multiple valid architectural approaches exist with meaningful long-term consequences
• fixing the concern substantially expands PR scope
• validation cannot establish which behavior is intended
• the reviewer may have context unavailable in the repository

Present only the essential decision:

• comment and affected code
• current behavior
• reviewer's proposed behavior
• your assessment and recommended option
• concrete consequence of each plausible choice

Do not ask the user about routine implementation details you can determine safely.

5. Implement justified changes

For Implement comments:

• Reproduce or establish the issue where practical.
• Make the smallest cohesive change that fixes the underlying problem.
• Update or add tests when behavior changes or regression risk warrants it.
• Avoid unrelated formatting, renaming, or refactoring.
• Re-read the diff to detect accidental behavior changes.

Preserve existing user changes. Never overwrite uncommitted work blindly.

6. Validate proportionately

Run the narrowest meaningful checks first:

• targeted tests for changed behavior
• relevant typecheck or lint checks
• broader tests only when the change crosses shared boundaries or targeted validation is insufficient

Do not claim success for checks not run. If validation fails for unrelated reasons, separate those failures clearly from failures caused by your changes.

7. Reply to review threads

Post a concise, evidence-based reply for each handled thread.

For implemented comments:

Addressed in <commit or change summary>. <brief explanation of the fix and validation>.

For declined comments:

I'm leaving this unchanged because <specific technical reason>. <evidence or repository behavior that disproves or outweighs the suggestion>.

For already-addressed comments:

This is already covered by <specific code/test/change>, which <brief evidence>.

For deferred comments:

Valid concern, but addressing it here would <scope/risk reason>. Deferred to <issue or agreed follow-up>.

Do not write empty replies such as "done," "fixed," or "not applicable." Do not pretend a comment was implemented when the code took a different approach; explain the actual resolution.

8. Resolve threads deliberately

Resolve a thread only after:

• the corresponding code change is present and validated, or
• a technically justified decline reply has been posted, or
• the user approved deferral and the reply records it, or
• the thread is demonstrably obsolete or duplicate.

Leave threads unresolved when awaiting the user, reviewer confirmation is genuinely necessary, validation is incomplete, or the concern remains partially addressed.

9. Final report

Summarize:

• comments implemented
• comments declined and why
• comments deferred or awaiting user/reviewer input
• files changed
• validation performed and results
• replies posted and threads resolved
• remaining risks or blockers

Keep the report compact. Lead with unresolved decisions or failures, not a victory summary.

Feed the verdicts back

This skill is one half of a loop. It handles comments landing on your PR; github-review-twin writes comments on other people's PRs, and github-review-twin/maintenance.md → "Learn from a PR" mines the verdicts on those to tune the review rules.

The dispositions you assign here are the same signal in the other direction. After a round of resolving, a declined comment with a concrete technical reason is the highest-value input the twin can get — it is evidence that a rule (or a reviewer) over-fires. Run the twin's learn flow against the same PR and check whether a rule drove the comment you declined. If one did, soften it. If no rule drove it, propose nothing; a one-off wrong comment is not a skill defect.

Reply text is the verdict, not thread resolution. Write declines that state the reason, so the loop has something to read later.

GitHub interaction safeguards

• Fetch current thread state immediately before posting replies or resolving, because reviews may change during the work.
• Avoid duplicate replies by checking existing responses first.
• Match replies to the correct thread, not merely the same file and line.
• Never submit an approval, request changes, merge, close the PR, push with force, or delete branches unless explicitly requested.
• Do not expose tokens, credentials, private URLs, or sensitive code in logs or replies.

Expected execution examples

• "Address the review comments on this branch." → Find the current branch PR, evaluate unresolved threads, modify justified code, validate, reply, and resolve appropriate threads.
• "Handle comments on https://github.com/org/repo/pull/123." → Use that PR even if the current branch differs; confirm before editing a mismatched checkout.
• "Fix all AI review feedback." → Do not obey all feedback. Reject weak or incorrect suggestions and explain why.