ci-monitor

# GitHub CI Monitor

Monitor GitHub Pull Request CI/CD checks continuously until all checks complete, then provide visual and audio notification of the result.

## Core Behavior

**CRITICAL: Be tenacious.** CI pipelines vary wildly in duration—some complete in 2 minutes, others take over an hour. Never give up monitoring. Continue polling until receiving a definitive pass or fail result, or until explicitly stopped by the user.

## Prerequisites

Ensure the GitHub CLI (`gh`) is installed and authenticated. Verify with:

```bash
gh auth status
```

## Monitoring Workflow

### Step 1: Identify the PR

Determine the PR to monitor. If user specifies a PR number, use that. Otherwise, detect from current branch:

```bash
gh pr view --json number,title,url,headRepository
```

If no PR exists for the current branch, inform the user and offer to help create one.

### Step 2: Start Monitoring Loop

Begin the polling loop with clear user feedback:

1. Print initial status message: "Monitoring PR #X: [title]"
2. Print the PR URL for reference
3. Begin polling every 60 seconds

### Step 3: Poll for Check Status

Use `gh pr checks` to get current status:

```bash
gh pr checks <PR_NUMBER> --json name,state,conclusion
```

Check states:
- `PENDING` or `QUEUED` - Still running, continue polling
- `IN_PROGRESS` - Still running, continue polling
- `COMPLETED` - Check finished, examine conclusion

Check conclusions (when completed):
- `SUCCESS` - Check passed
- `FAILURE` - Check failed
- `CANCELLED` - Check was cancelled (treat as failure)
- `SKIPPED` - Check was skipped (treat as success)
- `NEUTRAL` - Neutral result (treat as success)

### Step 4: Determine Overall Status

All checks must complete before announcing results:

- **All checks completed with SUCCESS/SKIPPED/NEUTRAL**: CI passed
- **Any check with FAILURE/CANCELLED**: CI failed
- **Any check still PENDING/QUEUED/IN_PROGRESS**: Continue polling

### Step 5: Handle Completion

When all checks complete:

#### On Success

1.