teamcraft-jcg:pipeline-health

---
name: teamcraft-jcg:pipeline-health
description: Interpret GitHub Actions workflow status with context — not raw logs, but an explanation of what failed and why. Optionally create a trackable Jira issue from a persistent workflow failure. Use when CI is failing, the build is broken, checks are red, asking "why did the pipeline fail", or wanting to understand a workflow error. Also run when a PR's checks won't pass, deployments are stuck, or a recurring CI failure needs to be tracked as a ticket.
argument-hint: "[branch name or workflow run ID — optional]"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Bash
  - mcp__sooperset-mcp-atlassian__jira_create_issue
---

## Goal

Surface what failed in a GitHub Actions workflow run and why — not raw logs, but an interpreted explanation a developer or DevOps engineer can act on. When a failure is persistent, offer to create a trackable Jira issue from it so it does not get lost.

## Hard Constraints

- A branch name or workflow run ID from `$ARGUMENTS` is the starting point. If neither was provided, ask before searching.
- Never auto-create issues. Always show the draft issue and get explicit confirmation before creating anything in Jira.
- Never retry or cancel a workflow run without explicit instruction from the user. Offer these as options after presenting findings — do not take action on your own.
- All GitHub Actions interactions go through the gh CLI via Bash only. No other mechanism.

## Identify the Workflow Run

If a branch name or workflow run ID was provided in `$ARGUMENTS`, use it. If not, ask the user to specify — which branch or which workflow run they want to investigate.

The GitHub repo is identified from git remote: `git remote -v` via Bash. No project listing step is needed.

Use `gh run list --branch [branch]` to locate recent workflow runs for a branch. For a branch, the most recent run is typically the relevant one — confirm with the user if there is ambiguity.

Surface the workflow name alongside the run ID when presenting options. GitHub Actions has named workflows (`.github/workflows/*.yml`) — this context helps the user orient quickly.

## Read the Failure

Fetch the run details with `gh run view [run-id]`. For jobs and steps: `gh run view [run-id] --json jobs`.

For failed jobs, retrieve logs with `gh run view [run-id] --log-failed`. This retrieves logs for failed jobs only, which is the most relevant output for diagnosis.

Read the logs carefully. The goal is not to surface the log — it is to understand what the log is saying. Parse the failure at the right level of abstraction:

Not: "The test job failed."
But: "The auth service integration tests are failing because `JWT_SECRET` is not set in the CI environment. The test runner is erroring on the first test that calls the token validation endpoint, and all subsequent tests in that suite are also failing as a result."

That level of explanation is the deliverable. A developer reading this should know what broke and what to do about it.

Note: GitHub Actions organizes runs into jobs and steps. A job is roughly analogous to a GitLab CI job; a step is finer-grained. When reporting, surface the failing job name and the specific step within it.

## Present Interpreted Findings

Present the failure explanation to the user. Cover:

**What failed** — which workflow, which job, which step, and the nature of the failure in plain language.

**Why it failed** — the root cause as read from the logs. Be specific: environment variables, dependency issues, test failures with test names, build errors with the error message.

**What to fix** — a concrete, actionable suggestion. Not generic advice. What specifically to change, add, or investigate.

If multiple jobs failed, cover each one. Group failures that share a common root cause.

## Check for Persistence

If the user or the context suggests this failure has appeared across multiple workflow runs on this branch, note that explicitly. A one-time flaky test and a structural configuration failure are different problems — the data helps distinguish them.

To check persistence, run `gh run list --branch [branch] --limit 10` and compare recent run outcomes. If the failure appears across multiple runs (same job, same error), note that explicitly.

If the failure appears persistent, offer to create a Jira issue to make it trackable.

## Offer to Create a Trackable Issue

If the failure is persistent and the user wants to track it, read `references/example-bug-issue.md` and draft a bug issue matching its structure. The draft must include all sections from the reference: Problem Statement, Environment, Steps to Reproduce, Current/Expected Behavior, Debug Information, Investigation Areas, Potential Approaches, Testing Requirements, Priority, and Labels. Populate from what the workflow logs revealed.

Show the complete draft. Do not create the issue until the user confirms.

After confirmation, use `mcp__sooperset-mcp-atlassian__jira_create_issue` to confirm the correct issue type name for bugs in this Jira project. Then create the issue using `mcp__sooperset-mcp-atlassian__jira_create_issue`. Share the issue key and URL.

The Jira project key comes from `.teamcraft/project.md` if it exists. If not, ask the user for it.

## Offer Next Steps

After presenting findings, offer the developer their options:

- **Rerun only failed jobs** — if the failure looks transient (network error, flaky test), offer to rerun via `gh run rerun [run-id] --failed`
- **Rerun the full workflow** — if appropriate, via `gh run rerun [run-id]`
- **Cancel a running workflow** — if the current run is stuck or irrelevant, via `gh run cancel [run-id]`

Present these as choices. Do not act without explicit instruction.