arthai-marketplace

/ci-fix

Auto-remediate CI, staging, and production failures. 3-attempt retry with investigation. Discord alert on exhaustion.

Synopsis

/ci-fix [ci|staging|prod] [branch]

When to use it

Quickstart

/ci-fix

What you’ll see: the failed run’s logs pulled and classified, a narrowly-scoped fix verified locally, then a commit + push and a wait for the new CI result. If the first attempt doesn’t go green, it retries with a different strategy — up to 3 attempts.

Examples

/ci-fix                        # fix CI failures on the current branch
/ci-fix ci feature/my-branch   # fix CI on a specific branch
/ci-fix staging                # diagnose + fix a staging deploy failure
/ci-fix prod                   # production deploy failure — read-only investigation first

Arguments & flags

Argument Values Default What it does
mode ci | staging | prod ci Which failure surface to remediate
branch any branch name current branch Which branch’s CI runs to inspect

What it does

  1. Reads the full CI/CD landscape — CLAUDE.md test commands and the project profile, then checks the knowledge base and knowledge graph using keywords from the error logs (if kg-query.sh is available, it runs first and surfaces past CI failure patterns, known flaky tests, and team conventions before investigating from scratch). It then detects the actual CI platform via config files (.github/workflows/, .gitlab-ci.yml, Jenkinsfile, .circleci/config.yml, and others) and uses platform-specific commands to pull logs, check status, and retry — for non-GitHub CI, review your CLAUDE.md test/CI commands, since most guidance below assumes GitHub Actions conventions. It also checks for environment mismatches between CI and local: runtime versions (python/node/go), running services (postgres, redis), env vars, and secrets — if tests pass locally but fail in CI, this is the first place to look.
  2. Checks known flaky patterns — before investigating, it queries past CI incidents and the bug-pattern database in the knowledge base. If a match is found, it reports the known issue instead of redoing the investigation; if it’s a new pattern, it gets added to the knowledge base for future /ci-fix runs.
  3. Attempt loop (max 3) — each attempt: pull the failed logs, classify the failure (lint / types / tests / build / migration / dependency), apply a fix scoped to only the failing files, verify locally before pushing, then commit, push, and wait for the new CI result. Each retry uses a different strategy — attempt 2 reads more context, attempt 3 does a deep investigation against the last green commit.
  4. Mode-specific guardrails — staging mode reads deploy logs and health endpoints, patching code or env vars; prod mode is read-only first, never modifies the production database, and considers a git revert on attempt 3.
  5. On exhaustion — after 3 failed attempts it posts a Discord alert to #deployments (when discord-ops is configured), writes a QA incident file, and hands back to you for manual review.
  6. Completion verification — a completion-verifier agent runs a final cross-check, displaying PASS (fully fixed), GAPS FOUND (fix incomplete), or INCONCLUSIVE (unclear if fixed). GAPS FOUND does not block anything — you decide whether to rerun /ci-fix.

On the claude-agents toolkit repo specifically, CI failures often come from repo-specific conventions rather than real bugs: bracket characters in a SKILL.md description:/arguments: field (fix: use <text> not [text]), missing required frontmatter fields, a new portable.manifest entry not yet mapped to a category in install.sh:get_category_items(), or a stale agent test fixture (fix: cp agents/<name>.md tests/fixtures/claude-setups/poweruser/.claude/agents/). /ci-fix auto-fixes all of these when it recognizes them.

Hard rules: never repo-wide lint auto-fix, never # noqa/# type: ignore suppressions, never deleted or skipped tests, never direct deploy commands — fixes always go through git, never modify dependency files unless the failure is actually a dependency issue, and never run railway up or an equivalent platform deploy command — always push to git and let the platform auto-deploy.

Agents spawned

Agent Model tier Role
troubleshooter sonnet Only on stuck escalation — most attempts run inline
completion-verifier sonnet Final completeness cross-check

Output & artifacts

Troubleshooting

Problem Fix
Auto-fix exhausted after 3 attempts Manual review required — the QA incident file contains the diagnosis trail; start a fresh session to investigate
Monitor-triggered run exits immediately with an alert The cross-session guard found attempts >= 3 for this branch in .ci-fix-state.json — fix manually, then a green run resets the counter
Fix requires architectural changes /ci-fix reports and stops by design — it never attempts large refactors
Same failure keeps recurring across branches It may be a flaky test — check the report’s known-flaky match and the CI recommendations for retry configuration
Attempt 2 looks like it’s about to fail the same way as attempt 1 Rewind (Esc Esc) to before attempt 1 and re-prompt with a different strategy — don’t let a failed attempt’s context carry into the next try
Following work after a multi-attempt fix behaves oddly or seems confused After a fix that took 2-3 attempts (or hit exhaustion), run /clear before starting the next task — accumulated failed-attempt logs and dead-end diagnoses actively mislead subsequent reasoning