---
name: PR Preflight
slug: pr-preflight
category: Quality
description: PR Preflight runs a full merge-readiness check before opening or merging a pull request, validating local gates (lint, format, tests), CI status, screenshot evidence, and PR metadata in one pass.
github: "https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/pr-preflight"
language: Python
stars: 3064
forks: 266
install: "npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/pr-preflight ~/.claude/skills/pr-preflight"
installs_to: ~/.claude/skills/pr-preflight
source_path: .agents/skills/pr-preflight/SKILL.md
collection_size: 11
category_size: 1354
collection_url: "https://dirskills.com/collections/liaohch3/claude-tap"
added: 2026-08-17T07:09:16.618Z
last_synced: 2026-08-17T07:09:16.618Z
canonical_url: "https://dirskills.com/skills/pr-preflight"
---

# PR Preflight

PR Preflight runs a full merge-readiness check before opening or merging a pull request, validating local gates (lint, format, tests), CI status, screenshot evidence, and PR metadata in one pass.

**Install:**

```bash
npx degit https://github.com/liaohch3/claude-tap/tree/main/.agents/skills/pr-preflight ~/.claude/skills/pr-preflight
```

## README

# PR Preflight

One-command merge-readiness check that combines local gates, CI status, and PR policy checks. Mirrors what reviewers look for so issues are caught before review, not during.

## Check an existing PR

```bash
scripts/check_pr.sh <pr_number>
```

This runs:
1. **PR metadata** — fetches title, state, draft status, merge state, branch info
2. **CI checks** — counts pass/fail/pending GitHub Actions checks
3. **Local gates** — runs lint, format, and tests locally:
   - `uv run ruff check .`
   - `uv run ruff format --check .`
   - `uv run pytest tests/ -x --timeout=60`
4. **PR body policy** — validates required sections, evidence links, and blocked artifacts
5. **Verdict** — `READY` or `NOT_READY` with specific reasons

### Options

| Flag | Purpose |
|------|---------|
| `--repo OWNER/REPO` | Override repository (default: auto-detect via `gh`) |
| `--no-tests` | Skip local test gates (useful when you just want CI + metadata check) |

### Exit codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed — ready to merge |
| 1 | Script error (missing tool, network failure) |
| 2 | Not ready — at least one check failed |

## Run local gates only (no PR needed)

If you haven't opened a PR yet and just want to validate locally:

```bash
uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60
```

Or use the pre-commit hook (auto-runs lint on commit):

```bash
git config core.hooksPath .githooks
```

## What blocks merge

The script reports `NOT_READY` if any of these are true:
- PR is not in OPEN state
- PR is still a draft
- Merge state is not CLEAN or HAS_HOOKS
- Any CI check is failing
- Any CI check is still pending
- Local gates (lint/format/tests) fail
- PR body policy fails, such as missing evidence for runtime/viewer/client changes

## Typical workflow

```bash
# 1. Make sure local gates pass
uv run ruff check . && uv run ruff format --check . && uv run pytest tests/ -x --timeout=60

# 2. Push and open PR
git push origin my-branch
gh pr create --title "feat: ..." --body "..."

# 3. Wait for CI, then run full preflight
scripts/check_pr.sh <pr_number>
```