AGENT SKILL

ci-triage

Find and diagnose RED CI with the gh CLI — answer "is anything failing?" and "why?" correctly, without being handed a URL. Invoke (via the Skill tool) whenever you need to check whether a branch, commit, or PR is green, whenever someone reports failing CI, before cutting a release, and before claiming any commit is green. THE FAILURE THIS SKILL EXISTS TO PREVENT: `gh run list` reports a RUN-level `conclusion`, and a run whose rollup is `cancelled` can contain a job whose conclusion is `failure` — so filtering runs on `conclusion=="failure"` silently misses real red, and taking the latest run per workflow hides an older failed run on the same SHA. The authoritative instrument is the commit's CHECK-RUNS, which is what the GitHub UI renders. Pairs with `ci-watch` (blocking until a run is terminal) and `ci-adhoc-test` (running a probe on a real OS).

License 许可
MIT
所属仓库
nubjs/nub
最近更新
2026-11-14
Stars
★ 4.4k
Forks
71

01 前言 Front Matter

name
ci-triage
description
Find and diagnose RED CI with the gh CLI — answer "is anything failing?" and "why?" correctly, without being handed a URL. Invoke (via the Skill tool) whenever you need to check whether a branch, commit, or PR is green, whenever someone reports failing CI, before cutting a release, and before claiming any commit is green. THE FAILURE THIS SKILL EXISTS TO PREVENT: `gh run list` reports a RUN-level `conclusion`, and a run whose rollup is `cancelled` can contain a job whose conclusion is `failure` — so filtering runs on `conclusion=="failure"` silently misses real red, and taking the latest run per workflow hides an older failed run on the same SHA. The authoritative instrument is the commit's CHECK-RUNS, which is what the GitHub UI renders. Pairs with `ci-watch` (blocking until a run is terminal) and `ci-adhoc-test` (running a probe on a real OS).

03 SKILL.md 正文

Investigating CI

ci-watch answers "has it finished, and did it pass?" for one run you are waiting on. This skill answers the two questions you get asked cold: "is anything red?" and "why is this red?" — starting from a branch name or a commit, never from a URL someone hands you.

The rule

Never answer "is it green?" from run-level conclusion. Query the commit's check-runs.

A GitHub Actions run rolls up its jobs into one conclusion, and that rollup is lossy in the exact case that matters:

What happened Run conclusion Job conclusions gh run list shows
A job failed failure one failure ✅ red — you see it
A job failed inside a run that also got cancelled cancelled one failure ❌ nothing — filtered out
Superseded by cancel-in-progress cancelled all cancelled ❌ nothing (correctly)

The middle row is real and it is what the UI paints red on the commit. It happens whenever a workflow has an aggregation/gate job that runs after its matrix legs: concurrency: cancel-in-progress cancels the legs, the gate still runs, sees cancelled, and fails. The run rolls up cancelled; the gate job is failure.

The one command that is always correct

SHA=$(git rev-parse origin/main)   # or a PR head, or any commit
gh api repos/nubjs/nub/commits/$SHA/check-runs --paginate \
  --jq '.check_runs[] | select(.conclusion != "success" and .conclusion != "skipped" and .conclusion != "neutral")
        | "\(.conclusion // .status) | \(.name) | \(.html_url)"'

Empty output means genuinely green. Anything else is exactly what a human sees in the Actions tab, with a clickable URL per finding. This endpoint is the source of truth because it is what the UI renders — run-level data is downstream of it.

Counting, and the --paginate trap

--paginate runs --jq once PER PAGE. A per-item filter like the one above is fine — each page emits its own lines and they concatenate. But any aggregation (length, add, group_by) silently returns one result per page instead of a total:

# WRONG — prints "0" then "1" on a 2-page response. Reads like 0 if you only look at line 1.
gh api repos/nubjs/nub/commits/$SHA/check-runs --paginate --jq '[.check_runs[]|select(.conclusion=="failure")]|length'

Use --slurp to get one array across pages, and pipe to external jq — --slurp is rejected together with --jq:

# RIGHT — one number for the whole commit.
gh api repos/nubjs/nub/commits/$SHA/check-runs --paginate --slurp \
  | jq '[.[].check_runs[] | select(.conclusion=="failure")] | length'

This is not hypothetical: a release commit here carried 192 check-runs across 2 pages, and the naive count printed 0 on the first line.

Diagnosing one failure

Given a failing check, get the run, then the job, then the log — in that order.

gh run view <run-id> --json name,status,conclusion,headBranch,headSha,event,createdAt
gh run view <run-id> --json jobs --jq '.jobs[] | "\(.conclusion // .status) | \(.name)"'
gh run view <run-id> --log-failed > /tmp/fail.log 2>&1; echo "EXIT=$?"
sed -e 's/\x1b\[[0-9;]*m//g' /tmp/fail.log | grep -viE '^\s*$' | tail -40

Strip ANSI escapes (sed -e 's/\x1b\[[0-9;]*m//g') or the log is unreadable. --log-failed returns only failing steps, which is usually 40 lines rather than 40,000.

Read the event and createdAt fields before concluding anything. They tell you whether the run was superseded, and by what.

Superseded-run triage — is this red REAL?

A red check on a commit is not automatically a broken commit. Decide with this:

  1. List every run of that workflow on that SHA. More than one is the tell.
    gh run list --workflow <file>.yml --limit 30 \
      --json databaseId,status,conclusion,headSha,headBranch,event,createdAt \
      --jq '.[] | select(.headSha=="'"$SHA"'") | "id=\(.databaseId) | \(.conclusion // .status) | \(.event) | \(.createdAt)"'
    
  2. If a later run of the same workflow on the same SHA is fully green, the code is fine — the red one was superseded. The commit still shows red, which is a workflow defect worth fixing, not a code defect.
  3. Check the concurrency group. group: ${{ github.workflow }}-${{ github.ref }} means a schedule run and a push run on main share a group and will cancel each other, because both carry refs/heads/main. That is a common and surprising source of self-inflicted red.

The gate-job anti-pattern, and its fix

A gate job that aggregates matrix legs must treat cancelled as not a verdict. This is wrong:

[[ "$smoke" == "success" || "$smoke" == "skipped" ]] || { echo "smoke failed"; exit 1; }

A superseded run sets smoke=cancelled, so the gate fails and paints the commit red forever. Accept cancelled too — it does not mask a real failure, because a genuinely failing leg aggregates to failure, not cancelled:

[[ "$smoke" == "success" || "$smoke" == "skipped" || "$smoke" == "cancelled" ]] || { echo "smoke failed"; exit 1; }

What NOT to do

  • Do not filter gh run list on conclusion=="failure" and call the absence of hits "green". That is the whole bug this skill exists for.
  • Do not take the latest run per workflow (group_by(.name) | max_by(.createdAt)). A later scheduled run can hide an earlier failed push run on the same SHA.
  • Do not trust --branch main alone to find everything; a check can be attached by an app or a workflow_run. Check-runs on the SHA catch all of them.
  • Do not conclude "not failing" from a bot issue being absent. The trunk-red bot files on its own schedule and its silence proves nothing.
  • Do not read an exit code through a pipe (gh ... | head then $?). Redirect, capture $? on its own line, then inspect.

Reporting a finding

State the commit, the check name, the run URL, whether a later run on the same SHA passed, and the mechanism. "CI is red" without those is not a diagnosis. If a superseded run is the cause, say so plainly and name the fix — the commit is still red in the UI and someone has to look at it.

04 同仓库更多 Skills

nubjs
nubjs/nub

nub

暂无简介

★ 4.4k
nubjs
nubjs/nub

nub

This project uses nub, a single Rust CLI that runs on the project's installed Node and replaces the everyday Node toolchain. ALWAYS prefer nub over node, bun, npm, npx, pnpm, and yarn for: executing JS/TS files, running package.json scripts, the npx-equivalent, installing dependencies, watch mode, and Node version management. Surfaces whenever you would otherwise reach for node/bun/npm/npx or a package manager.

★ 4.4k
nubjs
nubjs/nub

worktree

Create and manage isolated git worktrees for parallel build/test/landing work on the nub repo. Invoke (via the Skill tool) whenever you need a fresh worktree to land a change, when you want to know what `.worktreeinclude` does or how to add an entry, or when cleaning up after a merge. Encodes the one-command setup (`nub scripts/new-worktree.ts <slug>` or `node …`) that bakes in the proven recipe — worktree off origin/main (vendor/aube is plain in-tree files now, no submodule init), the shared CARGO_TARGET_DIR (`~/.cache/nub/shared-target`) that all worktrees reuse, and applying `.worktreeinclude` — plus the eagerly-pull-the-shared-tree discipline and the safe cleanup path. Pairs with the `dev-loop` build skill.

★ 4.4k
nubjs
nubjs/nub

windows-vm-test

Run ad-hoc Nub tests and debugging probes in the maintainer's existing local Windows 11 ARM64 QEMU/HVF VM when its external disk and runbook are present. Use for interactive win32-arm64 or Windows-on-ARM x64-emulation checks; use ci-adhoc-test for true x64-native behavior or when the local VM is unavailable.

★ 4.4k
nubjs
nubjs/nub

visual-review

Verify UI/layout/styling changes are correct by computing occlusion, clipping, and alignment from the browser's resolved paint order via the chrome-devtools MCP `evaluate_script` tool — instead of eyeballing a flat screenshot. Invoke BEFORE declaring any UI, site, or styling/layout change correct. Screenshots have no depth buffer, so z-index/occlusion/clip bugs are exactly where "just look at it" fails; the `evaluate_script` routines below turn those fuzzy visual judgments into deterministic measurements — including optical center-of-mass, which measures the glyph ink's true visual center so differently-sized labels can be aligned by more than eye.

★ 4.4k
nubjs
nubjs/nub

type-declarations

Add, audit, or update @nubjs/types declarations for Nub runtime APIs. Use whenever Nub adds or changes a user-visible global, built-in method, module loader type, or TC39 proposal; when TypeScript or @types/node gains an overlapping declaration; and before every release to reconcile runtime changes since the previous tag. Covers conflict-safe global augmentation, compiler-version routing, fixture matrices, and package verification.

★ 4.4k