ci-debug

name	ci-debug
license	MIT
compatibility	Claude Code 2.1.220+ — uses `gh` CLI for GitHub Actions log inspection. Works in interactive sessions and headless `claude -p --bare` invocations (e.g. /ork:ci-sentinel).
description	Diagnose a failing CI run against an 11-pattern playbook. Classifies the failure, cites the relevant memory entry, proposes the exact fix command — but NEVER applies without explicit user approval. Use when a specific PR check or GitHub Actions run failed and you want a diagnosis instead of speculation. Don't use for org-wide CI sweeps (that's /status) or for app-level test failures (the playbook is CI-infra-specific).
argument-hint	<PR-number | run-URL | job-URL>
context	fork
background	false
version	0.2.0
disable-model-invocation	false
author	OrchestKit
tags	["ci","github-actions","debugging","classification","propose-dont-apply"]
user-invocable	true
allowed-tools	["Bash","Read","Grep","Glob"]
skills	["github-operations","memory"]
complexity	medium
persuasion-type	guidance
model	sonnet
metadata	{"category":"workflow-automation","origin":"/insights audit 2026-05-11 — recurring CI-debug pattern across 12 sessions in 3 weeks"}
triggers	{"keywords":["ci failure","build red","actions failed","workflow failed","PR check failed","CI broken"],"examples":["PR #1842 build is red, what happened?","/ci-debug 822","/ci-debug https://github.com/owner/repo/actions/runs/12345"],"anti-triggers":["what's failing across the org","test broke in my code"]}
paths	[".github/workflows/**/*.yml"]

/ci-debug — classify a failing CI run

Direct response to the recurring CI-debug pattern surfaced by /insights: ~12 sessions in 3 weeks doing the same classification dance. This skill encodes the 11 patterns so the dance becomes a lookup.

Input

User invokes with one of:

• PR number: /ci-debug 822 (default repo from context; ask if ambiguous)
• Run URL: /ci-debug https://github.com/owner/repo/actions/runs/12345
• Job URL: /ci-debug https://github.com/owner/repo/actions/runs/X/job/Y

Execution

1. Resolve the failing job

# From PR number:
gh pr checks <n> --repo <owner>/<repo> --json bucket,link,name \
  --jq '.[] | select(.bucket=="fail") | "\(.name)|\(.link)"'

# From run URL:
gh api repos/<owner>/<repo>/actions/runs/<run-id>/jobs \
  --jq '.jobs[] | select(.conclusion=="failure")
                | {id, name, runner_name, started_at, completed_at,
                   steps: [.steps[] | select(.conclusion=="failure") | {name, number}]}'

If multiple jobs failed, pick the one with the shortest duration — root cause is usually the first failure; later jobs cascade.

No job in the fail bucket but a check won't settle? If gh pr checks shows zero fail-bucket entries yet a status sits in pending that never resolves (and gh pr view --json mergeStateStatus returns UNSTABLE while mergeable=MERGEABLE), this is a stuck external status, not a failure — jump straight to Pattern #11. There is no failing log to fetch; classify on the commit-status metadata (gh api repos/<o>/<r>/commits/<sha>/status).

2. Fetch the failing log

gh api repos/<owner>/<repo>/actions/jobs/<job_id>/logs 2>&1 \
  | grep -iE '(error|fail|ERR_|CONFLICT|Process completed with exit code)' \
  | head -30

Capture the FIRST distinct error message (later lines often echo).

3. Classify against the playbook