git:20260901.75010d8 to git:20261028.c2c0bcf

---

name: investigating-builds

description: Use when the user is working with an existing Buildkite CI run and wants to understand, diagnose, or act on it. Strong signals: a buildkite.com URL, the word "buildkite", the `bk` CLI, the `bktide` tool, or a reference to a specific pipeline, build, or job. Covers intents like: "why did this build fail", "what's flaking", "summarize pass/fail rates across recent builds", "pull logs for this job", "figure out the exact command CI ran so I can reproduce it locally" (often via docker-compose), "why didn't my downstream build trigger", and debugging `bk`/`bktide` behavior itself (auth failures, query errors, sandbox issues). Do NOT use for authoring pipeline YAML or adding pipeline steps (that's `buildkite:developing-pipelines`). Do NOT use for meta-work on the Claude buildkite plugin itself (editing SKILL.md, reviewing pickled-claude-plugins PRs, adding reference docs under the plugin's directory). Do NOT use for GitHub Actions, PR review, app code changes, git merge conflicts, or local `bk` config (`~/.bk/config.yml`) that don't involve investigating an actual build. This skill reads and investigates CI runs that already exist.

---

# Working with Buildkite Builds

First, see the state distribution:

```bash

jq -r '.steps[].state' ./tmp/bktide/snapshots/<org>/<pipeline>/<build>/manifest.json | sort | uniq -c | sort -rn

```

**Only these are real failures:**

- Steps with state `FINISHED` (or `FAILED`) AND non-zero `exit_status`

**These are NOT failures — do not count or investigate them:**

- **BROKEN** — Downstream dependencies that never ran. Auto-resolve when the root failure is fixed.

- **RUNNING** — Still in progress.

- **WAITING** / **SCHEDULED** — Haven't started yet.

- **CANCELED** — Manually or automatically canceled.

Find actual root failures:

```bash

jq -r '.steps[] | select((.state == "FINISHED" or .state == "FAILED") and .exit_status != null and .exit_status != 0) | "\(.id): \(.label) (exit \(.exit_status))"' ./tmp/bktide/snapshots/<org>/<pipeline>/<build>/manifest.json

```

**Example:** A summary reads "466 steps: 43 passed, 397 failed, 361 running" — filtering reveals 1 actual failure (e.g. codeownership validation) and 396 BROKEN dependents. Fix the root and everything else passes.

```javascript

mcp__MCPProxy__call_tool('buildkite:get_build', {

org_slug: '<org>',

pipeline_slug: '<pipeline>',

build_number: '<build-number>',

detail_level: 'detailed',

job_state: 'failed',

});

```

```javascript

mcp__MCPProxy__call_tool('buildkite:get_logs', {

org_slug: '<org>',

pipeline_slug: '<pipeline>',

build_number: '<build-number>',

job_id: '<job-uuid>',

});

```

**Common Issues:**

- **"job not found" error**: You likely provided a step ID instead of a job UUID. Step IDs come from URLs (`sid=019a5f...`). Job UUIDs come from `get_build` API responses.

- **Empty logs**: The job may not have started yet. Check the job's `state` field first.

```javascript

mcp__MCPProxy__call_tool('buildkite:unblock_job', {

org_slug: '<org>',

pipeline_slug: '<pipeline>',

build_number: '<build-number>',

job_id: '<job-id>',

fields: {}, // Optional form fields if the block step has inputs

});

```

Some events that feel like they should start a new build don't. GitHub's "ready for review" event, for example, does not trigger a new Buildkite build — only pushes do. If you need a build for the current state without a new commit, don't push an empty commit as a workaround; trigger one directly:

```bash

# Start a new build (auto-detects org/pipeline/commit/branch from the current git checkout)

npx bktide@latest build create

# Watch it through to completion

npx bktide@latest build create --watch

# Re-run an existing build with its original commit/branch/message

npx bktide@latest build rebuild <org>/<pipeline>/<build-number>

npx bktide@latest build rebuild <buildkite-build-url>

```

Flags (`--commit`, `--branch`, `--message`, `--env`) override git auto-detection; run `bktide build create --help` for the full list. This is the one write operation bktide supports — it's the direct replacement for `bk build create`/`bk build retry`, which the buildkite tool-preference hook blocks in favor of this command.