# Preflight Check

> This skill should be used when the user asks to "pre-flight check", "validate before commit", "validate before PR", "validate before deploy", "is this ready to ship", "check readiness", "run pre-flight", "validate project state", or wants context-aware validation across commit/PR/release/deploy boundaries. Orchestrates universal validators (lint, tests, types, version sync, stale refs, docs, hook conflicts) and supports generating new custom validators.

- Skill: `data-wise/preflight-check` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add data-wise/preflight-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/data-wise/preflight-check/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: Data-Wise (https://skillmd.com/u/data-wise)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/data-wise/preflight-check

---


# Pre-flight Check

Universal pre-flight validation across commit, PR, release, and deploy boundaries. Orchestrates the validator suite that lives under `.claude-plugin/skills/validation/` and dispatches the right check set for the current context.

## When to Use

- User asks "is this ready to commit / PR / release / deploy?"
- User says "pre-flight", "validate", "check readiness", or runs `/craft:check`
- Before staging a commit, opening a PR, or kicking off the release pipeline
- After a session of edits, to confirm nothing regressed
- When the user wants to scaffold a new custom validator (`gen-validator` flow)

## Scope Boundary (Read This First)

This skill is broader than its siblings — understand the seams:

| Skill | Concern | Does NOT cover |
|---|---|---|
| **preflight-check** (this) | Cross-cutting validators: lint, tests, types, version sync, stale refs, link integrity, hook conflicts, CLAUDE.md health, docs staleness, badge URLs, formula desc, skill standards (release-gated) | Detection logic, release orchestration, guard rule editing |
| `project-detector` (`skills/ci/`) | Detect project type / build tool / test framework to recommend a CI template | Validation orchestration. It answers "what kind of project is this?" not "is it ready?" |
| `release` (`skills/release/`) | The full release pipeline (version bump → PR → merge → GitHub release → Homebrew → verify). Calls this skill internally for its Step 2 pre-flight gate | Standalone commit/PR validation |
| `guard-audit` (`skills/guard-audit/`) | Tune `branch-guard.sh` rules via `.claude/branch-guard.json` to reduce false positives | Running checks. It edits guard config, doesn't validate the project |

**Rule of thumb:** if the user wants to *run validators*, use this skill. If they want to *change which rules block them*, route to `guard-audit`. If they want a *release*, route to `release` (which calls back into this skill).

## Backing Commands

- `/craft:check` — primary entry point; mode-aware, context-aware orchestrator

The skill should prefer invoking the commands rather than re-implementing their logic. The commands handle dry-run, orchestration, and hot-reload validator discovery.

## Context Flags (`--for ...`)

Pick the check set by what the user is preparing for. This is the primary axis of behavior:

| `--for` | Run when user is about to... | Adds beyond default |
|---|---|---|
| `commit` | Stage and commit on a feature branch | Fast lint on changed files, fail-fast tests, basic version-sync, no-secrets scan |
| `pr` | Open a PR to dev/main | Full lint, full test suite, coverage ≥ 80%, internal links, merge-conflict detect, stale-ref scan, hook-conflict audit, CLAUDE.md health |
| `release` | Cut a release (called by `skills/release/`) | Full audit: strict lint, all tests + coverage ≥ 90%, all links, full version audit (fatal on drift), security audit, badge URL both-branch check, formula desc count check |
| `deploy` | Deploy docs site or downstream artifact | Same as `release` minus formula-desc; plus tag-exists check |

If no `--for` is specified, run the "general" check set (lint + tests + git status + docs if changed).

## Mode-Aware Behavior

Modes are orthogonal to `--for` — they tune verbosity, fail-fast, and threshold strictness:

| Mode | Budget | Behavior |
|---|---|---|
| `default` | < 30s | Fast path, fail-fast, summary output |
| `debug` | < 120s | Verbose output, no fail-fast, surface all warnings |
| `thorough` | < 180s | Full lint + types + security + docs sweep |
| `release` | < 300s | Strictest thresholds (coverage ≥ 90%, version drift = fatal) |

Mode applies to the hot-reload validators too via `$CRAFT_MODE` — see the validator template generator output for the per-mode threshold table.

## Recommended Flow

1. **Confirm intent.** Ask which context (`commit`/`pr`/`release`/`deploy`) if the user didn't say. Default to the most conservative reasonable guess based on the current branch (`feature/*` → `commit` or `pr`; `dev` → `release`).
2. **Dry-run first when stakes are high.** For `--for release` or `--for deploy`, suggest `/craft:check --for release --dry-run` to preview the validator plan and time estimate before executing.
3. **Run the appropriate command.** Invoke `/craft:check --for <context> [mode]`. Let the command's Step 0 plan + AskUserQuestion gate handle confirmation.
4. **On failure, route specifically.** Don't just dump errors — point at the right follow-up:
   - Lint failures → suggest `/craft:ci:fix` or `/craft:code:lint`
   - Version drift → suggest `/craft:check --version release` for the focused validator
   - Stale refs from a rename → list the files that need updating
   - CLAUDE.md staleness → suggest the docs/claude-md skill (sync)
   - Hook-conflict false positives → route to `guard-audit` skill
5. **On all-green, summarize and stop.** Don't recommend "next steps" past the immediate gate the user asked about (per feature-branch-workflow rules: no PR-merge nudging).

## Validator Generation (Separate Operation)

Generating a new custom validator is a *distinct* workflow from running checks. Trigger conditions:

- User says "create a validator", "add a custom validator", "generate a validator template"
- User wants to extend `/craft:check` with project-specific validation logic

`check:gen-validator` was folded into this skill in the v4 consolidation (Phase 3.5,
2026-07-12) — no standalone command remains. Full scaffolding walkthrough (template
structure, interactive-mode prompts, mode-aware threshold examples, the community
validator marketplace convention): `references/gen-validator.md`.

In that flow:

1. Generate the validator file directly under `.claude-plugin/skills/validation/<name>.md`
   with `hot_reload: true` (see `references/gen-validator.md` for the full template).
2. After generation, suggest a smoke test: `CRAFT_MODE=default bash .claude-plugin/skills/validation/<name>.md` then `/craft:check` to confirm auto-discovery.

**Do not** auto-generate a validator while the user is running checks — these are independent concerns. If both are in flight, finish the check pass first.

## Context Header (`--context`)

The check command supports a `--context` flag that *skips* validation and emits only a one-screen session header (project, branch, worktree, base, guard status, phase, test count, docs status, insights). When the user asks "what's the state of this branch?" or "what session am I in?", prefer `/craft:check --context` over running validators. It's read-only and < 1s.

## Output Conventions

The backing command uses box-drawing output (see `commands/check.md`). When this skill summarizes results in chat, mirror that structure compactly:

```text
Project: <name> (<type>)        Context: <for-value>      Mode: <mode>
Lint:    PASS / N issues
Tests:   N/M passed
Version: in sync / DRIFT (file:line)
Docs:    GREEN / YELLOW / RED
Status:  READY / BLOCKED — <reason>
Next:    <single actionable suggestion or none>
```

Keep summaries terse. The command's own output is the system of record.

## Anti-Patterns

- **Don't** re-implement project detection here — defer to `project-detector` via the command.
- **Don't** edit branch-guard rules — that's `guard-audit`.
- **Don't** chain into the release pipeline — let the user invoke `release` explicitly. This skill stops at "READY FOR RELEASE."
- **Don't** silently expand scope. If the user asked `--for commit`, don't also run the release-tier validators just because "they're cheap." Mode budgets exist for a reason.
- **Don't** fix issues the validators report unless the user asks. Surface, then wait.

## See Also

- `commands/check.md` — full check command spec (validators, modes, dry-run output)
- `references/gen-validator.md` — validator scaffolding (folded from a command into this
  skill in the v4 consolidation)
- `.claude-plugin/skills/validation/` — hot-reload validator directory
- `skills/release/SKILL.md` — orchestrates this skill at Step 2 of releases
- `skills/ci/SKILL.md` — project detection (used internally to pick check set)
- `skills/guard-audit/SKILL.md` — tune what blocks operations (not what validates them)