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".
- Author
- bdfinst ↗
- Repository
- agentic-dev-team ↗
- Licence
- MIT
- Last repository change
- 14.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
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
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
- Overview
- Constraints
- Process
- Anti-Patterns
- Integration
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
| Repository | Score | Licence |
|---|---|---|
| This page · bdfinst/agentic-dev-team | 90 | MIT |
| kcenon/claude-config | 100 | BSD-3-Clause |
| citypaul/.dotfiles | 100 | MIT |
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