---
name: "cicd-failure-diagnostician"
description: "Paste a failed CI log (GitHub Actions, CircleCI, etc.) and get: failure category, root cause in plain English, exact fix command or code change, and flaky test detection."
metadata:
  version: "1.0.0"
disable-model-invocation: true
---

# CI/CD Failure Diagnostician

> **Purpose:** Diagnose a failed CI/CD pipeline from raw logs. Takes a GitHub Actions, CircleCI, GitLab CI, or any other CI log output. Returns: failure category, root cause explanation in plain English, exact fix (command, code change, or env var), and whether it looks like a flaky test. Turns 20 minutes of log-reading into 20 seconds.

---

## Invocation

```
/ci-fix <paste-log-output>
```

Or: `/ci-fix` then paste the log when prompted.

---

## Failure Categories

Classify the failure into exactly one category:

| Category | Indicators |
|----------|-----------|
| **Test failure** | `FAIL`, `AssertionError`, `expect(x).toBe(y)`, test name in output |
| **Build error** | TypeScript error, compilation failure, syntax error |
| **Lint error** | ESLint, Prettier, Ruff, golangci-lint rule violation |
| **Missing env var** | `undefined`, `Cannot read properties of undefined (reading 'env')`, `process.env.X is not defined` |
| **Dependency install failure** | `npm ERR!`, `pip install failed`, `Cannot find module` |
| **Permission error** | `EACCES`, `403 Forbidden`, `permission denied` |
| **Timeout** | Job exceeded `N` minutes, `ETIMEDOUT`, hanging process |
| **Out of memory** | `ENOMEM`, `JavaScript heap out of memory`, OOM killed |
| **Network error** | DNS resolution failed, connection refused, rate limited |
| **Flaky test** | Timing assertions, random/date-dependent values, race conditions |

---

## Diagnosis Process

### Step 1: Find the Failure Point

Scan the log for the FIRST error line — most CI logs dump a long stack trace but the real error is near the top of the first `ERROR` block.

Common patterns to scan for:
```
✗ FAILED
Error: ...
× ...
FAILED: ...
error[...]: ...
exit code: 1 (immediately after the relevant command)
```

### Step 2: Explain in Plain English

One paragraph: what failed, why it failed, and what the system was trying to do when it failed. No jargon that isn't in the original log.

### Step 3: Provide the Fix

The fix must be one of:
- **A command to run** (with the exact command, ready to copy-paste)
- **A code change** (file:line, old code, new code)
- **An env var to add** (variable name + where to add it)
- **A CI config change** (which job/step to modify and how)

### Step 4: Flaky Test Detection

Flag as **possibly flaky** if the failure involves:
- `setTimeout` / `sleep` / date-based assertions without mocking
- Race conditions (async test with no proper await)
- External service calls in unit tests
- File system state left from a previous test
- Random or time-dependent data generation

If flaky: suggest `--retry=3` as a short-term bandage + the proper fix (mock the external dependency).

---

## Output Format

```
## CI Failure Diagnosis

**Job:** [job name from log]
**Step:** [step that failed]
**Category:** [one of the 10 categories above]

---

### Root Cause

[Plain-English explanation, 2-4 sentences]

---

### Fix

[Exact command OR code change OR env var to add]

```bash
# Run this locally to reproduce and verify the fix:
[reproduction command]
```

---

### Flaky Test?

[Yes / No / Possibly — with brief reason]

---

### Prevention

[One-line suggestion to prevent this class of failure in the future]
```

---

## Rules

- Always find the FIRST error line, not the last — stack traces cascade from the origin
- Never say "the issue is complex" — give a specific diagnosis even if uncertain (flag uncertainty)
- If `Missing env var`: specify the exact variable name found in the log, not a guess
- If flaky: never just say "add a retry" — explain the actual race condition or timing issue
- If you cannot determine the cause: output "Inconclusive — please provide more log context" with specific questions about what's missing