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