monitor-ci

# Monitor CI Command You are the orchestrator for monitoring Nx Cloud CI pipeline executions and handling self-healing fixes. You spawn the `ci-monitor-subagent` subagent to poll CI status and make decisions based on the results. ## Context - **Current Branch:** !`git branch --show-current` - **Current Commit:** !`git rev-parse --short HEAD` - **Remote Status:** !`git status -sb | head -1` ## User Instructions $ARGUMENTS **Important:** If user provides specific instructions, respect them over default behaviors described below. ## Configuration Defaults | Setting | Default | Description | | ------------------------- | ------------- | ------------------------------------------------------------------------- | | `--max-cycles` | 10 | Maximum **agent-initiated** CI Attempt cycles before timeout | | `--timeout` | 120 | Maximum duration in minutes | | `--verbosity` | medium | Output level: minimal, medium, verbose | | `--branch` | (auto-detect) | Branch to monitor | | `--subagent-timeout` | 30 | Subagent polling timeout in minutes | | `--fresh` | false | Ignore previous context, start fresh | | `--auto-fix-workflow` | false | Attempt common fixes for pre-CI-Attempt failures (e.g., lockfile updates) | | `--new-cipe-timeout` | 10 | Minutes to wait for new CI Attempt after action | | `--local-verify-attempts` | 3 | Max local verification + enhance cycles before pushing to CI | Parse any overrides from `$ARGUMENTS` and merge with defaults. ## Nx Cloud Connection Check **CRITICAL**: Before starting the monitoring loop, verify the workspace is connected to Nx Cloud. ### Step 0: Verify Nx Cloud Connection 1. **Check `nx.json`** at workspace root for `nxCloudId` or `nxCloudAccessToken` 2. **If `nx.json` missing OR neither property exists** → exit with: ``` [monitor-ci] Nx Cloud not connected. Unlock 70% faster CI and auto-fix broken PRs with https://nx.dev/nx-cloud ``` 3. **If connected** → continue to main loop ## Anti-Patterns (NEVER DO) **CRITICAL**: The following behaviors are strictly prohibited: | Anti-Pattern | Why It's Bad | | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | Using CI provider CLIs with `--watch` flags (e.g., `gh pr checks --watch`, `glab ci status -w`) | Bypasses Nx Cloud self-healing entirely | | Writing custom CI polling scripts | Unreliable, pollutes context, no self-healing | | Cancelling CI workflows/pipelines | Destructive, loses CI progress | | Running CI checks on main agent | Wastes main agent context tokens | | Independently analyzing/fixing CI failures while subagent polls | Races with self-healing, causes duplicate fixes and confused state | **If this skill fails to activate**, the fallback is: 1. Use CI provider CLI for READ-ONLY status check (single call, no watch/polling flags) 2. Immediately delegate to this skill with gathered context 3. NEVER continue polling on main agent **CI provider CLIs are acceptable ONLY for:** - One-time read of PR/pipeline status - Getting PR/branch metadata - NOT for continuous monitoring or watch mode ## Session Context Behavior **Important:** Within a Claude Code session, conversation context persists. If you Ctrl+C to interrupt the monitor and re-run `/monitor-ci`, Claude remembers the previous state and may continue from where it left off. - **To continue monitoring:** Just re-run `/monitor-ci` (context is preserved) - **To start fresh:** Use `/monitor-ci --fresh` to ignore previous context - **For a completely clean slate:** Exit Claude Code and restart `claude` ## Default Behaviors by Status The subagent returns with one of the following statuses. This table defines the **default behavior** for each status. User instructions can override any of these. | Status | Default Behavior | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `ci_success` | Exit with success. Log "CI passed successfully!" | | `fix_auto_applying` | Fix will be auto-applied by self-healing. Do NOT call MCP. Record `last_cipe_url`, spawn new subagent in wait mode to poll for new CI Attempt. | | `fix_available` | Compare `failedTaskIds` vs `verifiedTaskIds` to determine verification state. See **Fix Available Decision Logic** section below. | | `fix_failed` | Self-healing failed to generate fix. Attempt local fix based on `taskOutputSummary`. If successful → commit, push, loop. If not → exit with failure. | | `environment_issue` | Call MCP to request rerun: `update_self_healing_fix({ shortLink, action: "RERUN_ENVIRONMENT_STATE" })`. New CI Attempt spawns automatically. Loop to poll for new CI Attempt. | | `self_healing_throttled` | Self-healing throttled due to unapplied fixes. See **Throttled Self-Healing Flow** below. | | `no_fix` | CI failed, no fix available (self-healing disabled or not executable). Attempt local fix if possible. Otherwise exit with failure. | | `no_new_cipe` | Expected CI Attempt never spawned (CI workflow likely failed before Nx tasks). Report to user, attempt common fixes if configured, or exit with guidance. | | `polling_timeout` | Subagent polling timeout reached. Exit with timeout. | | `cipe_canceled` | CI Attempt was canceled. Exit with canceled status. | | `cipe_timed_out` | CI Attempt timed out. Exit with timeout status. | | `cipe_no_tasks` | CI Attempt exists but failed with no task data (likely infrastructure issue). Retry once with empty commit. If retry fails, exit with failure and guidance. | | `error` | Increment `no_progress_count`. If >= 3 → exit with circuit breaker. Otherwise wait 60s and loop. | ### Fix Available Decision Logic When subagent returns `fix_available`, main agent compares `failedTaskIds` vs `verifiedTaskIds`: #### Step 1: Categorize Tasks 1. **Verified tasks** = tasks in both `failedTaskIds` AND `verifiedTaskIds` 2. **Unverified tasks** = tasks in `failedTaskIds` but NOT in `verifiedTaskIds` 3. **E2E tasks** = unverified tasks where target contains "e2e" (task format: `<project>:<target>` or `<project>:<target>:<config>`) 4. **Verifiable tasks** = unverified tasks that are NOT e2e #### Step 2: Determine Path | Condition | Path | | --------------------------------------- | ---------------------------------------- | | No unverified tasks (all verified) | Apply via MCP | | Unverified tasks exist, but ALL are e2e | Apply via MCP (treat as verified enough) | | Verifiable tasks exist | Local verification flow | #### Step 3a: Apply via MCP (fully/e2e-only verified) - Call `update_self_healing_fix({ shortLink, action: "APPLY" })` - Record `last_cipe_url`, spawn subagent in wait mode #### Step 3b: Local Verification Flow When verifiable (non-e2e) unverified tasks exist: 1. **Detect package manager:** - `pnpm-lock.yaml` exists → `pnpm nx` - `yarn.lock` exists → `yarn nx` - Otherwise → `npx nx` 2. **Run verifiable tasks in parallel:** - Spawn `general` subagents to run each task concurrently - Each subagent runs: `<pm> nx run <taskId>` - Collect pass/fail results from all subagents 3. **Evaluate results:** | Result | Action | | ------------------------- | ---------------------------- | | ALL verifiable tasks pass | Apply via MCP | | ANY verifiable task fails | Apply-locally + enhance flow | 1. **Apply-locally + enhance flow:** - Run `nx-cloud apply-locally <shortLink>` - Enhance the code to fix failing tasks - Run failing tasks again to verify fix - If still failing → increment `local_verify_count`, loop back to enhance - If passing → commit and push, record `expected_commit_sha`, spawn subagent in wait mode 2. **Track attempts** (wraps step 4): - Increment `local_verify_count` after each enhance cycle - If `local_verify_count >= local_verify_attempts` (default: 3): - Get code in commit-able state - Commit and push with message indicating local verification failed - Report to user: ``` [monitor-ci] Local verification failed after <N> attempts. Pushed to CI for final validation. Failed: <taskIds> ``` - Record `expected_commit_sha`, spawn subagent in wait mode (let CI be final judge) #### Commit Message Format ```bash git commit -m "fix(<projects>): <brief description> Failed tasks: <taskId1>, <taskId2> Local verification: passed|enhanced|failed-pushing-to-ci" ``` **Git Safety**: Only stage and commit files that were modified as part of the fix. Users may have concurrent local changes (local publish, WIP features, config tweaks) that must NOT be committed. NEVER use `git add -A` or `git add .` — always stage specific files by name. ### Unverified Fix Flow (No Verification Attempted) When `verificationStatus` is `FAILED`, `NOT_EXECUTABLE`, or fix has `couldAutoApplyTasks != true` with no verification: - Analyze fix content (`suggestedFix`, `suggestedFixReasoning`, `taskOutputSummary`) - If fix looks correct → apply via MCP - If fix needs enhancement → use Apply Locally + Enhance Flow above - If fix is wrong → reject via MCP, fix from scratch, commit, push ### Auto-Apply Eligibility The `couldAutoApplyTasks` field indicates whether the fix is eligible for automatic application: - **`true`**: Fix is eligible for auto-apply. Subagent keeps polling while verification is in progress. Returns `fix_auto_applying` when verified, or `fix_available` if verification fails. - **`false`** or **`null`**: Fix requires manual action (apply via MCP, apply locally, or reject) **Key point**: When subagent returns `fix_auto_applying`, do NOT call MCP to apply - self-healing handles it. Just spawn a new subagent in wait mode. No local git operations (no commit, no push). ### Accidental Local Fix Recovery If you find yourself with uncommitted local changes from your own fix attempt when the subagent returns (e.g., you accidentally analyzed/fixed the failure while the subagent was polling): 1. **Compare your local changes with the self-healing fix** (`suggestedFix` / `suggestedFixDescription`) 2. **If identical or substantially similar** → discard only the files you modified (`git checkout -- <file1> <file2> ...`), then apply via MCP instead. Self-healing's pipeline is the preferred path. Do NOT discard unrelated user changes. 3. **If meaningfully different** (your fix addresses something self-healing missed) → proceed with the Apply Locally + Enhance Flow Self-healing fixes go through proper CI verification. Always prefer the self-healing path when fixes overlap. ### Apply vs Reject vs Apply Locally - **Apply via MCP**: Calls `update_self_healing_fix({ shortLink, action: "APPLY" })`. Self-healing agent applies the fix in CI and a new CI Attempt spawns automatically. No local git operations needed. - **Apply Locally**: Runs `nx-cloud apply-locally <shortLink>`. Applies the patch to your local working directory and sets state to `APPLIED_LOCALLY`. Use this when you want to enhance the fix before pushing. - **Reject via MCP**: Calls `update_self_healing_fix({ shortLink, action: "REJECT" })`. Marks fix as rejected. Use only when the fix is completely wrong and you'll fix from scratch. ### Apply Locally + Enhance Flow When the fix needs enhancement (use `nx-cloud apply-locally`, NOT reject): 1. Apply the patch locally: `nx-cloud apply-locally <shortLink>` (this also updates state to `APPLIED_LOCALLY`) 2. Make additional changes as needed 3. Stage only the files you modified: `git add <file1> <file2> ...` 4. Commit and push: ```bash git commit -m "fix: resolve <failedTaskIds>" git push origin $(git branch --show-current) ``` 5. Loop to poll for new CI Attempt