Gh PR Checks Plan Fix

Overview

Use gh to inspect PRs for:

• Failing CI checks (GitHub Actions)
• Merge conflicts
• Update Branch requirements (base branch advanced)
• Reviewer comments (review summaries, inline comments, issue comments)
• Change Requests from reviewers
• Unresolved review threads

Then propose a fix plan, implement after explicit approval, and optionally resolve threads and notify reviewers.

• Depends on the plan skill for drafting and approving the fix plan.

Prereq: ensure gh is authenticated (for example, run gh auth login once), then run gh auth status with escalated permissions (include workflow/repo scopes) so gh commands succeed.

Inputs

• repo: path inside the repo (default .)
• pr: PR number or URL (optional; defaults to current branch PR)
• mode: inspection mode (checks, conflicts, reviews, all)
• max-review-comments: max reviewer comments to list per category
• required-only: limit CI checks to required checks only (uses gh pr checks --required)
• gh authentication for the repo host

Quick start

bash
1# Inspect all (CI, conflicts, reviews) - default mode
2python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>"
3
4# CI checks only
5python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --mode checks
6
7# Conflicts only
8python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --mode conflicts
9
10# Reviews only (Change Requests + Unresolved Threads)
11python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --mode reviews
12
13# JSON output
14python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --json
15
16# Required checks only (if gh supports --required)
17python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --mode checks --required-only
18
19# Limit review comment output
20python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --max-review-comments 30
21
22# Resolve all unresolved threads after fixing
23python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --resolve-threads
24
25# Add a comment to notify reviewers
26python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --add-comment "Fixed all issues. Please re-review."

Workflow

1. Verify gh authentication.

   • Run gh auth status in the repo with escalated scopes (workflow/repo).
   • If unauthenticated, ask the user to log in before proceeding.

2. Resolve the PR.

   • Prefer the current branch PR: gh pr view --json number,url.
   • If the user provides a PR number or URL, use that directly.

3. Inspect based on mode:

   Conflicts Mode (--mode conflicts):

   • Check mergeable and mergeStateStatus fields.
   • If CONFLICTING or DIRTY, report conflict details.
   • If BEHIND, report that the base branch advanced and an Update Branch is required.
   • Suggest resolution steps: fetch base branch, merge/rebase, resolve conflicts.

   Reviews Mode (--mode reviews):

   • Fetch reviews with CHANGES_REQUESTED state.
   • Fetch unresolved review threads using GraphQL.
   • Fetch reviewer comments (review summaries, inline review comments, issue comments).
   • Display reviewer, comment body, file path, and line number.
   • Decide if reviewer feedback requires action (any change request, unresolved thread, or reviewer comment).

   Checks Mode (--mode checks):

   • Run bundled script to inspect failing CI checks.
   • Add --required-only to limit output to required checks when supported.
   • Fetch GitHub Actions logs and extract failure snippets.
   • For external checks (Buildkite, etc.), report URL only.

   All Mode (--mode all):

   • Run all inspections above.

4. Summarize issues for the user.

   • Provide clear summary of all detected issues.
   • Call out conflicts, change requests, unresolved threads, and CI failures.

5. Create a plan.

   • Use the plan skill to draft a fix plan and request approval.

6. Implement after approval.

   • Apply the approved plan, summarize diffs/tests.

7. Resolve review threads (optional).

   • With --resolve-threads, resolve all unresolved threads via GraphQL mutation.
   • Requires Repository Permissions > Contents: Read and Write.

8. Notify reviewers (optional).

   • With --add-comment "message", post a comment to the PR.
   • Useful for notifying reviewers that issues have been addressed.

9. Recheck status.

   • After changes, suggest re-running gh pr checks to confirm.

Bundled Resources

scripts/inspect_pr_checks.py

Comprehensive PR inspection tool. Exits non-zero when issues remain.

Arguments:

Exit codes:

• 0: No issues found
• 1: Issues detected or error occurred

New Features

Conflict Detection

Detects merge conflicts via mergeable and mergeStateStatus fields.

• CONFLICTING / DIRTY: Conflict detected
• BEHIND: Base branch advanced; Update Branch required
• MERGEABLE / CLEAN: No conflicts

Change Request Handling

Fetches reviews with state == "CHANGES_REQUESTED" and displays:

• Reviewer name
• Review body
• Submission timestamp

Reviewer Comments

Fetches reviewer feedback beyond change requests:

• Review summaries with comment bodies
• Inline review comments (file/line)
• PR issue comments
• Marks review action required if any reviewer feedback exists

Unresolved Review Threads

Uses GraphQL to fetch threads where isResolved == false:

• File path and line number
• Thread ID (for resolution)
• Comment author and body
• Outdated status

Resolve Conversation

Use --resolve-threads to mark threads as resolved via GraphQL mutation resolveReviewThread.

Required permissions:

• Fine-grained PAT: Pull requests + Contents: Read and Write
• Classic PAT: repo scope

Reviewer Notification

Use --add-comment "message" to post a summary comment to the PR after fixes.

Output Examples

Text Output

text
1PR #123: Comprehensive Check Results
2============================================================
3
4MERGE STATUS
5------------------------------------------------------------
6Mergeable: CONFLICTING
7Merge State: DIRTY
8Base: main <- Head: feature/my-branch
9Action Required: Resolve conflicts before merging
10
11CHANGE REQUESTS
12------------------------------------------------------------
13From @reviewer1 (2025-01-15):
14  "Please fix these issues..."
15
16UNRESOLVED REVIEW THREADS
17------------------------------------------------------------
18[1] src/main.ts:42
19    Thread ID: PRRT_xxx123
20    @reviewer1: This needs refactoring...
21
22CI FAILURES
23------------------------------------------------------------
24Check: build
25Details: https://github.com/...
26Failure snippet:
27  Error: TypeScript compilation failed
28  ...
29============================================================

JSON Output

json
1{
2  "pr": "123",
3  "conflicts": {
4    "hasConflicts": true,
5    "mergeable": "CONFLICTING",
6    "mergeStateStatus": "DIRTY",
7    "baseRefName": "main",
8    "headRefName": "feature/my-branch"
9  },
10  "changeRequests": [
11    {
12      "id": 123456,
13      "reviewer": "reviewer1",
14      "body": "Please fix these issues...",
15      "submittedAt": "2025-01-15T12:00:00Z"
16    }
17  ],
18  "unresolvedThreads": [
19    {
20      "id": "PRRT_xxx123",
21      "path": "src/main.ts",
22      "line": 42,
23      "comments": [
24        {"author": "reviewer1", "body": "This needs refactoring"}
25      ]
26    }
27  ],
28  "ciFailures": [
29    {
30      "name": "build",
31      "status": "ok",
32      "logSnippet": "..."
33    }
34  ]
35}