/fix-ci

name: fix-ci
description: Fetch GitHub CI failure information, analyze root causes, reproduce locally, and propose a fix plan. Use `/fix-ci` for current branch or `/fix-ci <run-id>` for a specific run.
allowed-tools: Bash, Read, Grep, Glob, Task, AskUserQuestion, EnterPlanMode

Fix CI Skill

Automates CI troubleshooting by fetching GitHub Actions failures, analyzing logs, reproducing issues locally, and creating a fix plan for user approval.

---

Execution Workflow

Step 1: Prerequisites Check

Verify the GitHub CLI is installed and authenticated:

gh --version && gh auth status

**If gh is not installed:**

• Inform user: "GitHub CLI is required. Install with: `brew install gh`"
• Exit gracefully

**If not authenticated:**

• Inform user: "Please authenticate with: `gh auth login`"
• Exit gracefully

Step 2: Parse Arguments

Determine the mode based on arguments:

• **No arguments** (`/fix-ci`): Fetch failures for the current branch only
• **With run-id** (`/fix-ci <run-id>`): Fetch specific run (bypasses branch scoping)

Step 3: Fetch Failed Run

**Default mode (current branch):**

BRANCH=$(git branch --show-current)
gh run list --branch "$BRANCH" --status failure --limit 1 --json databaseId,name,headBranch,workflowName,createdAt

**Specific run mode:**

gh run view <run-id> --json databaseId,name,headBranch,workflowName,jobs,conclusion

**If no failures found:**

• Report: "No failed runs found for branch `$BRANCH`. CI is green!"
• Optionally show recent successful runs:

gh run list --branch "$BRANCH" --limit 3 --json databaseId,conclusion,workflowName,createdAt

• Exit gracefully

Step 4: Get Failure Details

Once a failed run is identified, gather comprehensive details:

RUN_ID=<the-run-id>

# Get failed jobs with their steps
gh run view $RUN_ID --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion, steps: [.steps[] | select(.conclusion == "failure")]}'

# Get failed step logs (critical for debugging)
gh run view $RUN_ID --log-failed 2>&1 | head -500

# Get verbose run info
gh run view $RUN_ID --verbose

**Log handling:**

• Truncate logs to 500 lines to avoid context overflow
• Note to user: "Showing first 500 lines of failed logs. Full logs available on GitHub."

Step 5: Download Artifacts (if available)

Attempt to download any debug artifacts:

# Try common artifact names - failures are OK (not all runs have artifacts)
gh run download $RUN_ID -n "coverage" -D /tmp/ci-debug/ 2>/dev/null || true
gh run download $RUN_ID -n "test-results" -D /tmp/ci-debug/ 2>/dev/null || true
gh run download $RUN_ID -n "logs" -D /tmp/ci-debug/ 2>/dev/null || true

If artifacts downloaded, read them for additional context.

Step 6: Analyze Failure Type

Categorize the failure based on log patterns:

| Pattern | Failure Type | Root Cause Area | |---------|--------------|-----------------| | `FAIL:`, `--- FAIL`, `FAILED` | Test Failure | Specific test case | | `ruff check`, `ruff format` | Lint Error | Code style/formatting | | `ModuleNotFoundError`, `ImportError` | Import Error | Missing dependency | | `TypeError`, `AttributeError` | Runtime Error | Type mismatch | | `SyntaxError` | Syntax Error | Invalid code | | `AssertionError` | Assertion Failure | Test expectation mismatch | | `TimeoutError`, `timed out` | Timeout | Performance/hang | | `PermissionError`, `EACCES` | Permission Error | File/resource access | | `ConnectionError`, `ECONNREFUSED` | Network Error | External service |

Extract key information:

• Failed test name/file (if applicable)
• Error message
• Stack trace location (file:line)
• Environment variables or config issues

Step 7: Map to Local Test Commands

Determine the appropriate local command based on the CI job:

| CI Workflow/Job | Local Command | |-----------------|---------------| | `test-cli` | `cd cli && go test ./...` | | `test-python` (server) | `cd server && uv run pytest -v` | | `test-python` (rag) | `cd rag && uv run pytest -v` | | `test-python` (config) | `cd config && uv run pytest -v` | | `test-python` (runtime) | `cd runtimes/universal && uv run pytest -v` | | `lint` (python) | `uv run ruff check .` | | `lint` (go) | `cd cli && golangci-lint run` | | `type-check` | `uv run mypy .` | | `build-cli` | `nx build cli` | | `build-designer` | `cd designer && npm run build` |

**For specific test failures**, narrow down the command:

• Python: `cd <dir> && uv run pytest -v <test_file>::<test_name>`
• Go: `cd cli && go test -v -run <TestName> ./...`

Step 8: Reproduce Locally

Run the mapped local command to confirm the failure reproduces:

# Example for Python test
cd server && uv run pytest -v tests/test_api.py::test_health_check

**Outcome A - Failure reproduces locally:**

• Good! Continue to fix plan
• Report: "Successfully reproduced failure locally"

**Outcome B - Failure does NOT reproduce locally:**

• Note: "Could not reproduce locally. Possible causes:"
• Flaky test (timing-dependent)
• Environment difference (CI has different deps/config)
• Race condition
• Suggest: "Consider re-running CI with `gh run rerun $RUN_ID`"
• Ask user how to proceed (investigate further or skip)

Step 9: Analyze Root Cause

Based on the failure type and logs, identify:

1. **What failed**: Specific test, lint rule, or build step 2. **Why it failed**: The actual error condition 3. **Where to fix**: File(s) and line(s) that need changes 4. **How to fix**: Proposed changes

Use available tools to explore:

• Read the failing test file
• Read the code being tested
• Search for related patterns in the codebase
• Check recent changes that might have caused the failure

Step 10: Enter Plan Mode

Use `EnterPlanMode` to create a formal fix plan. The plan should include:

# CI Fix Plan

## Problem Statement
[Summary of the CI failure from logs]

## Failure Details
- **Run ID**: <run-id>
- **Workflow**: <workflow-name>
- **J