Files
skills/skills/kvb-ci-artifacts/SKILL.md
T
Kevin Veen-BirkenbachandClaude Opus 5.5 de8823e239 feat(kvb-org-operator): list every command only the operator can run
kvb-org-operator collects the steps that wait on a human across all agents: commands under a deny or unconfirmed ask rule, anything outside the sandbox (keys, permission settings, foreign hosts, root), steps the agent rules reserve for the operator (push, release, tags, reboot) and human-bound ones (hardware key, login, second factor, purchase, decision). Sources are the own session, the kvb-org-rasci register and one message per live peer. Done steps drop out, duplicates merge, the rest is ordered by dependency and printed as a table plus one copyable bash block, then recorded as operator/<slug> register tasks. Agents never run a listed command or hand it to a peer. Operator order 2026-11-03; four descriptions trimmed for the listing budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-03 13:57:14 +01:00

79 lines
3.6 KiB
Markdown

---
name: kvb-ci-artifacts
description: >
Pull failed job logs (also mid-run), clustered by error line, and the
cause-holding artifacts out of a CI run. Trigger when a CI failure needs
explaining, and from triage.
---
A job log tells you what broke. An artifact tells you why. Investigating a CI
failure without downloading its artifacts is guessing with extra steps.
## Getting the log
For a GitHub Actions run, one call does it:
${CLAUDE_SKILL_DIR}/scripts/ci_failures.py <RUN_ID> [--repo <owner>/<repo>] [--artifacts]
It prints how far HEAD moved since the run's commit, saves every finished
failed job's log to `/tmp/ci-logs-<run>/` (colour stripped, even while the run
is still in progress), and clusters the jobs by the normalised error line that
ended them. Jobs still running are listed, not fetched: their API log can stop hours
early. The clustering is a heuristic; check each boundary against the logs.
Grep the saved files repeatedly. Re-fetching a log to find the line you just
lost costs minutes; grepping the saved copy costs milliseconds.
## Getting the artifacts
gh api /repos/<owner>/<repo>/actions/runs/<RUN_ID>/artifacts --paginate \
--jq '.artifacts[] | "\(.name)\t\(.size_in_bytes)"'
gh run download <RUN_ID> --repo <owner>/<repo> -n <NAME> -D <DIR>
Choose by content, not by name length:
- **Rescue / diagnostics bundles** carry the reverse-proxy access and error log,
the per-service and per-container logs, the journal, and the event stream.
This is where causes live. Prefer them.
- **Test-report bundles** (Playwright and friends) are mostly video and traces
and can run to hundreds of megabytes for one assertion string. Pull one only
when you need the assertion text or the error-context file.
- **Inventory / runtime dumps** settle "what was actually deployed" questions.
Inside a rescue bundle, read in this order: the reverse-proxy log (it shows
status code, upstream, and time-to-response for the exact failing request), the
application container log, then the journal and event stream for restarts and
OOM kills.
An access-log line is a timing witness. A `499` means the *client* gave up; the
server was still working. A `504` or an `upstream timed out ... while reading
upstream` means your backend never answered. `ReqTime` versus `UpstreamTime`
tells you whether the proxy or the upstream burned the seconds.
## Grep hygiene
Two failure modes turn a search into a false conclusion:
- **Clustered flags silently change the pattern.** Write them separately —
`grep -r -a -i -l -F "needle" dir/`, not `-ariel`. A cluster where one letter
takes an argument consumes your pattern and searches for something else, and
the run still exits successfully.
- **Substring matches lie.** A protocol token like `h2c` matches inside
`veth2cb3f8c`; a short id matches inside a hash. Before concluding anything
from a hit, print its context (`grep -o ".\{30\}needle.\{30\}"`) and look at
it. Before concluding anything from a *miss*, prove the command was
well-formed by searching for a string you know is present.
Binary-ish logs need `-a`, or grep reports "binary file matches" and you see
nothing.
## Rules
- Download before theorising. Do it even when the job log looks conclusive: a
log that explains the symptom rarely explains the cause.
- Quote literally, with the file path and line number. Never paraphrase a log
line you did not read, and never reconstruct one from memory.
- A negative result is a finding only when the search was verified sound.
- "The artifact does not settle this" is a legitimate answer. Say it instead of
filling the gap with a plausible mechanism.