CI Checker

Checks GitHub CI status for PRs and guides fixing any failures.

Prerequisites

PR must exist
Must be in a git repository with GitHub remote
gh CLI authenticated

Workflow

1. Get PR Info

Check for status.json in current directory:

cat status.json 2>/dev/null | jq -r '.prNumber // empty'

If not found, ask: "PR number? (or paste URL)"

2. Check CI Status

gh pr checks {pr-number}

Parse each check for status:

✅ pass
❌ fail
🔄 pending

3. Report Status

Present as table:

# CI Status for PR #{number}

| Check     | Status     | Duration |
| --------- | ---------- | -------- |
| lint      | ✅ pass    | 2m       |
| typecheck | ✅ pass    | 3m       |
| test-unit | ❌ fail    | 5m       |
| test-e2e  | 🔄 pending | -        |
| build     | ✅ pass    | 4m       |

## Overall: {Passing / Failing / Pending}

4. Handle Pending

If checks still running:

CI checks still running. Estimated time: {X} minutes.

Options:
A) Wait and check again in 5 minutes
B) Check specific workflow status
C) Continue anyway (not recommended)

5. Handle Failures

For each failing check, get details:

# Get JSON with run IDs
gh pr checks {pr-number} --json name,status,conclusion,detailsUrl

# Get logs for failing run
gh run view {run-id} --log-failed

Present failure summary:

## Failed: {check-name}

### Error Summary

{extracted error message}

### Failed Tests

- `src/components/Foo.test.ts` - "expected true, got false"

### Suggested Fix

{analysis based on error type}

6. Guide Fixes

Found {X} failing checks.

Options:
A) Investigate and fix locally
B) Re-run failed checks (if flaky)
C) View full logs for {check}
D) Ignore and proceed (not recommended)

Choice:

Option A - Fix locally:

Provide commands to reproduce locally
Dispatch subagent to investigate
After fix, commit and push
Re-check CI

Option B - Re-run:

gh run rerun {run-id} --failed

Wait and check again.

Option C - View logs:

gh run view {run-id} --log

Present relevant sections.

7. Handle All Passing

✅ All CI checks passing!

PR is ready for review.

Options:
A) Update Notion status to "Done"
B) Request specific reviewers
C) Done for now

If updating Notion (Option A):

⚠️ Follow Notion Write Safety rules.

Validate transition In Review → Done is valid
Log to status.json:

{
  "field": "Status",
  "value": "Done",
  "previousValue": "In Review",
  "at": "...",
  "skill": "ci-checker",
  "success": true
}

8. Update State

Update status.json if it exists:

jq '.ciStatus = "passing"' status.json > tmp.json && mv tmp.json status.json

Common Issues & Solutions

E2E Test Flakes

Cause: Timing issues, async operations
Solution: Re-run with gh run rerun --failed
If persists: Fix the flaky test

Lint Differences

Cause: Different eslint/prettier versions
Solution: Run pnpm install and pnpm lint:fix locally

Type Errors in CI Only

Cause: Stricter tsconfig or different TS version
Solution: Run exact same typecheck command as CI

Build Failures

Cause: Missing files, import errors
Solution: Run pnpm build locally to reproduce

Key Commands

# List all checks
gh pr checks {pr-number}

# Get check details as JSON
gh pr checks {pr-number} --json name,status,conclusion,detailsUrl

# View run details
gh run view {run-id}

# View failed logs only
gh run view {run-id} --log-failed

# View full logs
gh run view {run-id} --log

# Re-run failed jobs
gh run rerun {run-id} --failed

# Re-run entire workflow
gh run rerun {run-id}

Notes

E2E tests can take 10-20 minutes - don't poll too frequently
One re-run for flaky tests is acceptable
If same test fails twice, it's a real issue
Some checks are required for merge, some optional
Never force merge with failing required checks