olliecrow/gh-fix-ci

Gh Pr Checks Plan Fix

Multi-agent collaboration

• Default to using subagents when they are likely to improve speed, quality, confidence, or keep the main context clean.
• Use subagents to widen coverage, dig deeper on one thread, get a fresh second opinion, or keep the main thread clean while side work runs.
• Split work into clear packets with owners, inputs, acceptance checks, and a synthesis step when parallelizing.
• Keep the main agent focused on synthesis, unblockers, and the next critical-path step; let subagents handle bounded side work that can run in parallel.
• Use single-agent execution only when scope is small or coordination overhead outweighs gains.

Gh-fix-ci-specific subagent split

• Default to subagents when there are multiple failing checks, unclear logs, or a fix needs both diagnosis and proof.
• Suggested split: log-reader owns failing job logs, key snippets, and suspected failure points, and updates plan/current/gh-fix-ci.md.
• Suggested split: repro-or-fix-worker owns local reproduction or the narrowest high-confidence fix path and updates the same note with changed files and open risks.
• Suggested split: verification-runner owns the smallest local checks plus final gh pr checks recheck before closeout.
• The main agent owns PR selection, final fix choice, metadata updates, and the merged user-facing story.
• Use subagents only when the work splits cleanly; otherwise stay single-agent.

Proactive autonomy and knowledge compounding

• Be proactive: immediately take the next highest-value in-scope action when it is clear.
• Default to autonomous execution: do not pause for confirmation between normal in-scope steps.
• Request user input only when absolutely necessary: ambiguous requirements, material risk tradeoffs, missing required data/access, or destructive/irreversible actions outside policy.
• If blocked by command/tool/env failures, attempt high-confidence fallbacks autonomously before escalating (for example rg -> find/grep, python -> python3, alternate repo-native scripts).
• When the workflow uses plan/, ensure required plan directories exist before reading/writing them (create when edits are allowed; otherwise use an in-memory fallback and call it out).
• Treat transient external failures (network/SSH/remote APIs/timeouts) as retryable by default: run bounded retries with backoff and capture failure evidence before concluding blocked.
• On repeated invocations for the same objective, resume from prior findings/artifacts and prioritize net-new progress over rerunning identical work unless verification requires reruns.
• Drive work to complete outcomes with verification, not partial handoffs.
• Treat iterative execution as the default for non-trivial work; run adaptive loop passes. Example loops (adapt as needed, not rigid): issue-resolution investigate -> plan -> fix -> verify -> battletest -> organise-docs -> git-commit -> re-review; cleanup scan -> prioritize -> clean -> verify -> re-scan; docs audit -> update -> verify -> re-audit.
• Keep looping until actual completion criteria are met: no actionable in-scope items remain, verification is green, and confidence is high.
• Run organise-docs frequently during execution to capture durable decisions and learnings, not only at the end.
• Create small checkpoint commits frequently with git-commit when changes are commit-eligible, checks are green, and repo policy permits commits.
• Never squash commits; always use merge commits when integrating branches.
• Prefer simplification over added complexity: aggressively remove bloat, redundancy, and over-engineering while preserving correctness.
• When you touch code, leave the touched area in a better state than you found it: clearer, simpler, tidier, and at least as performant unless the task requires an explicit trade-off.
• Before finishing any non-trivial task or pass, run at least one explicit consolidation pass across the touched code, docs, notes, tests, and configs.
• Use that pass to merge toward one clear source of truth, remove stale or duplicate material, and resolve contradictions before you declare the work complete.
• Do this by default as part of normal completion, even when the user did not explicitly ask for cleanup, consolidation, or contradiction resolution.
• Use simple, plain English in user messages, docs, notes, reports, code comments, and other explanatory writing. Avoid jargon, fancy wording, and complex phrasing. When a technical term is needed for correctness, explain it in simple words the first time. Default to short user-facing responses. Think about what the user most wants to know, and lead with that. Do not dump every detail by default. Always include important changes, blockers, verification gaps, and any important assumptions, nuances, principles, or decisions that shaped the work. Add more detail only when the user asks for it or when uncertainty or risk makes it necessary.
• Compound knowledge continuously: keep docs/ accurate and up to date, and promote durable learnings and decisions from work into docs.

Long-task checkpoint cadence

• For any non-trivial task (including long efforts), run recurring checkpoint cycles instead of waiting for a single end-of-task wrap-up.
• At each meaningful milestone with commit-eligible changes, and at least once per major phase, invoke git-commit to create a small logical checkpoint commit once relevant checks are green and repo policy permits commits.
• At the same cadence, invoke organise-docs whenever durable learnings/decisions appear, and prune stale plan/ scratch artifacts.
• If either checkpoint is blocked (for example failing checks or low-confidence documentation), resolve or record the blocker immediately and retry before expanding scope.

Terminal state contract (must follow)

The skill is complete only when all of the following are true:

• Objective completion: the user-requested outcome is achieved, or explicitly marked blocked with concrete blocker evidence.
• Workflow completion: every required workflow step is resolved as done, blocked, or not-applicable, with brief evidence or rationale.
• Step-level terminal completion: each numbered subtask must have explicit completion evidence (artifact, command output, or written rationale) before advancing.
• Verification completion: required checks/validations for this skill are executed, or any unavailable checks are explicitly called out with impact.
• Findings completion (where applicable): report only evidence-backed findings; if no high-confidence critical findings are present, explicitly state that.
• Loop completion: no actionable in-scope next step remains under the current objective.

Stop only after this terminal contract is satisfied; otherwise continue iterating.

Terminal state examples (adapt to skill)

• done: requested outcome is delivered and required checks are completed (for example expected artifact/report produced and required validation command(s) passed).
• blocked: progress cannot continue after bounded retries because of a concrete dependency or access issue; blocker evidence and exact unblock action are reported.
• not-applicable: an optional step is explicitly skipped with reason (for example no remote configured, so push step is marked not-applicable).

Overview

Use gh to locate failing PR checks, fetch GitHub Actions logs for actionable failures, summarize the failure snippet, then propose and execute a fix plan autonomously with explicit verification.

• If a plan-oriented skill (for example plan) is available, use it; otherwise draft a concise plan inline and proceed when confidence is high.

Prereq: authenticate with the standard GitHub CLI once (for example, run gh auth login), then confirm with gh auth status (repo + workflow scopes are typically required).

Preflight (must run first)

• Confirm repo context and branch state (git rev-parse --show-toplevel, git symbolic-ref -q --short HEAD).
• Confirm gh availability/auth (command -v gh, gh auth status).
• If detached HEAD or no branch PR is available, require an explicit PR number/URL instead of guessing.
• Verify referenced paths exist before writing logs or artifacts.

Inputs

• repo: path inside the repo (default .)
• pr: PR number or URL (optional; defaults to current branch PR)
• gh authentication for the repo host

Quick start

• python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"
• Add --json if you want machine-friendly output for summarization.

Workflow

1. Verify gh authentication.
   • Run gh auth status in the repo.
   • If unauthenticated, try available non-interactive auth/context fallbacks first (for example existing token env or alternate host context). Ask the user to run gh auth login only if auth remains blocked.
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.
   • If current-branch PR discovery fails, retry once with explicit --repo <owner>/<repo> before asking the user.
3. Inspect failing checks (GitHub Actions only).
   • Preferred: run the bundled script (handles gh field drift and job-log fallbacks):
     • python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "<number-or-url>"
     • Add --json for machine-friendly output.
   • Manual fallback:
     • gh pr checks <pr> --json name,state,bucket,link,startedAt,completedAt,workflow
       • If a field is rejected, rerun with the available fields reported by gh.
       • Keep a minimal fallback field set ready: name,state,link to survive CLI schema drift.
     • For each failing check, extract the run id from detailsUrl and run:
       • gh run view <run_id> --json name,workflowName,conclusion,status,url,event,headBranch,headSha
       • gh run view <run_id> --log
     • If the run log says it is still in progress, fetch job logs directly:
       • gh api "/repos/<owner>/<repo>/actions/jobs/<job_id>/logs" > "<path>"
4. Scope non-GitHub Actions checks.
   • If detailsUrl is not a GitHub Actions run, label it as external and only report the URL.
   • Do not attempt Buildkite or other providers; keep the workflow lean.
5. Summarize failures for the user.
   • Provide the failing check name, run URL (if any), and a concise log snippet.
   • Call out missing logs explicitly.
6. Create a plan.
   • Use the plan skill to draft a concise, execution-ready plan.
7. Implement and verify.
   • Apply high-confidence in-scope fixes autonomously, summarize diffs/tests, and update PR metadata as needed (never create draft PRs).
   • Before rechecking status, run one consolidation pass over touched code, docs, tests, and configs so duplicate fixes or contradictory guidance do not survive.
8. Recheck status.
   • After changes, rerun the relevant tests and gh pr checks to confirm.
   • Keep iterating plan -> fix -> verify until checks are green or a true blocker remains.
9. Refresh active PR metadata.
   • Check whether the current branch has an active PR.
   • Compare PR title/body against the branch intent and actual delta after CI fixes.
   • If title/body are stale or incomplete, update them with sanitized metadata only (for example with gh pr edit --title ... --body-file ... using repo-relative paths or plain-language references rather than absolute local paths, file URLs, or raw terminal transcripts).
   • If the active PR is draft and the branch is review-ready, promote it (for example with gh pr ready <pr-number-or-url>).
   • If no active PR exists, state that explicitly and continue.

Failure-handling defaults

• Treat Unknown JSON field from gh as schema drift; retry with a reduced field set instead of failing the task.
• Treat could not determine current branch as branch-state ambiguity; switch to explicit PR mode.
• Treat Not Found (404) as repo/PR mismatch first; verify --repo and PR identity before deeper debugging.

Bundled Resources

scripts/inspect_pr_checks.py

Fetch failing PR checks, pull GitHub Actions logs, and extract a failure snippet. Exits non-zero when failures remain so it can be used in automation.

Usage examples:

• python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "123"
• python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --pr "https://github.com/org/repo/pull/123" --json
• python "<path-to-skill>/scripts/inspect_pr_checks.py" --repo "." --max-lines 200 --context 40