---
name: ci-debug
description: Systematic CI build failure analysis with log inspection and fix recommendations
whenToUse: When asked to diagnose a CI build failure, analyze CI logs, or debug a failing pipeline
version: 1.0.0
priority: managed
domain: devops
tools:
  - Read
  - Bash
  - GitDiff
paths:
  - .gitlab-ci.yml
  - .github/workflows/**
  - Dockerfile
  - "**/Dockerfile"
  - "**/*.ci.yml"
hooks:
  post-tool: |
    After each tool result, re-evaluate: did this reveal new error context? Update the diagnosis if so.
---

# CI Debug Skill

You are diagnosing a CI build failure. Follow this systematic debugging process.

## Debug Process

1. **Read the log**: Start from the end (the error), then trace backwards to find the first failure.
2. **Classify the failure**:
   - **Compile error**: syntax, type mismatch, missing import
   - **Test failure**: assertion mismatch, timeout, flaky test
   - **Build error**: dependency resolution, missing environment variable, infrastructure issue
   - **Lint/format**: style violation, formatting mismatch
3. **Identify the root cause**: Don't just fix the symptom. Why did this fail now? What changed?
4. **Propose a fix**: Give specific, actionable file changes.
5. **Verify**: Check that the fix doesn't break anything else.

## Error Pattern Recognition

### Compile Errors
- `TS2xxx`: TypeScript errors — check types, generics, imports
- `Cannot find module`: Missing dependency or wrong import path
- `Type 'X' is not assignable to type 'Y'`: Interface mismatch

### Test Failures
- `AssertionError`: Expected vs actual mismatch — check if test or code is wrong
- `Timeout`: Async operation didn't complete — check promises, event loops
- `toHaveBeenCalledWith`: Mock expectation mismatch

### Build Errors
- `ENOENT`: File not found — check paths, build outputs
- `Module not found`: Dependency issue — check package.json, lockfile
- `exit code 1`: Generic failure — grep for "error" in full log

## Output Format

```
## Root Cause
<One sentence explaining why the build failed>

## Error Analysis
- **Error**: <exact error message>
- **Location**: <file:line>
- **Likely Fix**: <specific code change needed>

## Recommended Actions
1. <step-by-step fixes in order>

## Prevention
<How to prevent this in CI or pre-commit hooks>
```

## Database

Record CI failure patterns and their fixes for future reference. If the same error appears again, cite the previous fix.
