validate-before-pr

name	validate-before-pr
description	REQUIRED before opening any pull request. Always invoke when about to open a PR, create a merge request, push for review, or run pre-PR checks. Runs lint and format checks as a gate before PR creation.
TRIGGER	user asks to open a PR or merge request, asks to push for review, mentions pre-PR validation, or calls the open-pull-request skill.
DO NOT SKIP	applies to all PR creation regardless of repository or context.

Validate Before PR

This skill is a mandatory gate that runs lint and format checks before any pull request is opened. It must be invoked before the open-pull-request skill. If either check fails, the PR must not be opened until the failures are resolved.

IMPORTANT: When This Skill Applies

This skill is mandatory for:

• Any request to open, create, or draft a pull request or merge request
• Any workflow that leads to invoking the open-pull-request skill
• Requests to "push for review" or "push and open a PR"
• Pre-PR validation checks requested explicitly

Do not open a PR through any means without running this skill first.

Steps

Each check must be run as a separate, standalone Bash call. Do not chain commands with && or ; — this is required by the bash-style rule.

Step 0 — Detect stack

Run the following as a standalone Bash call (no args — uses the current directory):

~/.claude/scripts/detect-stack.sh

The script emits a single-line JSON object to stdout:

{"stack": "...", "lint_cmd": "...", "format_check_cmd": "...", "format_warning": "..."}

Branch on .stack:

• If .stack == "unknown": print the value of .format_warning (which will be "No recognized lint/format toolchain was found. Skipping validation."), then jump directly to Step 3. Note in the handoff that pre-PR checks were not run.
• Otherwise: store .lint_cmd as <lint_cmd> and .format_check_cmd as <format_check_cmd> for use in Steps 1–2. If .format_warning is non-empty, print it now (this surfaces the Makefile fmt-only warning to the user). Proceed to Step 1.

Step 1 — Run lint

Run the following as a standalone Bash call, using the <lint_cmd> value captured in Step 0:

<lint_cmd>

• If lint passes (exit code 0): proceed to Step 1b.
• If lint fails (non-zero exit): stop immediately. Do not proceed to format check or PR creation. Report the full lint output to the user and request that the errors be fixed before retrying.

Step 1b — Run shell lint

Run the following probe as a standalone Bash call:

node -e "process.exit(require('./package.json').scripts?.['lint:sh'] ? 0 : 1)" 2>/dev/null && npm run lint:sh

• If the node -e probe exits non-zero (script not declared in package.json) or if package.json does not exist: skip with note "No lint:sh script declared in package.json — skipping shell lint." This is not a failure.
• If the probe passes and npm run lint:sh passes (exit code 0): proceed to Step 1c.
• If the probe passes and npm run lint:sh fails (non-zero exit): stop immediately. Do not proceed to format check or PR creation. Report the full lint output to the user and request that the errors be fixed before retrying.

Step 1c — Run YAML lint

Run the following probe as a standalone Bash call:

node -e "process.exit(require('./package.json').scripts?.['lint:yaml'] ? 0 : 1)" 2>/dev/null && npm run lint:yaml

• If the node -e probe exits non-zero (script not declared in package.json) or if package.json does not exist: skip with note "No lint:yaml script declared in package.json — skipping YAML lint." This is not a failure.
• If the probe passes and npm run lint:yaml passes (exit code 0): proceed to Step 2.
• If the probe passes and npm run lint:yaml fails (non-zero exit): stop immediately. Do not proceed to format check or PR creation. Report the full lint output to the user and request that the errors be fixed before retrying.

Step 2 — Run format check

If <format_check_cmd> is empty (e.g., a Makefile repo with only a fmt target that modifies files), skip this step with the note: "No format check is configured for this stack." Proceed directly to Step 2b.

Otherwise, run the following as a standalone Bash call, using the <format_check_cmd> value captured in Step 0:

<format_check_cmd>

• If format check passes (exit code 0): proceed to Step 2b.
• If format check fails (non-zero exit): stop immediately. Do not open the PR. Report the full output to the user and request that the formatting issues be fixed before retrying.

Step 2b — Run shell format check

Run the following probe as a standalone Bash call:

node -e "process.exit(require('./package.json').scripts?.['format:check:sh'] ? 0 : 1)" 2>/dev/null && npm run format:check:sh

• If the node -e probe exits non-zero (script not declared in package.json) or if package.json does not exist: skip with note "No format:check:sh script declared in package.json — skipping shell format check." This is not a failure.
• If the probe passes and npm run format:check:sh passes (exit code 0): proceed to Step 2c.
• If the probe passes and npm run format:check:sh fails (non-zero exit): stop immediately. Do not open the PR. Report the full output to the user and request that the formatting issues be fixed before retrying.

Step 2c — Run spellcheck

Run the following probe as a standalone Bash call:

node -e "process.exit(require('./package.json').scripts?.['spellcheck'] ? 0 : 1)" 2>/dev/null && npm run spellcheck

• If the node -e probe exits non-zero (script not declared in package.json) or if package.json does not exist: skip with note "No spellcheck script declared in package.json — skipping spell check." This is not a failure.
• If the probe passes and npm run spellcheck passes (exit code 0): proceed to Step 3.
• If the probe passes and npm run spellcheck fails (non-zero exit): stop immediately. Do not open the PR. Report the full output to the user and request that the spelling issues be fixed before retrying.

Step 3 — Proceed to open-pull-request

Only after all of Steps 1, 1b, 1c, 2, 2b, and 2c pass (or are legitimately skipped) may you proceed to the open-pull-request skill to create the pull request.

Fail-Fast Behavior

• Stop on the first failure. Do not run Step 1b if Step 1 failed; do not run Step 1c if Step 1b failed; do not run Step 2 if Step 1c failed; do not run Step 2b if Step 2 failed.
• Report which check failed and include its full output so the user can act on it.
• Do not attempt to open the PR until all checks pass.
• The presence-check skip in Steps 1b, 1c, 2b, and 2c (when lint:sh, lint:yaml, format:check:sh, or spellcheck is absent from package.json) is NOT a failure — it is a graceful no-op.

Note on Optional Sub-Steps

Optional sub-steps (Steps 1b, 1c, 2b, and 2c) use a node -e probe against package.json.scripts to detect whether the relevant script is declared. This covers shell lint (lint:sh), YAML lint (lint:yaml), shell format check (format:check:sh), and spell check (spellcheck). This skill installs to ~/.claude/skills/ and runs in any repository; the probe ensures the gate degrades cleanly in repos without these scripts. npm run is used (not pnpm run) for package-manager-agnostic compatibility.

Relationship to Other Skills

• open-pull-request: This skill gates entry to open-pull-request. It must always be invoked first. After both lint and format:check pass, hand off to open-pull-request to complete the PR workflow.
• commit-message-guide: Commits must follow conventional commit format. This skill does not replace that requirement — it adds a validation layer on top of it.