---
name: ci-investigate
description: Investigate flaky CI failures across multiple workflow runs to identify patterns, categorize root causes, and propose fixes. Use when asked to investigate CI failures, find flaky tests, diagnose test flakiness, or understand why CI is failing repeatedly.
---

# CI Failure Investigator

Investigate flaky CI failures across multiple workflow runs to identify patterns, categorize root causes, and propose targeted fixes.

## Arguments

- `$ARGUMENTS` - Optional: job name filter, number of runs to check, or branch name. Examples: "test-core-rspec", "--runs 10", "master"

If no arguments are provided, investigate the most recent failing workflow on the current branch.

## Context

- Current branch: !`git branch --show-current`
- Repo remote: !`git remote get-url origin 2>/dev/null | head -1`
- CI config: !`find . -maxdepth 2 \( -name ".circleci" -o -name ".github" \) -type d 2>/dev/null | head -5`
- CircleCI config snippet: !`head -30 .circleci/config.yml 2>/dev/null | head -30`

## Instructions

Investigate CI failures by fetching multiple workflow runs, extracting test results, and categorizing failure patterns.

### Step 1: Determine Scope

Parse `$ARGUMENTS` for:
- **Job name filter** (e.g., "test-core-rspec") -- only analyze jobs matching this name
- **Run count** (e.g., "--runs 10") -- how many recent runs to check (default: 5, max: 15)
- **Branch** -- which branch to investigate (default: current branch from context above)

Derive the project slug from the git remote URL. For GitHub repos, format is "gh/org/repo".

Report the scope to the user before proceeding:
- Project slug
- Branch
- Job filter (if any)
- Number of runs to fetch

### Step 2: Fetch Recent Workflow Runs

Detect the CI provider from the context above and use the appropriate tools.

**CircleCI** (if .circleci/ exists):
Use ToolSearch to find available CircleCI MCP tools (search "circleci"). Then:
1. Fetch recent pipelines for the project slug and branch
2. For each pipeline, get its workflows
3. For each workflow, get jobs and their statuses
4. Filter to failed jobs (and optionally by job name from Step 1)

**GitHub Actions** (if .github/workflows/ exists):
Use the gh CLI:
1. `gh run list --branch {branch} --limit {N}` to get recent runs
2. `gh run view {run_id}` to get job details
3. `gh run view {run_id} --log-failed` to get failure output

Collect up to the target number of failed runs. If a workflow has no failures, skip it but note it as a passing run (useful for calculating flake rate).

Track:
- Total workflow runs examined
- Number with failures vs passing
- Which specific jobs failed in each run

### Step 3: Extract Failure Details

For each failed job found in Step 2:

**CircleCI:**
1. Fetch test results for the failed job (with artifacts and logs if the MCP tools support it)
2. If 0 test failures but non-zero exit code, fetch raw job logs. Flag as **infrastructure failure**.

**GitHub Actions:**
1. Use `gh run view {run_id} --log-failed` to get failure output
2. Parse test framework output (JUnit XML, RSpec, Jest, etc.) for structured results

For each failure, extract:
- Test file path
- Test name
- Error message and stack trace
- Node/container number (for parallel test splitting issues)

Use parallel Task tool calls to fetch test results for multiple jobs simultaneously when possible.

### Step 4: Categorize Failures

Group failures by test file + test name. For each group, classify the root cause:

| Category | Signals | Common Fix |
|----------|---------|------------|
| **Deterministic** | Fails every run, same error | Fix the test or code -- this is a real bug |
| **Timing flake** | Intermittent, error involves time comparison, values differ by milliseconds | Freeze time in tests, use tolerance matchers |
| **Parallel collision** | Hard-coded IDs, PK violations, "Duplicate entry" | Use sequences/auto-increment, avoid hard-coded IDs |
| **Test isolation** | Order-dependent failures, shared mutable state between tests | Reset state between tests, avoid global side effects |
| **Infrastructure** | 0 test failures + exit code 1, OOM killed, container timeout | Retry or investigate resource limits |
| **External dependency** | Timeout connecting to external service, API errors | Add retry logic or stub external calls in tests |

If a failure does not clearly fit one category, mark it as **Unclassified** and include the full error for manual review.

### Step 5: Report Findings

Present the findings in this format:

```
## CI Investigation Report

**Scope:** {project} / {branch} / {job filter or "all jobs"}
**Runs analyzed:** {N} ({pass_count} passed, {fail_count} failed)
**Overall flake rate:** {fail_count/N * 100}%

### Failure Groups (by frequency)

#### 1. {test_file}:{test_name} -- {category}
- **Frequency:** {X}/{N} runs ({percentage}%)
- **Error:** {1-2 line error summary}
- **Affected nodes:** {node numbers if relevant}
- **Root cause:** {explanation}
- **Proposed fix:**
  {specific code change or strategy}

#### 2. ...

### Infrastructure Failures
{List any jobs that failed with 0 test failures}

### Cross-Repo Issues
{Flag any fixes needed in shared gems (Nucleus, etc.) or CI configuration}

### Recommended Priority
1. {highest frequency flake} -- affects X% of runs
2. ...
```

### Step 6: Offer Next Steps

After presenting the report, ask the user if they want to:
1. **Fix a specific flake** -- implement the proposed fix for a chosen failure group
2. **Investigate deeper** -- fetch more runs or drill into a specific failure
3. **Export the report** -- save findings to a file for reference