Skip to content
Skills Library
DevOps & cloud · Analysis

ci-debugging

/ci-debugging

Systematic CI/CD failure diagnosis using hypothesis-first investigation, local reproduction, and environment delta analysis. Use when a CI pipeline, GitHub Actions workflow, or build job fails; when tests pass locally but fail in CI; when diagnosing flaky tests, timeouts, or red pipelines; or when the user says "CI is failing", "the build is broken", or "works on my machine".

Repository
.dotfiles ↗
Licence
MIT
Last repository change
02.10.2026

Assessment and security

100/ 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.
Content35 / 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 02.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 using hypothesis-first investigation, local reproduction, and environment delta analysis. Use when a CI pipeline, GitHub Actions workflow, or build job fails; when tests pass locally but fail in CI; when diagnosing flaky tests, timeouts, or red pipelines; or when the user says "CI is failing", "the build is broken", or "works on my machine".

Triggers from the description

CI is failingthe build is brokenworks on my machine
Original author description

Systematic CI/CD failure diagnosis using hypothesis-first investigation, local reproduction, and environment delta analysis. Use when a CI pipeline, GitHub Actions workflow, or build job fails; when tests pass locally but fail in CI; when diagnosing flaky tests, timeouts, or red pipelines; or when the user says "CI is failing", "the build is broken", or "works on my machine".

How it works

  1. Getting the Data
  2. Hypothesis-First Diagnosis
  3. Local Reproduction
  4. Environment Delta Analysis
  5. Read the Full Error
  6. Fix Verification
  7. Anti-Patterns
  8. Proving Flakiness
  9. Handoff
Original SKILL.md headings · 117 lines, 879 words
SKILL.md preview
---
name: ci-debugging
description: Systematic CI/CD failure diagnosis using hypothesis-first investigation, local reproduction, and environment delta analysis. Use when a CI pipeline, GitHub Actions workflow, or build job fails; when tests pass locally but fail in CI; when diagnosing flaky tests, timeouts, or red pipelines; or when the user says "CI is failing", "the build is broken", or "works on my machine".
---

# CI Debugging

Every CI failure is real until proven otherwise. Never assume flakiness.

This skill owns pipeline-specific evidence and environment deltas. For a local
or runtime failure outside CI, use `debugging`.

## Getting the Data

Identify the CI provider from the repository configuration, then pull the actual failure output with that provider's connected tool, CLI, or UI before forming hypotheses. Preserve the run, job, attempt, commit SHA, and timestamps so later comparisons refer to the same execution.

For GitHub Actions:

```bash
gh run list --branch <branch> --limit 5        # find the failing run
gh run view <run-id> --log-failed              # only the failed steps' logs
gh run view <run-id> --job <job-id> --log      # one job's full log
gh run download <run-id>                       # artifacts (coverage, reports, screenshots)
```

Rerunning a workflow or changing a CI variable mutates external state and may
repeat deploys, migrations, notifications, or other effects. Do that only
with explicit authority after inspecting the workflow and failed job for side
effects. When authorized, rerun only the failed jobs with
`gh run rerun <run-id> --failed`, or use
`gh run rerun <run-id> --debug` for step-level logging; remove any temporary
debug variable afterwards. For another provider, use its equivalent controls
without translating commands by guesswork. Compare the failing run against
the last green run on the same branch — the diff in commits, dependency
lockfiles, and pipeline files between those two runs is the primary suspect
list.

If the system under test emits structured telemetry (canonical events, traces, in-memory exporter output from test runs), pull it as evidence alongside the logs — see the `observability` skill.

## Hypothesis-First Diagnosis

Before editing, list plausible causes, rank them by evidence, and test one falsifiable hypothesis at a time. Do not invent a fixed minimum merely to fill a list.

**Example hypotheses for a test timeout:**
1. Test relies on network access unavailable in CI
2. Parallel test execution causes resource contention
3. CI runner has less memory/CPU than local machine

## Local Reproduction

Reproduce locally when a faithful environment is available before pushing fixes.

- Run the **exact** failing command, not a close equivalent
- Match the CI environment as closely as possible (Node version, env vars)
- If it passes locally, treat the environment delta as evidence to localize; the cause may still be timing, state, or an external dependency

## Environment Delta Analysis

Compare CI vs local:

| Factor | Check |
|--------|-------|
| Node/runtime version | CI config vs `node -v` locally |
| OS | Linux CI vs macOS local |
| Dependency resolution | Repository's locked clean-install command and package cache (for npm, `npm ci` vs cached `node_modules`) |
| Env vars | CI secrets/config vs local `.env` |
| Parallelism | CI may run tests in parallel differently |
| Memory/CPU | CI runners often have less resources |
| Network | CI may block external network access |
| File system | Case sensitivity (Linux) vs insensitive (macOS) |

## Read the Full Error

- Read the **complete** error output, not just the last line
- Check preceding log lines and warnings — they often contain the real cause
- Look at stack traces to identify the actual failure point
- Check for earlier failures that may cascade into the visible error

## Fix Verification

If the request is diagnosis-only, report the supported root cause, evidence,
affected jobs, uncertainty, and recommended fix, then stop. Diagnosis does not
authorize workflow, production, dependency, test, or configuration changes.

When the user requested a fix, after identifying it:

1. Explain **why** it addresses the root cause (not just the symptom)
2. Run the exact failing command locally
3. Verify the fix doesn't mask the real issue (e.g., adding a retry hides a race condition)

## Anti-Patterns

| Anti-Pattern | Why It's Wrong | Instead |
|-------------|----------------|---------|
| "It's flaky, re-run it" | Masks real issues | Investigate the failure |
| Adding blind retries/sleeps | Can hide timing bugs | Identify the cause; add bounded retry only when the external contract requires it |
| Pushing speculative fixes | Wastes CI cycles | Reproduce and verify locally |
| Reading only the last error line | Misses root cause | Read full output from the top |
| Fixing symptoms | Problem will recur | Trace to root cause |

## Proving Flakiness

Different outcomes across independent runs with the same controlled inputs are
evidence that the outcome is nondeterministic. That proves flakiness even when
the source is not yet diagnosed. Record which inputs and environment facts were
actually controlled, then localize the cause: race, time, shared state, resource
pressure, or an external dependency. A single unexplained failure remains a
real failure, not permission to re-run until green.

## Handoff

Once the root cause is identified, a diagnosis-only handoff ends with the
evidence and recommended guard. For an authorized fix, leave the smallest
durable regression guard that fits it. For production behavior, write the
failing behavior test before the fix using `tdd` (or
`characterisation-tests` when legacy behavior first needs capture). For
provider configuration, permissions, or an external outage, use a config
assertion, dry-run, contract check, or monitored recovery proof as appropriate.
If no executable guard is feasible, record the evidence and remaining
detection path instead of fabricating a test.

Versions

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

Database snapshot: 13.11.2026 · package version 48930bd9a5f2 (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

  • 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…
  • 100fix-failing-actions
    Diagnose and fix failing GitHub Actions workflows in the drift repository. Use when a CI run, security hygiene check, release workflow, or any other GitHub Actions job is red. Keywords: GitHub Actions, workflow failure, CI failure, failed run, failing check, red CI, workflow…
  • 100debugging-ci-failures
    Debugs failing GitHub Actions CI runs for PostHog PRs, commits, and branches, and answers broad CI-health questions ("is CI red?", "is master green today?", "what's broken right now?"). Use when the user asks why CI is red, asks for the current CI or master status, or mentions a…
  • 100flaky-tests
    Finds unreliable tests in GitHub Actions history. In unit mode it ranks tests by how often they fail across the last N runs of the CI test job and flags those that fail on more than one branch. In e2e mode it turns the failure annotations of recent E2E runs on the default branch…
  • 100ci-triage
    Diagnose a failed GitHub Actions run and decide the right fix instead of reflexively rerunning or rewriting code. Use whenever CI is red, a workflow fails on a schedule or nightly run, "the pipeline is broken again", a PR shows failed checks, a deployment job failed, the user…

Feedback and reports

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