review-pr

name	review-pr
description	Inspect and finish flutter_calendar_carousel pull requests by fixing valid review findings, replying and resolving threads, diagnosing CI, using review-self when automation is unavailable, and polling at five-minute intervals until the exact head is clean. Use for PR review, review feedback, CI failures, reviewer monitoring, or requests to keep reviewing until no actionable feedback remains.

Review Pull Request

Own one PR review loop. Fix valid findings now, verify the resulting head, and stop at a clean PR unless the user separately authorized merging.

Authority And Target

• Read AGENTS.md and .claude/commands/review-pr.md completely.
• Resolve a supplied number or URL. Otherwise use the PR for the current branch.
• Confirm repository, base branch, head branch, exact head SHA, author, draft state, and whether the branch can be edited safely.
• Existing authorization to commit, push, create a PR, or reply to reviews is preserved. Review authorization alone never grants merge or release authority.
• Record the initial working tree and preserve unrelated changes.

Fetch The Complete Current State

For every round, refresh:

• PR metadata, full base-to-head diff, commits, and merge state;
• check runs and status rollup for the exact head SHA;
• submitted reviews, requested reviewers, and top-level comments;
• paginated inline review comments;
• GraphQL review threads with resolution and outdated state.

Do not infer clean state from reviewDecision alone. Do not reuse review or CI evidence from an older head.

Auto-resolve only unresolved threads GitHub marks outdated. Do not resolve a current thread merely because the author already replied.

Classify And Act

For each unresolved current finding:

1. Read the cited code and surrounding tests or workflow.
2. Classify it as valid, invalid, already fixed, obsolete, or requiring a user decision.
3. Fix every valid in-scope correctness, compatibility, CI, documentation, or regression gap in the current PR. Do not defer a real finding as follow-up.
4. Add or strengthen a focused regression test when behavior changed.
5. Run the verification required by the changed paths.

After one coherent fix batch:

1. Commit and push when already authorized.
2. Reply directly to each inline comment using its reply endpoint. Mention the plain commit hash without backticks and summarize the fix or evidence.
3. Resolve the thread after the pushed fix or evidence-backed reply fully addresses it.
4. Re-request only reviewers that are configured for this repository and need a new pass on the new head. Do not fabricate a three-bot requirement.

All public replies must be concise English. Never hide a failed check, dismiss a review, or weaken a gate.

Verification Matrix

Use touched-path checks while iterating. For dependency, Flutter SDK, native example, release, publish, or broad workflow changes, run:

flutter pub get
dart format --set-exit-if-changed .
flutter analyze
flutter test --coverage
(cd example && flutter pub get && flutter analyze && flutter test)
(cd example && flutter build apk --debug)
flutter pub publish --dry-run
git diff --check

Build the iOS example for a simulator when iOS files changed and Xcode is available. Validate changed workflow YAML. Prefer current stable Flutter for compatibility claims.

Reviewer Fallback

External review automation is optional coverage, not a completion dependency. A reviewer is unavailable for the current head when it returns a terminal quota, billing, permission, size, or service failure, or when two polling rounds after a request show neither a review nor a requested/in-progress state.

When any configured reviewer is unavailable, run exactly one complete $review-self round against the actual base and head. Pass the requirements, changed paths, checks, and current commit/push authority. The fallback must not request reviewers or start its own polling loop. Cache clean fallback coverage by reviewer failure set and head SHA; invalidate it after any head change.

Five-Minute Polling Contract

• Run the first review round immediately.
• Use the product's recurring monitor or wake-up mechanism to re-enter $review-pr 300 seconds after each non-terminal round. Never emulate this with sleep, a shell loop, nohup, or an abandoned process.
• Carry the PR number, base, exact head SHA, seen thread/check/review IDs, poll count, clean count, fallback coverage, start time, and fix-attempt fingerprints.
• Pending CI or active reviewers are neither clean nor failed. Poll without rerunning expensive unchanged local checks.
• A snapshot is clean only when the exact head has terminal successful or allowed-skipped checks, no actionable unresolved feedback, no pending configured reviewers, clean fallback coverage for unavailable reviewers, and the final diff has been reread.
• Finish after two consecutive clean snapshots separated by at least five minutes. Reset the clean count on any head or material-state change.
• If no real recurring mechanism exists, complete the current round and report that automatic re-entry could not be scheduled. Do not claim it was scheduled.

Stop Conditions

Stop and report exact evidence when two clean snapshots establish stability; the user redirects the task; the PR closes or changes incompatibly; a fix needs new authority or a product decision; the same finding survives two fix attempts; the same external/tool failure blocks three rounds; or only unchanged pending state remains after twelve polls. Never label a blocked or interrupted PR clean.

Do not merge the PR unless the user explicitly asks for merge after these gates.