Gh Fix CI

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

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-ci/scripts/inspect_pr_checks.py" --repo "." --pr "<number>"

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

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

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

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

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

# Reply to all unresolved threads and resolve them
python3 "${CLAUDE_PLUGIN_ROOT}/github/skills/gh-fix-ci/scripts/inspect_pr_checks.py" --repo "." --pr "<number>" --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-ci/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 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.

4. Produce Diagnosis Report (mandatory format).

   Output MUST use this exact structure:

   ## Diagnosis Report: PR #<number>
   
   **Merge Verdict: BLOCKED | CLEAR**
   Blocking items: <N>
   
   ---
   
   ### BLOCKING
   
   #### B1. [CATEGORY] <1-line title>
   - **What:** Factual statement (no speculation)
   - **Where:** file_path:line_number / 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] <1-line title>
   ...
   
   ---
   
   ### INFORMATIONAL
   #### I1. [CATEGORY] <1-line title>
   - **What / Note**
   
   ---
   
   **Summary:** <N> blocking items to fix, <M> 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.

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

6. 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.
   • For CONFLICT items, see Fix Strategies: CONFLICT.

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

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

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