Pre-PR Verification

Structured verification pass before creating any PR. Run this BEFORE gh pr create or git push for a new PR.

Step 1: Detect base branch

First check for repo-local PR convention. Look for a declared base branch in:

1. Repo-local AGENTS.md or CLAUDE.md (some repos use a non-main default branch, e.g. develop, release, or a project-specific trunk; never assume main)
2. .claude/pr-config.json if it exists (field: baseBranch)

If no repo-local convention is found, fall back:

git remote show origin | grep 'HEAD branch' | sed 's/.*: //'

Report which source determined the base branch.

Step 2: Verify working branch

CURRENT=$(git branch --show-current)

Check that the current branch is NOT the base branch or any protected branch declared in repo-local config. If it is, report as BLOCKING.

Step 3: Run repo-local preflight

Read the repository's AGENTS.md or CLAUDE.md and CI configuration. Run its declared applicable checks (for example, pytest, npm test, bun test). If the repository declares an existing trusted preflight executable, run it too; .claude/hooks/pre-commit.sh is one optional convention, not a bundled requirement. Do not install or activate hooks as part of this check.

If no repo-local preflight exists, report as INFO: "No repo-local preflight found."

Step 4: Secret scan

Scan the diff against the base branch for credential patterns:

git diff <base-branch>...HEAD

Patterns to check (advisory, not a policy gate):

• password, secret, token, api_key, apikey, private_key, auth_token followed by assignment with a string value
• Base64-encoded strings longer than 40 characters that look like keys
• Your secrets manager's documented token prefixes (most managers publish a recognizable prefix for service/personal tokens; add yours here)

If hits are found, report as BLOCKING (secrets are the one advisory pattern that blocks).

Step 5: Repo-local optional patterns

If .claude/pr-config.json exists and declares additional scan patterns:

{
  "scanPatterns": [
    { "pattern": "console\\.log", "severity": "WARNING", "label": "Debug logging" },
    { "pattern": "TODO|FIXME|HACK", "severity": "WARNING", "label": "Shipping markers" }
  ]
}

Run each pattern against the diff and report at the declared severity.

If no repo-local patterns are configured, skip this step.

Step 6: File inventory

List all changed files with a one-line rationale:

git diff --stat <base-branch>...HEAD

For each file, state what changed and why (based on the diff content and commit messages).

Step 7: Coverage of the diff

Review changed behavior as well as the suite's exit code:

1. Identify each changed behavior, invariant, error path, authority gate, state transition or side effect in git diff <base-branch>...HEAD.
2. Name the highest useful test seam already available (unit, API/integration, CLI/hook, migration, or manual proof when automation is inappropriate).
3. Map each behavior to a test or observed proof that would fail if it broke. Report WARNING for a missing match, especially for silent failure, fallback, authorization, data integrity and state changes. Existing green tests alone do not establish coverage of the changed behavior.
4. Mechanical edits and prose-only documentation corrections need no new tests; report why this review is not applicable. A documented executable recipe or a change to a supported workflow is behavior and still needs a scenario/proof. Respect the current request's authority for any live proof; an absent grant means report the gap, not invoke production or a provider.

Worked example: a PR changes an API's 401 fallback, while its only test exercises 200 success. Report WARNING: 401 fallback has no matching failure-path test at the API seam, even if the full suite passes. A Markdown spelling correction has no changed behavior: report INFO: coverage review not applicable; prose-only.

This review is advisory. It does not weaken repository-required checks, convert warnings into approval, or grant push/PR/merge authority.

Output Format

## Pre-PR Report

**Base branch:** <branch> (source: <repo-local | origin default>)
**Current branch:** <branch>
**Files changed:** <count>

### BLOCKING
- [secrets found, protected-branch violation, preflight failure]

### WARNING
- [advisory findings: TODOs, debug markers, large diffs, repo-local patterns, changed behavior without matching proof]

### INFO
- [file inventory, branch state, preflight status]

### Result: CLEAR | ISSUES (<N> blocking, <N> warning)