Gh Fix Pr

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, reply to every reviewer comment (with action taken or reason for not addressing), resolve all 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.

Comment Response Policy

> No reviewer comment may be left unanswered.

• Every unresolved review thread MUST receive a reply before being resolved.
• If the feedback was addressed: reply with what was done (e.g., "Fixed: refactored as suggested.").
• If the feedback was intentionally not addressed: reply with the reason (e.g., "Not addressed: this is intentional because the API contract requires this format.").
• The --reply-and-resolve argument enforces this by requiring a reply entry for every unresolved thread and rejecting empty bodies.

Diagnosis Report Anti-Patterns

Prohibited Language

| Prohibited | Required Alternative | |---|---| | "We should look into..." | "Edit path/file.ts:42 to..." | | "There seem to be some issues" | "3 blocking items detected" | | "This might be causing..." | "Root cause: `" | | "Consider fixing..." / "It looks like..." | "Action: Fix in " | | "Various CI checks are failing" | "2 CI checks failing: build, lint" | | "Some reviewers have concerns" | "@reviewer1 requested: `" | | "I'll try to fix this" | "Action: \" |

Structural Prohibitions

• Prose paragraphs for reporting — use B1/I1 item format exclusively.
• Omitting the Evidence field in any BLOCKING item.
• Combining multiple independent problems into a single item.
• Omitting file paths or line numbers when the script output contains them.

Issue/PR Comment Formatting (must follow)

• Final comment text must not contain escaped newline literals such as \n.
• Use real line breaks in comment bodies. Do not rely on escaped sequences for formatting.
• Before posting (--add-comment or manual gh issue/pr comment), verify the final body does not accidentally include escaped control sequences (\n, \t).
• If a raw escape sequence must be shown for explanation, include it only inside a fenced code block and clarify it is intentional.

Issue Progress Comment Template (required for issue-based work)

When work is tracked in GitHub Issues, progress updates must use this template:

Progress
- ...

Done
- ...

Next
- ...

• Post updates at least when starting work, after meaningful progress, and when blocked/unblocked.
• In Next, explicitly state blockers or the immediate next action.

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)
• required-only: limit CI checks to required checks only (uses gh pr checks --required)
• gh authentication for the repo host

Quick start

# Inspect all (CI, conflicts, reviews) - default mode
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr ""

# CI checks only
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --mode checks

# Conflicts only
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --mode conflicts

# Reviews only (Change Requests + Unresolved Threads)
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --mode reviews

# JSON output
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --json

# Required checks only (if gh supports --required)
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --mode checks --required-only

# Reply to all unresolved threads and resolve them
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --reply-and-resolve '[
  {"threadId":"PRRT_xxx123","body":"Fixed: refactored the method as suggested."},
  {"threadId":"PRRT_xxx456","body":"Not addressed: this is intentional because the API requires this format."}
]'

# Add a comment to notify reviewers
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-pr/scripts/inspect_pr_checks.py" --repo "." --pr "" --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.

1. 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.

1. 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 ALL reviewer comments (review summaries, inline review comments, issue comments) without truncation.
• Display reviewer, comment body (full text), 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.

1. Produce Diagnosis Report (mandatory format).

Output MUST use this exact structure:

```text ## Diagnosis Report: PR #

Merge Verdict: BLOCKED | CLEAR Blocking items:

---

### BLOCKING

#### B1. [CATEGORY]

• What: Factual statement (no speculation)
• Where: filepath:linenumber / check name / branch ref
• Evidence: Verbatim quote from script output
• Action: Specific fix (file path, command, or code change — at least one required)
• Auto-fix: Yes | No (needs confirmation)

#### B2. [CATEGORY] ...

---

### INFORMATIONAL #### I1. [CATEGORY]

• What / Note

---

Summary: blocking items to fix, informational items noted. ```

Classification rules:

• BLOCKING: CONFLICTING/DIRTY merge state, BEHIND, CI failure/cancelled/timed\out/action\required, CHANGES\_REQUESTED, unresolved review threads
• INFORMATIONAL: Comments without change requests, pending CI, outdated review threads

Category labels: CONFLICT, BRANCH-BEHIND, CI-FAILURE, CHANGE-REQUEST, UNRESOLVED-THREAD, REVIEW-COMMENT

Auto-fix judgment:

• Auto-fix: Yes — CI-FAILURE code fixes, reviewer instructions that the LLM can address with high confidence
• Auto-fix: No (needs confirmation) — CONFLICT resolution (merge/rebase), low-confidence reviewer instructions, changes requiring design decisions

Each CHANGE-REQUEST and each UNRESOLVED-THREAD is a separate B-item. Do not combine multiple threads or requests into one item.

1. Decide execution path.

• If ALL blocking items have Auto-fix: Yes → display Diagnosis Report, skip plan, proceed directly to step 6.
• If ANY blocking item has Auto-fix: No → create a plan referencing B-item IDs (e.g., "Fix B1: ...", "Fix B3: ...") and request user approval for Auto-fix: No items before proceeding.

1. Implement fixes.

• Apply the approved fixes, summarize diffs/tests.
• After applying fixes, commit changes and push to the PR branch.
• Verify push succeeded before proceeding to step 7.
• After implementing fixes, proceed to step 7 to reply and resolve ALL threads.
• For BRANCH-BEHIND items, see [Fix Strategies: BRANCH-BEHIND](#branch-behind).
• For CONFLICT items, see [Fix Strategies: CONFLICT](#conflict).

1. Reply to ALL reviewer comments and resolve threads (mandatory).

• CRITICAL: Every unresolved review thread MUST receive a reply before resolution. No thread may be silently resolved or left unaddressed.
• For each unresolved thread, prepare a reply:
• If addressed: describe what was done (e.g., "Fixed: refactored the method as suggested in commit abc1234.")
• If intentionally not addressed: explain the reason (e.g., "Not addressed: this is by design because ...")
• Use --reply-and-resolve with a JSON array covering ALL unresolved threads.
• The script validates completeness and rejects the operation if any thread is missing a reply.
• Requires Repository Permissions > Contents: Read and Write.
• Resolve threads at this point (after code fix is pushed). Do not wait for CI completion to resolve threads.

1. Notify reviewers (mandatory).

• With --add-comment "message", post a comment to the PR.
• Include a summary of what was fixed (list each B-item and the action taken).
• This step is not optional — always notify reviewers after fixes are applied.

1. Verify fix (mandatory — do not skip).

• Re-run the inspection script with --mode all (regardless of initial mode).
• Exit code 0 → all resolved → report success to user.
• Exit code 1 → issues remain → go back to step 4 with new output.
• No iteration limit. Continue until all issues are resolved.
• CI still pending/queued → poll at 30-second intervals (no timeout) until ALL checks complete.
• Wait for ALL CI checks to complete before starting fixes (pushing resets pending checks).
• After fix push, re-enter polling to wait for new CI run to complete.

Loop Safety Guard

• If the same CI check name (e.g., build) fails 3 consecutive iterations:

1. Report to user: which check, what was tried in each iteration, what keeps failing.
2. Ask user to choose: continue / abort / change approach.
3. Only proceed after explicit user decision.

• This prevents oscillation loops where fix A breaks B and fix B breaks A.
• Different checks failing in different iterations do NOT trigger the guard (e.g., build fails → fixed → lint fails is normal progression, not oscillation).

Fix Strategies

BRANCH-BEHIND

• Default strategy: git fetch origin && git merge origin/
• If merge results in conflicts, switch to CONFLICT handling below.

CONFLICT

• LLM attempts to resolve conflicts after user confirmation.
• Present conflict summary (affected files, conflict markers) and proposed resolution to the user.
• Execute resolution only after user approves.

Bundled Resources

scripts/inspectprchecks.py

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

Arguments:

| Argument | Default | Description | |----------|---------|-------------| | --repo | . | Path inside the target Git repository | | --pr | (current) | PR number or URL | | --mode | all | Inspection mode: checks, conflicts, reviews, all | | --max-lines | 160 | Max lines for log snippets | | --context | 30 | Context lines around failure markers | | --required-only | false | Limit CI checks to required checks only | | --json | false | Emit JSON output | | --reply-and-resolve | (none) | JSON array of {threadId, body} to reply and resolve ALL threads | | --add-comment | (none) | Add a comment to the PR |

Exit codes:

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

--reply-and-resolve JSON format:

[
  {"threadId": "PRRT_xxx123", "body": "Fixed: refactored the method as suggested."},
  {"threadId": "PRRT_xxx456", "body": "Not addressed: this is intentional because ..."}
]

Validation rules:

• Every currently unresolved thread MUST have a corresponding entry.
• Every entry MUST have a non-empty body.
• If any unresolved thread is missing, the script prints the missing thread details and exits with error.

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 ALL reviewer feedback without truncation:

• Review summaries with full comment bodies
• Inline review comments (file/line) with full comment bodies
• PR issue comments with full comment bodies
• 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 reply and resolution)
• Comment author and full body
• Outdated status

Reply and Resolve

Use --reply-and-resolve to reply to every unresolved thread and resolve them.

• Uses GraphQL addPullRequestReviewThreadReply to post a reply.
• Uses GraphQL resolveReviewThread to mark the thread as resolved.
• Validates that ALL unresolved threads are covered (no thread left behind).
• Rejects empty reply bodies.

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

Diagnosis Report

## Diagnosis Report: PR #123

**Merge Verdict: BLOCKED**
Blocking items: 3

---

### BLOCKING

#### B1. [CI-FAILURE] TypeScript build fails
- **What:** `build` check failed with compilation error
- **Where:** `src/utils/parser.ts:42` / check: `build`
- **Evidence:** `error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.`
- **Action:** Edit `src/utils/parser.ts:42` — change `parseInt(value)` to pass the correct type
- **Auto-fix:** Yes

#### B2. [CHANGE-REQUEST] @reviewer1 requests error handling
- **What:** Reviewer requested try-catch around API call
- **Where:** `src/api/client.ts:88`
- **Evidence:** "@reviewer1: Please wrap this fetch call in a try-catch block to handle network errors gracefully."
- **Action:** Add try-catch in `src/api/client.ts:88` around the `fetch()` call
- **Auto-fix:** Yes

#### B3. [CONFLICT] Merge conflict with main
- **What:** 2 files have merge conflicts
- **Where:** `src/config.ts`, `src/index.ts` / branch: `main`
- **Evidence:** `Mergeable: CONFLICTING, Merge State: DIRTY`
- **Action:** Merge `origin/main` and resolve conflicts in listed files
- **Auto-fix:** No (needs confirmation)

---

### INFORMATIONAL
#### I1. [REVIEW-COMMENT] Code style suggestion
- **What / Note:** @reviewer2 suggested extracting a helper function — non-blocking style preference

---

**Summary:** 3 blocking items to fix, 1 informational item noted.

Text Output

PR #123: Comprehensive Check Results
============================================================

MERGE STATUS
------------------------------------------------------------
Mergeable: CONFLICTING
Merge State: DIRTY
Base: main <- Head: feature/my-branch
Action Required: Resolve conflicts before merging

CHANGE R

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [akiojin](https://github.com/akiojin)
- **Source:** [akiojin/skills](https://github.com/akiojin/skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.