investigate-ci

name	investigate-ci
description	Investigates GitHub Actions workflow failures for any repo. Fetches recent runs, identifies failures, extracts error logs, diagnoses root causes, and suggests fixes. Use when a deploy or CI workflow fails and you need to understand why.
argument-hint	<repo, workflow URL, or run URL>
context	fork
allowed-tools	["AskUserQuestion","Bash(gh *)","Read","Glob","Grep","WebFetch"]

Investigate CI

Investigate GitHub Actions failures — fetch logs, diagnose root causes, suggest fixes.

Preferences

Read ~/.claude/skills/investigate-ci/preferences.md using the Read tool. If not found, no preferences are set.

Context

On startup, use Bash to detect: current repo (gh repo view --json nameWithOwner -q .nameWithOwner) and default org (gh repo view --json owner -q .owner.login). Skip any that fail.

Command Routing

Check $ARGUMENTS for subcommands:

help

If $ARGUMENTS is "help" (case-insensitive), display:

Investigate CI — diagnose GitHub Actions failures

Usage:
  /investigate-ci <workflow-url>                  Investigate a specific workflow
  /investigate-ci <run-url>                       Investigate a specific run
  /investigate-ci <repo> [workflow]               Investigate by repo name
  /investigate-ci config                          Set preferences
  /investigate-ci reset                           Clear preferences
  /investigate-ci help                            This help

Examples:
  /investigate-ci https://github.com/org/repo/actions/workflows/deploy.yml
  /investigate-ci https://github.com/org/repo/actions/runs/12345678
  /investigate-ci ai-stacks deploy.yml
  /investigate-ci ai-stacks                       All failing workflows
  /investigate-ci 12345678                        Run ID (uses current/default repo)

Current preferences:
  [show from preferences.md or "defaults"]

Then stop.

config

If $ARGUMENTS is "config" or "configure", use AskUserQuestion:

Question 1 — "Default organization?" (multiSelect: false)

• Detect from current repo
• Always ask

Question 2 — "How many recent runs to check?" (multiSelect: false)

• 5 (quick)
• 10 (default)
• 20 (thorough)

Question 3 — "Default branch filter?" (multiSelect: false)

• All branches (default)
• Main/prod only
• Current branch

Save to ~/.claude/skills/investigate-ci/preferences.md. Display summary. Then stop.

reset

If $ARGUMENTS is "reset", delete preferences.md. Confirm: "Preferences cleared. Using defaults." Then stop.

Default (investigate)

If $ARGUMENTS is anything else, proceed below.

Step 1: Parse Input

Extract from $ARGUMENTS:

Full workflow URL — e.g., https://github.com/org/repo/actions/workflows/deploy.yml

• Extract: org, repo, workflow filename

Full run URL — e.g., https://github.com/org/repo/actions/runs/12345678

• Extract: org, repo, run ID → skip to Step 3 (single run investigation)

Repo + workflow — e.g., ai-stacks deploy.yml

• Resolve org from preferences or current repo context
• If repo is a short name (no /), prepend the detected org

Repo only — e.g., ai-stacks

• List all workflows, filter to those with recent failures

Run ID only — e.g., 12345678

• Use current repo or default org/repo from preferences

If ambiguous, use AskUserQuestion to clarify.

Step 2: Fetch Recent Runs

gh run list --repo <org/repo> --workflow <workflow> --limit <N> --json databaseId,status,conclusion,headBranch,event,createdAt,displayTitle,headSha

If no workflow specified, list all workflows first:

gh workflow list --repo <org/repo> --json name,id,state

Then fetch runs for workflows with recent failures.

Present overview

Workflow: deploy.yml (org/repo)
Recent runs (last N):

  [FAIL]  #123 — "Deploy to prod" — main — 2h ago
  [PASS]  #122 — "Deploy to staging" — main — 5h ago
  [FAIL]  #121 — "Deploy to prod" — main — 1d ago
  [PASS]  #120 — "Feature X" — feature/x — 1d ago

If multiple failures, use AskUserQuestion:

• "Which run to investigate?" — list failed runs as options + "Most recent failure (Recommended)"

If only one failure, investigate it directly.

Step 3: Investigate Failed Run

3a. Fetch run details

gh run view <run-id> --repo <org/repo> --json jobs,conclusion,headBranch,headSha,event,createdAt,updatedAt,displayTitle

3b. Identify failed jobs

For each failed job, fetch logs:

gh run view <run-id> --repo <org/repo> --log-failed 2>&1

This returns only the logs from failed steps — much more targeted than full logs.

3c. Parse errors

From the failed step logs, extract:

• Error messages: Lines containing error, Error, FAILED, fatal, Exception, exit codes
• Stack traces: Consecutive indented lines following an error
• Context: The 5 lines before the first error (often shows what was being attempted)

3d. Check the triggering commit

gh api repos/<org>/<repo>/commits/<sha> --jq '{message: .commit.message, author: .commit.author.name, date: .commit.author.date, files: [.files[].filename]}'

Step 4: Diagnose

Analyze the error and categorize:

Category	Signals	Common fixes
Dependency	ModuleNotFoundError, npm ERR!, Could not resolve	Lock file out of sync, missing package
Build	tsc, SyntaxError, TypeError, compilation errors	Type errors, syntax issues in changed files
Test	FAIL, AssertionError, test file paths	Failing tests, snapshot mismatches
Deploy	AccessDenied, timeout, connection refused	Permissions, infra issues, env vars
Config	invalid workflow, yaml, secrets references	Workflow syntax, missing secrets
Flaky	Same commit passed before, timing-related errors	Re-run, increase timeout

Cross-reference with:

• The files changed in the triggering commit (do they relate to the error?)
• Whether this workflow passed for the same branch before (regression vs. new issue?)
• Whether main is also failing (systemic vs. branch-specific?)

Step 5: Present Findings

CI Investigation: <workflow> — Run #<id>

Trigger:  <event> on <branch> by <author> (<relative time>)
Commit:   <sha_short> "<commit message>"
Duration: <time>

Failed job: <job name>
Failed step: <step name>

Error:
  <extracted error message, formatted>

Root cause:
  <one-paragraph diagnosis>

Changed files in trigger commit:
  - file1.py
  - file2.ts

Related:
  - [Previous run on same branch: PASS/FAIL]
  - [Main branch status: PASS/FAIL]

Step 6: Suggest Actions

Use AskUserQuestion (multiSelect: true):

Options based on diagnosis:

• "Re-run failed job" — gh run rerun <id> --repo <org/repo> --failed
• "View full logs" — gh run view <id> --repo <org/repo> --log
• "Open in browser" — gh run view <id> --repo <org/repo> --web
• "Check if main is also failing" — investigate main branch runs
• "Skip" — done investigating

For code-related failures, also suggest:

• "Read the failing file" — open the file at the error location
• "Compare with last passing run" — diff the commits

Principles

• Logs are noisy — extract signal: Don't dump raw logs. Parse and present the relevant error with context.
• Always check the commit: The triggering commit often explains the failure. Show which files changed.
• Detect patterns: If the same workflow failed multiple times recently, note it. If main is also broken, flag it as systemic.
• Read-only by default: Only re-run jobs if the user explicitly asks. Investigation is safe; re-runs cost compute.
• Fast first pass: Show the error quickly. Deep investigation (reading source files, comparing runs) is opt-in via the action menu.
• Cross-repo capable: Don't assume the current directory matches the failing repo. Always use --repo flags.