CI Failure Debugger Agent Skill

---
name: ci-failure-debugger
description: Diagnose and fix failing CI checks. Use when a pipeline, GitHub Actions workflow, build, test, lint, or type-check job fails.
---

# CI Failure Debugger

## Workflow

1. Identify the exact failed job, step, command, commit, and first actionable error.
2. Read the smallest relevant log slice before loading full logs.
3. Classify the failure: deterministic code issue, test regression, environment mismatch, dependency drift, flaky test, permissions, or external service.
4. Inspect the workflow file and the scripts it invokes. Do not assume CI runs the same command as local development.
5. Reproduce locally using the CI runtime, working directory, environment shape, and command as closely as practical.
6. Trace the failure to the smallest responsible code path.
7. Implement the minimal root-cause fix. Do not weaken assertions, skip checks, or add blind retries.
8. Run the failed command locally, then the nearest broader verification suite.
9. Report the root cause, changed files, exact verification, and any unverified CI-only behavior.

## Flaky failures

- Establish evidence of nondeterminism before calling a test flaky.
- Look for shared state, time dependence, race conditions, network reliance, resource limits, and test-order coupling.
- Fix the cause when possible. If retry behavior is unavoidable, bound it and document why.

## Safety

- Never print secrets or copy sensitive environment values into the report.
- Do not rerun paid or production-affecting workflows without approval.
- Do not modify branch protection or required-check settings.