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:

bash
1gh --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):

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

Specific run mode:

bash
1gh 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:

bash
1gh 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:

bash
1RUN_ID=<the-run-id>
2
3# Get failed jobs with their steps
4gh run view $RUN_ID --json jobs --jq '.jobs[] | select(.conclusion == "failure") | {name, conclusion, steps: [.steps[] | select(.conclusion == "failure")]}'
5
6# Get failed step logs (critical for debugging)
7gh run view $RUN_ID --log-failed 2>&1 | head -500
8
9# Get verbose run info
10gh 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:

bash
1# Try common artifact names - failures are OK (not all runs have artifacts)
2gh run download $RUN_ID -n "coverage" -D /tmp/ci-debug/ 2>/dev/null || true
3gh run download $RUN_ID -n "test-results" -D /tmp/ci-debug/ 2>/dev/null || true
4gh 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:

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:

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:

bash
1# Example for Python test
2cd 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:

markdown
1# CI Fix Plan
2
3## Problem Statement
4[Summary of the CI failure from logs]
5
6## Failure Details
7- **Run ID**: <run-id>
8- **Workflow**: <workflow-name>
9- **Job**: <job-name>
10- **Error Type**: <categorized-type>
11
12## Root Cause Analysis
13[Explanation of why the failure occurred]
14
15## Affected Files
16- `path/to/file1.py` (line X)
17- `path/to/file2.py` (line Y)
18
19## Proposed Changes
20
21### Change 1: [Brief description]
22[Specific edit to make]
23
24### Change 2: [Brief description]
25[Specific edit to make]
26
27## Verification Steps
281. Run: `<local-test-command>`
292. Expected: All tests pass
303. Optional: Run full test suite with `<full-suite-command>`
31
32## Notes
33- [Any caveats or considerations]

Step 11: User Approval Gate

Present the plan and wait for explicit user approval:

• User approves: Proceed to execute fixes
• User modifies: Incorporate feedback, update plan
• User rejects: Exit gracefully without changes

CRITICAL: Never make code changes without user approval.

Step 12: Execute Fix (after approval only)

1. Make the proposed code changes using Edit tool
2. Run local tests to verify the fix:

bash
1<local-test-command>

3. Report results:
   • Success: "Fix verified locally. Tests pass."
   • Failure: "Fix did not resolve the issue. [details]"

IMPORTANT: Do NOT auto-commit changes. Leave committing to the user or /commit-push-pr skill.

Error Handling

Output Format

On finding a failure:

CI Failure Found
Run: #12345 (workflow-name)
Branch: feature-branch
Failed Job: test-python
Error Type: Test Failure

Analyzing logs...
[Summary of failure]

Reproducing locally...
[Result]

Entering plan mode to propose fix...

On success (after fix):

Fix Applied
- Modified: path/to/file.py
- Verification: Tests pass locally

Next steps:
- Review the changes
- Run `/commit-push-pr` to commit and push
- CI will re-run automatically on push

Notes for the Agent

1. Always scope to current branch by default - Users expect /fix-ci to fix their current work, not random failures
2. Truncate logs wisely - CI logs can be huge; extract the relevant error sections
3. Reproduce before fixing - Don't propose fixes for issues that can't be reproduced
4. Plan mode is mandatory - Always use EnterPlanMode before making changes
5. Never auto-commit - The user controls when changes are committed
6. Be specific in analysis - Generic advice isn't helpful; identify exact files and lines
7. Handle flaky tests - If reproduction fails, acknowledge it might be flaky