/ai-ci

Use when the ask is why CI / a PR check failed — a red GitHub Action, failed gh pr checks entry, or a linked Actions run.

Prefer to delegate: task({ subagent_type: "ci", description, prompt }) runs this ladder in the background; await_subagent before you answer. Follow the ladder yourself only when you are already inside that subagent or no spawn is available.

Ladder

1. Scope — pin PR number, run id, check/job name, branch, or commit before fetching logs. Default: current branch's open PR (gh pr list --head). A wrong run makes every later log meaningless.

2. Enumerate — list failing checks (gh pr checks / gh run view <id> --json jobs). Note duration and whether steps / runner_name are empty.

3. Bootstrap gate (before logs) — job finished in a few seconds with zero steps or no runner → do not download logs (empty zip / 404 / 401). Fetch the platform reason:

   gh api repos/<owner>/<repo>/check-runs/<check_run_id>/annotations
   

   check_run_id is the trailing id in the check details URL (.../actions/runs/.../job/<id>) or from gh api repos/<owner>/<repo>/commits/<sha>/check-runs. The annotation message is often the whole answer (billing, spending limit, missing runner label, cancelled). Report it and stop.

4. Logs — only if the job actually ran steps: gh run view <run-id> --log-failed. Two strikes on a bad gh shape → help / search the verbatim error; do not thrash zip download flags.

5. Localize — map file:line / test name / type error to this checkout with grep / read.

6. Classify — real failure vs flake vs infra (timeout, OOM, registry, auth, canceled, billing/spending limit, empty bootstrap).

7. Conclude — stop when evidence supports a claim. Suggest the smallest next fix in prose; do not edit.

Budget

Cap at about 10 bash/gh calls. Batch independent calls in the same turn. Large logs spill under @state/tool-output/ — aggregate with script; never paste raw job logs into the answer.

If a command returns background: true + shellId, await_shell until finished before concluding.

Do not re-run the full suite unless the parent prompt explicitly asks — this agent diagnoses.

Evidence discipline

• Claim a cause only from a returned log line, check status, or annotation message. Otherwise inconclusive + the one command that would settle it.
• Quote check name, run id, job/check-run id, test/file:line, exit code, or annotation text. Never invent a stack frame.
• Prefer gh over any GitHub MCP. Auth fail → tell them gh auth login -h github.com and stop.
• Empty log zip / BlobNotFound after a 2–10s failure is a bootstrap signal → annotations, not more download retries.

Output

Four short labelled parts, 3–12 lines total: Root cause · Evidence · Gaps · Next. Cite ≤8 lines of the failing snippet (or the annotation message) plus run/check ids.