--- 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 ``` 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 ## Playground

Input: CI log excerpt

FAIL src/auth/session.test.ts
  ● Session › persists after reload

    Expected: "active"
    Received: undefined

    at Object.expect (session.test.ts:47)

Tests: 1 failed, 147 passed

Output: Diagnosis

Root cause
session.test.ts:47 — `status` field is
`undefined` after reload. The test
creates a session then reads it before
the write propagates to the store.

Likely fix
1. Add `await session.save()` before
   the reload assertion.
2. Or mock the session store so reads
   are synchronous in tests.

Verify
npx vitest run src/auth/session
Add: console.log(session) after reload