version
1.2.2
GitHub stars
13

Install

/plugin install ci-cd-tools@pickled-claude-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.

Contents

Discovered from source

Skills 1

Fixing CI

Overview

This skill drives an iterative CI fix session: investigate the failure (via the Buildkite investigation skill), apply a fix, verify it locally, push, watch the new build, and iterate until green or until you've hit the iteration cap and need to step back.

The scope is the fix loop only — investigation is delegated to buildkite:investigating-builds, which already covers bktide snapshot, log reading, and failure-pattern recognition.

When to Use

  • You have a failing CI build and want to push fixes until it goes green
  • You want to verify changes locally before each push (saves CI cycles)
  • You're iterating on fixes across multiple builds and need to know when to step back

When NOT to Use

  • First-time "why did this fail" investigation with no fix-and-push intent → use buildkite:investigating-builds directly
  • Authoring or modifying pipeline YAML → use buildkite:developing-pipelines
  • GitHub Actions, CircleCI, or non-Buildkite CI

Input Contract

The skill needs to know what to fix. Any one of these inputs is sufficient:

  • build_url — A Buildkite build URL (e.g. https://buildkite.com/org/pipeline/builds/123)
  • pr — A GitHub PR number (resolves to its latest failing build for that branch)
  • branch — A git branch name (resolves to its open PR's latest failing build)

Resolving inputs

If the caller provides one of the above, use it directly. Otherwise:

  1. From cwd: read the current git branch (git branch --show-current) and look for an open PR (gh pr view --json number,headRefName). Then find the branch's latest failing build:
    • Work out the pipeline slug. It usually matches the repo name; a monorepo may name it after the main repo.
    • List the branch's builds with MCP buildkite:list_builds (branch: <branch>, detail_level: "summary"), or npx bktide@latest builds --format json --branch <branch> <org>/<pipeline>. Without --branch, bktide builds lists every branch, so filter on branch yourself.
    • On the newest build, check in order: overall state, job summary (passed/failed/broken), annotations, then logs for the failed jobs.
  2. If cwd doesn't resolve cleanly (no branch, no open PR, no failing build): the caller (slash-command wrapper or workflow agent) is responsible for either asking the user or failing with a clear message. This skill assumes resolution is done before its loop starts.

Step 1: Capture Initial State

Record the starting point:

  • Branch name: Current git branch
  • PR number: If applicable (gh pr view --json number)
  • Build number: The failing build (from input contract)
  • Failure count: Number of failed jobs (from a bktide snapshot of the build)

Announce:

"Starting CI fix session for branch <branch> (Build #). I see failed jobs. Let me investigate."

Step 2: Check Branch Freshness

Before diving into failures, check if the branch is up to date with main.

  1. Check if behind main:

    git fetch origin main
    git rev-list --count HEAD..origin/main
    
  2. If behind by more than 0 commits, the failures might already be fixed in main. Decide:

    • Merge main now (handle conflicts)
    • Skip and investigate current failures

In autonomous mode (e.g. invoked from a workflow agent), default to merging main if behind. The slash-command wrapper asks the user.

Step 3: Investigate (Delegated)

Use the buildkite:investigating-builds skill to investigate the failing build. The skill's tool hierarchy applies: bktide snapshot first, then other bktide commands, then MCP tools as fallback.

After investigation, you should have:

  • The failing job(s) and their logs
  • A pattern category (test failure, lint, type error, lockfile, stale branch, infra, flake)
  • Files likely involved

Step 4: Categorize and Plan Fixes

Group failures by type:

CategorySignsTypical Fix
Stale branchTests pass on mainMerge main, resolve conflicts
Gemfile.lock issuesChecksum errors, missing gemsRegenerate from main (see references/common-fix-patterns.md)
Test failuresRSpec/Jest failures with stack tracesFix the test or code
Type errorsSorbet/TypeScript errorsFix type annotations
Lint errorsRubocop/ESLint failuresAuto-fix or manual fix
Flaky testsPasses locally, fails in CIInvestigate timing/isolation; do NOT fix-and-push, surface as flake

For each category, plan: what to fix, files involved, how to verify locally.

If the failure is flake or infra (CI runner/queue/dependencies), stop. Surface and exit. Don't push fixes for problems we don't understand.

Step 5: Pre-Push Verification

Always verify locally before pushing. Saves CI cycles, catches misfires.

Ruby/Rails projects

bin/rspec <spec_files>
bin/srb tc <modified_files>      # if using Sorbet
lefthook run pre-commit          # if using lefthook
pre-commit run --files <modified_files>  # if using pre-commit framework

JavaScript/TypeScript projects

npm test -- <test_files>         # or: yarn test <test_files>
npx tsc --noEmit                 # if using TypeScript
npm run lint

General

Run whatever the failing CI step ran. Check the failed job's command in the logs.

Step 6: Push and Monitor

After local verification passes:

  1. Commit with a message referencing the build:

    Fix <failure type> from build #<number>
    
    <brief description of what was wrong and how it was fixed>
    
  2. Push:

    git push
    
  3. Monitor the new build. The branch's newest build can still be the previous one right after the push, and watching an old failed build exits 1 at once, which reads as a failed fix. Confirm the build is for HEAD before watching; run the whole block in the background:

    sha=$(git rev-parse HEAD); build=
    for _ in $(seq 20); do  # about 5 minutes for the build to appear
      n=$(npx bktide@latest builds <org>/<pipeline> --branch <branch> --count 1 --format json --no-cache | jq -r '.builds[0].number // empty')
      if [ -n "$n" ] && [ "$(npx bktide@latest build "<org>/<pipeline>#$n" --format json --no-cache | jq -r .commit)" = "$sha" ]; then build=$n; break; fi
      sleep 15
    done
    if [ -n "$build" ]; then npx bktide@latest build "<org>/<pipeline>#$build" --watch; else echo "no build for $sha" >&2; (exit 2); fi
    

    Exit 0 means passed, 1 means anything else (failed, canceled, or --timeout <minutes> reached, default 30; the timeout prints Timeout reached), 2 means no build for HEAD appeared. MCP buildkite:wait_for_build (timeout: 1800, poll_interval: 30) also works where a Buildkite MCP server is connected. Don't poll in the foreground.

  4. On completion: pass → summarize and exit. Fail → go to Step 7.

Step 7: Iterate if Still Failing

Compare with the previous build:

  • Same failures → fix didn't work
  • Different failures → progress, but new issues
  • Fewer failures → partial progress

Iteration cap: 3. After 3 iterations without going green, step back. Don't keep trying. Exit with a summary covering:

  • What was tried
  • What's still failing
  • A guess at why progress stalled (deeper architectural issue, branch too diverged, etc.)

Three iterations is a heuristic, not a hard rule — if iterations 1 and 2 made clear progress on different failures and iteration 3 is on the last remaining issue, one more attempt is reasonable. If the same failure persists across all three, stop.

Step 8: Session Summary

When CI passes (or session ends), summarize:

  • Branch: <branch>
  • Started: Build # ( failures)
  • Ended: Build # (passed / still failing)
  • Iterations:
  • Fixes applied: brief list
  • Patterns encountered and how each was resolved

Common Fix Patterns

Detailed patterns for recurring issues (Gemfile.lock checksum, merge conflicts, year-boundary, test-helper changes) live in references/common-fix-patterns.md.

Guidelines

  • Always verify locally before pushing — saves CI cycles
  • One fix at a time when possible — easier to identify what worked
  • Know when to stop — sometimes fresh eyes are needed (3-iteration cap)
  • Check main first — the issue might already be fixed there

Commands 1

Fix CI Failures

Iteratively fix a failing Buildkite CI run. This command resolves what to fix, then loads the ci-cd-tools:fixing-ci skill to drive the loop (verify locally → push → check → iterate).

Arguments

  • URL (optional): Buildkite build URL to start with
  • If no URL provided, infer from current branch / open PR

Step 1: Resolve the Input

Determine the build to fix using this priority order:

  1. URL argument provided → use it directly. The bktide snapshot tool parses any Buildkite URL.
  2. No URL, current git branch has an open PR → resolve via gh pr view --json number,headRefName, then find the branch's latest failing build:
    • Work out the pipeline slug. It usually matches the repo name; a monorepo may name it after the main repo.
    • List the branch's builds with MCP buildkite:list_builds (branch: <branch>, detail_level: "summary"), or npx bktide@latest builds --format json --branch <branch> <org>/<pipeline>. Without --branch, bktide builds lists every branch, so filter on branch yourself.
    • On the newest build, check in order: overall state, job summary (passed/failed/broken), annotations, then logs for the failed jobs.
  3. No URL, current branch but no PR → ask the user for either the build URL or the PR number.
  4. Detached HEAD or no clear branch → ask the user.

Once resolved, you have one of: build_url, pr number, or branch name.

Step 2: Optional Tracking Document

For complex or multi-day debugging sessions, offer to create a tracking document:

"Would you like me to create a tracking document for this CI fix session? Useful for multi-day debugging or handoff."

If yes, create docs/plans/ci-fix-<branch-slug>.md with this template:

# CI Fix Workflow: <branch-name>

## Session: <YYYY-MM-DD>

### Initial State
- Branch: `<branch-name>`
- PR: #<pr-number>
- Latest failing build: <build-number> (<N> failures - <brief description>)

---

## Iteration 1: <Title>

**Build:** <number> (<status>)
**Failures:** <count> (<pattern description>)

**Root cause:**
<1-2 sentences>

**Fix:**
<Code changes or commands>

**Verification:**
\`\`\`bash
<local verification commands>
\`\`\`

**Commit:** `<sha>` - "<message>"
**Next build:** <number>

---

## Summary of Issues Fixed

| Build | Issue | Root Cause | Fix |
|-------|-------|------------|-----|
| <num> | <issue> | <cause> | <fix> |

## Next Steps

- [ ] <remaining items if session ends before green>

If no, skip and proceed.

Step 3: Run the Fix Loop

Use the ci-cd-tools:fixing-ci skill, passing the resolved input from Step 1. The skill drives the loop: branch-freshness check → delegate investigation → categorize → verify locally → push → monitor → iterate (max 3 iterations).

When the skill returns (CI green, iteration cap hit, or classified as flake/infra/unknown), surface the session summary to the user.

Sponsors

Details

Marketplace
technicalpickles/pickled-claude-plugins
Source
plugins/ci-cd-tools
Category
Community

More from technicalpickles/pickled-claude-plugins

All 26