Skip to content
Skills Library
DevOps & cloud · Analysis

ci-debugging

/ci-debugging

Systematic CI/CD failure diagnosis with hypothesis-first approach, environment delta analysis, and anti-patterns. Use when CI fails, pipelines break, or the user says "CI is failing", "build broke", "pipeline error", or "tests pass locally but fail in CI".

Licence
MIT
Last repository change
14.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Systematic CI/CD failure diagnosis with hypothesis-first approach, environment delta analysis, and anti-patterns. Use when CI fails, pipelines break, or the user says "CI is failing", "build broke", "pipeline error", or "tests pass locally but fail in CI".

Triggers from the description

CI is failingbuild brokepipeline errortests pass locally but fail in CI
Original author description

Systematic CI/CD failure diagnosis with hypothesis-first approach, environment delta analysis, and anti-patterns. Use when CI fails, pipelines break, or the user says "CI is failing", "build broke", "pipeline error", or "tests pass locally but fail in CI".

How it works

  1. Overview
  2. Constraints
  3. Process
  4. Anti-Patterns
  5. Integration
Original SKILL.md headings · 100 lines, 816 words
SKILL.md preview
---
name: ci-debugging
description: Systematic CI/CD failure diagnosis with hypothesis-first approach, environment delta analysis, and anti-patterns. Use when CI fails, pipelines break, or the user says "CI is failing", "build broke", "pipeline error", or "tests pass locally but fail in CI".
role: worker
user-invocable: true
---

# CI Debugging

## Overview

CI failures are diagnosed systematically, not by guessing. This skill prevents the common anti-pattern of "just re-run it" by enforcing a hypothesis-first approach.

## Constraints

- Never suggest "retry the build" as a first action
- Never add retry logic to "fix" a flaky test
- Never push a speculative fix without reproducing locally first
- Always form a hypothesis before making changes

## Process

### 1. Read the failure

Read the full CI log output. Identify:

- **What failed**: test, lint, typecheck, build, deploy, or infrastructure
- **When it started failing**: this commit, recent merge, or intermittent
- **Error message**: exact error text, not a summary

### 2. Form a hypothesis

Before touching any code, state a hypothesis: "I believe X is failing because Y, and I can verify by Z."

Good hypotheses are specific and falsifiable:

- "The test fails because the database migration added a NOT NULL column and the test fixture doesn't set it"
- "The build fails because Node 20 dropped support for this API and CI upgraded last week"

Bad hypotheses:

- "Something is wrong with the tests"
- "CI is flaky"

**Graph-assisted hypothesis grounding.** Prefer CodeGraph/Repowise over raw
`Grep` for locating the actual source/test code behind the failing log line
before stating the hypothesis. See
[`knowledge/codegraph-vs-graphify.md`](../../knowledge/codegraph-vs-graphify.md)
for tool selection and the fallback contract.

### 3. Environment delta analysis

Compare local vs CI environments using this checklist:

| Factor | Check |
| -------- | ------- |
| **Runtime version** | Node, Python, Go, JDK, Ruby, .NET — exact version match? |
| **OS and architecture** | macOS vs Linux, x86 vs ARM? |
| **Dependency resolution** | Lockfile committed? Registry differences? Private packages accessible? |
| **Environment variables** | All required vars set? Secrets populated? |
| **Parallelism** | Tests run in parallel in CI but serial locally? Shared state? |
| **Memory/CPU** | CI runner constrained? OOM killer? |
| **Network** | External service dependencies? DNS resolution? Firewall rules? |
| **Filesystem** | Case sensitivity (macOS vs Linux)? Temp directory permissions? Path length? |
| **Timezone/locale** | Date formatting tests? Locale-dependent string comparisons? |
| **Docker** | Image tag `latest` drifted? Layer cache stale? Build context different? |

### 4. Reproduce locally

Before fixing, reproduce the failure locally:

1. Match the CI environment as closely as possible (same Node version, same env vars)
2. Run the exact failing command from the CI log
3. If it passes locally, the delta from step 3 is the cause

### Monitoring long-running jobs

Before calling `Monitor` on a job whose completion time matters:

1. Check whether a duration signal exists (prior run duration from CI history/logs, a known job-type baseline, or an explicit estimate the user gave).
2. If a signal exists, set `timeout_ms` to a safety margin over that estimate (e.g., double it), capped at the tool's documented max (3,600,000 ms / 1 hour).
3. If no signal exists, don't guess — set `persistent: true` and pair it with a command that exits on the job's own terminal state (success/failure/timeout), never an unbounded `tail -f`/`while true` with no exit condition, so the monitor self-terminates instead of requiring a manual `TaskStop`.
4. Never silently re-arm after a timeout without noting the estimate was wrong; if a re-arm is needed, widen the estimate or switch to `persistent: true` rather than repeating the same timeout.
5. If the wait is handled by a scheduled wake-up instead of `Monitor` (no stream to watch, or a backstop against a missed notification), follow the calling contract in [`knowledge/long-run-waiting.md`](../../knowledge/long-run-waiting.md) — an arm/re-arm call needs the instruction to replay plus a reason, and standing down is a `stop`-only call. A malformed call arms no timer at all.

### 5. Fix and verify

Fix the root cause. Verify the fix locally. Push and confirm CI passes.

## Anti-Patterns

| Anti-pattern | Why it's wrong | What to do instead |
| ------------- | --------------- | ------------------- |
| Retry the build | Masks the root cause, wastes CI minutes | Read the logs, form a hypothesis |
| Add retry/sleep to test | Hides race conditions, makes tests slow | Fix the shared state or ordering issue |
| Skip the failing test | Reduces coverage, hides regressions | Fix the test or the code |
| Push a speculative fix | Pollutes git history, might not work | Reproduce locally first |
| Blame "flaky CI" | Normalizes unreliable pipelines | Every failure has a cause — find it |
| Re-arming a timed-out Monitor call | Wastes a round-trip and leaves a gap in coverage | Estimate `timeout_ms` from a duration signal, or use `persistent: true` (see Monitoring long-running jobs) |

## Integration

- **Platform Engineer agent**: Collaborates on infrastructure-level CI issues
- **QA Engineer agent**: Collaborates on test isolation and fixture problems
- **Systematic Debugging skill**: Uses the same hypothesis-first methodology

Versions

RepositoryScoreLicence
This page · bdfinst/agentic-dev-team90MIT
kcenon/claude-config100BSD-3-Clause
citypaul/.dotfiles100MIT

Database snapshot: 13.11.2026 · package version f8ee3b86360a (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100debug-operator
    TRIGGER when operator errors appear or user reports broken behavior. Systematic diagnosis workflow.
  • 100environment-configuration-delta
    Record which settings differ between the environment you test and the one that matters, because a check passing in staging says nothing about production behaviour. Use when the assessment runs against a non-production environment while findings will apply to production
  • 100debugging-and-error-recovery
    Guides systematic root-cause debugging. Use when tests fail, builds break, something that worked yesterday broke, behavior doesn't match expectations, or you encounter any unexpected error. Use when you need to figure out what broke and why — a systematic approach to finding and…
  • 100ci-failure-fix
    Diagnose and fix a failing CI pipeline (GitHub Actions, GitLab CI, CircleCI, Jenkins...). Use when the user says "CI is red", "the build fails", "checks are failing on my PR", "it passes locally but fails in CI", or pastes a CI log.
  • 100debug-failing-ci
    Use when a ticket is about a red pipeline — a job that fails in CI but passes locally, a build that broke on the default branch, a flaky or slow workflow — and the fix must be the real cause, not a retry or a skipped step. Invoke for "CI is red", "works on my machine", "the…
  • 100ferrox-systematic-debugging
    Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.