Manage Prs

Manage PRs

Operating Rule

Treat GitHub as the source of truth. Do not rely on stale browser state, old summaries, local guesses, or a previous agent's report.

Only mark review threads resolved after:

1. The related fix is committed.
2. The branch is pushed.
3. The live PR state is re-read and the fixed thread IDs are still the threads being resolved.

Top-level PR conversation comments do not have review-thread resolution. Address them by fixing the issue, pushing the fix, and replying only when a reply is useful or explicitly requested.

Quick Start

From the target repo:

python3 "<skill-dir>/scripts/inspect_pr_state.py" --repo "." --pr "<number-or-url>"

If the current branch has exactly one PR, omit --pr.

After fixes are pushed and the live thread IDs are confirmed:

python3 "<skill-dir>/scripts/resolve_review_threads.py" --repo "." --thread-id "<thread-id>"

Workflow

1. Confirm the target PR.

   • Use a provided PR number/URL when present.
   • Otherwise run gh pr view --json number,url,headRefName,headRepositoryOwner.
   • Run git status --short before editing. Preserve unrelated user changes.

2. Refresh from GitHub.

   • Run git fetch --all --prune.
   • Inspect mergeability with gh pr view <pr> --json number,url,headRefName,baseRefName,mergeable,mergeStateStatus,reviewDecision.
   • If the branch is behind or conflicted, update from the PR base using the repo's normal merge/rebase pattern before calling the PR clean.

3. Inventory every blocker.

   • Run inspect_pr_state.py.
   • Read unresolved review threads.
   • Read top-level PR conversation comments.
   • Read review summary bodies, especially CHANGES_REQUESTED.
   • Read failing and pending checks.
   • For failing GitHub Actions checks, fetch logs with gh run view <run-id> --log or use the existing gh-fix-ci skill/script if available.
   • For external CI providers, open the details URL if tooling is available; otherwise report the exact external URL and continue with local reproduction where possible.

4. Cluster comments by root cause.

   • Multiple comments often point at one bug. Fix the bug once instead of making one-off edits for each comment.
   • Separate actionable requests from stale, duplicate, or already-addressed comments.
   • Do not resolve a stale-looking thread until live code proves it is obsolete and the branch has been pushed.

5. Fix and verify.

   • Reproduce failing CI locally when feasible.
   • Run the narrowest meaningful existing verification first, then broader repository-prescribed gates when the PR touches shared code.
   • Do not weaken lint, typecheck, tests, snapshots, coverage, security checks, or required workflows to get green.

6. Commit and push.

   • Use the repo's commit conventions.
   • If push is rejected, fetch/rebase or merge the remote branch, rerun the relevant checks, then push again.
   • Never resolve review threads before this push succeeds.

7. Re-check GitHub.

   • Re-run inspect_pr_state.py.
   • Re-run gh pr checks <pr> or the provider-specific status command.
   • If checks are pending, wait or watch them when practical. Do not claim there are no failing checks while required checks are still red.

8. Resolve completed review threads.

   • Resolve only the exact thread IDs whose requested changes were fixed and pushed.
   • Use resolve_review_threads.py or the GraphQL mutation directly.
   • Re-run inspect_pr_state.py and confirm unresolved actionable review threads are zero.

9. Final report.

   • Include the PR URL/number.
   • List the comments fixed, top-level comments addressed, and CI failures cleared.
   • State the exact verification run.
   • If anything remains pending or externally blocked, say exactly which check/comment and link the details.

Comment Handling Rules

• Review threads: fix, push, then resolve via GraphQL resolveReviewThread.
• Top-level PR conversation comments: fix the underlying issue. Reply only when a human needs a note; do not pretend they can be resolved.
• Review summary bodies: treat CHANGES_REQUESTED as actionable even when there is no inline thread.
• Bot comments: handle if they identify a real blocker. Ignore noise only after proving it is non-actionable.
• Duplicates: mention they are duplicates in the final report, but still verify there is no separate unresolved request.

CI/CD Handling Rules

• Required checks must not be failing when done.
• A local green test does not replace a red GitHub check. Use logs to connect the local fix to the failing workflow.
• Treat pending checks as pending, not green.
• Treat skipped/neutral checks as their own bucket. They are not failures unless branch protection or the PR UI marks them as blockers.
• If a failure is environmental or third-party, gather the run URL, error text, and retry status before reporting it as blocked.
• If several PRs share the same failing workflow, fix the shared workflow once and verify each affected PR state separately.

Useful GraphQL Mutation

Use this only after the fix is pushed:

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

Bundled Scripts

• scripts/inspect_pr_state.py: prints unresolved review threads, top-level PR comments, review summaries, and status checks for a PR.
• scripts/resolve_review_threads.py: resolves explicit review-thread IDs after the branch has been fixed and pushed.