Claude-skill-registry ci-doctor

install

source · Clone the upstream repo

git clone https://github.com/majiayu000/claude-skill-registry

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/ci-doctor" ~/.claude/skills/majiayu000-claude-skill-registry-ci-doctor && rm -rf "$T"

manifest: skills/data/ci-doctor/SKILL.md

CI Doctor

Diagnose and fix CI failures fast. Read logs, identify root cause, fix or delegate.

Context Files (Read First)

For project structure, read from

Docs/context/

```
Docs/context/repo-structure.md
```
- File locations
```
Docs/context/conventions.md
```
- CI/build patterns

Workflow

1. FETCH    → Get failure details (gh cli or logs)
2. DIAGNOSE → Identify error category
3. FIX      → Apply fix or delegate to specialist skill
4. VERIFY   → Run locally to confirm
5. PUSH     → Commit and push fix

Step 1: Fetch Failure Details

# Get recent workflow runs
gh run list --limit 5

# Get failed run details
gh run view <run-id>

# Get job logs
gh run view <run-id> --log-failed

# Get PR checks
gh pr checks

If user provides a GitHub URL, extract info with

gh

gh pr view <url> --json statusCheckRollup
gh run view <url>

Step 2: Diagnose Error Category

Error Pattern	Category	Action
`tsc` errors, "TS2xxx"	TypeScript	Fix type errors
`biome lint` , "lint error"	Lint	Delegate to `lint-fixer`
`FAIL src/...test.ts`	Test failure	Delegate to `test-writer` or fix
`npm ci` failed	Dependency	Check package-lock.json
`types.ts changed`	Generated types	Regenerate and commit
`timeout` , `ETIMEDOUT`	Flaky/infra	Retry or increase timeout
`permission denied`	Secrets/auth	Check workflow permissions
CodeQL alert, code scanning	Security vulnerability	See "Code Scanning Alerts" section

Step 3: Fix by Category

TypeScript Errors

# Run locally to see all errors
npm run typecheck:ci
# or
npx tsc -p tsconfig.ci.json --noEmit

Fix each error. Common patterns:

Missing imports
Type mismatches
Unused variables (remove or prefix with
```
_
```
)

Lint Errors

Delegate:

Use the lint-fixer skill

Or quick fix:

npx @biomejs/biome check --write .

Test Failures

Run failing test locally:

npm run test --workspace=apps/raamattu-nyt -- --run <test-file>

If complex, delegate:
```
Use the systematic-debugging skill
```
If test needs update, delegate:
```
Use the test-writer skill
```

Generated Types Out of Sync

Supabase types:

# Regenerate (requires SUPABASE_PROJECT_ID and SUPABASE_ACCESS_TOKEN)
npx supabase gen types typescript --project-id "$SUPABASE_PROJECT_ID" > apps/raamattu-nyt/src/integrations/supabase/types.ts
git add apps/raamattu-nyt/src/integrations/supabase/types.ts
git commit -m "Regenerate Supabase types"

OpenAPI types:

npx openapi-typescript ./openapi.yaml -o apps/raamattu-nyt/src/lib/openapi.types.ts
git add apps/raamattu-nyt/src/lib/openapi.types.ts
git commit -m "Regenerate OpenAPI types"

Dependency Issues

# Clear and reinstall
rm -rf node_modules package-lock.json
npm install
git add package-lock.json
git commit -m "Refresh package-lock.json"

Code Scanning Alerts (CodeQL)

GitHub Code Scanning uses CodeQL to find security vulnerabilities. Access alerts via:

# List all code scanning alerts
gh api repos/{owner}/{repo}/code-scanning/alerts --jq '.[] | {number, state, rule: .rule.id, severity: .rule.security_severity_level, file: .most_recent_instance.location.path, line: .most_recent_instance.location.start_line}'

# Get specific alert details
gh api repos/{owner}/{repo}/code-scanning/alerts/<alert-number>

# List open alerts only
gh api repos/{owner}/{repo}/code-scanning/alerts?state=open

Common CodeQL Alerts and Fixes:

Alert Type	Fix
`js/xss`	Sanitize user input before rendering, use `textContent` not `innerHTML`
`js/sql-injection`	Use parameterized queries, never concatenate user input
`js/path-injection`	Validate/sanitize file paths, use `path.join` with basename
`js/prototype-pollution`	Use `Object.create(null)` or validate object keys
`js/insecure-randomness`	Use `crypto.randomUUID()` instead of `Math.random()`
`js/hardcoded-credentials`	Move secrets to environment variables
`js/log-injection`	Sanitize user input before logging
`js/regex-injection`	Escape regex special characters in user input

Workflow:

Fetch alert details with
```
gh api
```
Read the affected file and understand the vulnerability
Apply the appropriate fix
Test locally
Commit and push - CodeQL will re-analyze

Dismissing False Positives:

# Dismiss alert as false positive
gh api -X PATCH repos/{owner}/{repo}/code-scanning/alerts/<number> -f state=dismissed -f dismissed_reason=false_positive -f dismissed_comment="Reason here"

Step 4: Verify Locally

Before pushing, run the same checks CI runs:

# TypeScript
npm run typecheck:ci || npx tsc -p tsconfig.ci.json

# Lint
npx @biomejs/biome lint .

# Build
npm run build

# Tests
npm run test --workspace=apps/raamattu-nyt

Step 5: Push Fix

git add -A
git commit -m "Fix CI: <brief description>"
git push

Then monitor:

gh run watch

Project CI Structure

This project has these workflows:

Workflow	File	Triggers	Checks
CI	`.github/workflows/ci.yml`	PR, push to main	TypeScript, Lint, Build
Tests	`.github/workflows/tests.yml`	PR, push (code changes)	Vitest, Playwright smoke
Supabase Sync	`.github/workflows/supabase-sync.yml`	Various	Type generation

Delegation Guide

Situation	Delegate To
Lint/format errors	`lint-fixer` skill
Test needs rewriting	`test-writer` skill
Complex bug in test	`systematic-debugging` skill
Supabase migration issue	`supabase-migration-writer` skill
Type refactoring needed	`code-refactoring` skill

Quick Commands Reference

# See what's failing
gh pr checks
gh run list --limit 3

# Get logs for failed run
gh run view <id> --log-failed

# Re-run failed jobs
gh run rerun <id> --failed

# Watch current run
gh run watch