pr-readiness

# PR Readiness Skill

Activates when the user asks to verify PR readiness, run a pre-merge check,
or confirm a PR is safe to merge.

## When to Use

- Before opening a pull request for the first time
- Before merging an open PR
- When asked "is this PR ready to merge?" or "pre-merge checklist"
- After addressing review feedback — re-run this checklist before merging

## Pre-Merge Checklist

Run each item in order. A PR is not merge-ready until every item passes.

### 1. Lint pass

Run the `lint` tool with `mode="check"`. Must report 0 errors.

```
Tool: lint  |  mode: "check"
Expected: success, 0 errors
```

If lint fails, run with `mode="fix"` to auto-correct, then re-check.

### 2. Build pass

Run `build_check` to verify the project compiles without errors.

```
Tool: build_check  |  mode: "both"
Expected: success (both build and typecheck pass)
```

### 3. Test pass

Run tests for changed files only. Use `test_runner` with `scope="convention"`
and explicit `files: [...]`, or use the per-file shell isolation loop documented
in `TESTING.md`.

```
Tool: test_runner  |  scope: "convention"  |  files: <changed files>
Expected: success, 0 failures
```

Do NOT use `scope: "all"` for interactive validation. See AGENTS.md invariant 6.

### 4. Pre-check batch green

Run `pre_check_batch` on the project directory. All gates must pass
(`gates_passed: true`).

```
Tool: pre_check_batch  |  directory: <project root>
Expected: gates_passed === true
```

This runs lint, secretscan, SAST, and quality budget in a single pass.

### 5. CI green via `gh` CLI

Verify all remote CI checks are green on the PR head commit.

```bash
gh pr checks <PR_NUMBER>
```

Also inspect the structured check rollup:

```bash
gh pr view <PR_NUMBER> --json statusCheckRollup
```

All entries in `statusCheckRollup` must have `"status": "completed"` and
`"conclusion": "success"`. If any check is `"conclusion": "failure"`,
diagnose before proceeding.

### 6. Release fragment present

Every user-visible PR must ship a release note fragment under
`docs/releases/pending/`. Verify one exists for this change.

```bash
ls docs/releases/pending/
```

Each fragment is a `<unique-slug>.md` file. Do NOT create version-numbered
files — release-please owns the version number. See AGENTS.md invariant 12
and `contributing.md`.

### 7. Invariant audit section in PR description

The PR description must contain a `## Invariant audit` section covering all
12 invariants. See the [Invariant Audit Template](#invariant-audit-template)
section below.

For each invariant the PR touches, evidence must be a concrete artifact:
a command output, a passing test, a grep result, or a spec citation.
"Looks fine" is not evidence.

### 8. PR body claim verification

Verify that all quantitative claims in the PR description match the actual
source code. Bot reviews (Codex, Copilot) and human reviewers trust PR body
text — inaccurate claims waste review cycles and erode trust.

Check these claim types against source:

- **Test count**: Count actual test cases from test runner output or grep for
  test declarations only (not `describe` blocks):
  `grep -rE "^\s*(it|test)\(" --include="*.test.ts" | wc -l`
  Compare to PR body count.
- **Pattern/validation count**: If PR claims "12 regex patterns" or "3 validation
  gates", count the actual constants/patterns in the source file.
- **Storage format**: If PR claims "individual JSON files" or "JSONL", verify
  the actual store implementation reads/writes that format.
- **Tool count**: If PR claims "7 new tools", verify 7 tool files exist with
  `src/tools/` entries.
- **Config field names**: If PR shows config examples, verify field names match
  the Zod schema in `src/config/schema.ts`.

```bash
# Quick verification commands
grep -rE "^\s*(it|test)\(" tests/unit/tools/my-feature*.test.ts | wc -l   # actual test count
grep -c "PATTERN = " src/services/my-validator.ts                          # actual pattern count
ls src/tools/my-feature-*.ts | wc -l                                       # actual tool count
```

If any claim is inaccurate, fix the PR body before proceeding. Do not merge
with incorrect claims.

### 9. No TODOs or placeholder code

Run `placeholder_scan` or `todo_extract` on changed files.

```
Tool: placeholder_scan  |  changed_files: <changed files>
Expected: 0 findings (TODOs referencing a future task ID are acceptable)
```

Alternatively:

```
Tool: todo_extract  |  paths: <changed files or directory>
Expected: no stale TODOs/FIXMEs/HACKs
```

### 10. Secret scan clean

Run `secretscan` to verify no leaked credentials.

```
Tool: secretscan  |  directory: <project root>
Expected: 0 findings
```

If findings appear, verify they are false positives before suppressing.

### 11. SAST scan clean

Run `sast_scan` to verify no security vulnerabilities.

```
Tool: sast_scan  |  directory: <project root>
Expected: no medium+ severity findings
```

### 12. Review state

All required reviews must be approved.

```bash
gh pr view <PR_NUMBER> --json reviewDecision,latestReviews
```

`reviewDecision` summarizes the overall review outcome. It should be
`"APPROVED"` to proceed. Historical `COMMENTED` or `DISMISSED` reviews
do not block merge — only an unresolved `"CHANGES_REQUESTED"` in
`latestReviews` will block. If `reviewDecision` is `"CHANGES_REQUESTED"`
or `"REVIEW_REQUIRED"`, address the outstanding feedback before merging.

### 13. No merge conflicts

```bash
gh pr view <PR_NUMBER> --json mergeable,mergeStateStatus
```

Must return `"mergeable": "MERGEABLE"` and `"mergeStateStatus": "CLEAN"`.
If `"mergeable"` is `"UNKNOWN"`, wait for GitHub to recalculate mergeability, then re-check.
If `mergeStateStatus` is `"BEHIND"`, the PR needs a rebase.
If it is `"DIRTY"` or `"BLOCKED"`, resolve conflicts or blockers before merging.

## Quick Commands

Reference set of `gh` CLI commands for CI and review status:

```bash
# Check CI status
gh pr checks <PR_NUMBER>

# Structured check rollup
gh pr view <PR_NUMBER> --json