Preflight

preflight — Multi-Dimensional, Codebase-Grounded Quality Audit

CodeOps Skills Version: 3.20.0

Run a rigorous quality audit of the artifact named in $ARGUMENTS, grounded in the actual codebase. Find every issue, ambiguity, contradiction, gap, and risk; verify every claim and assumption against the real code; present each finding with options + a recommendation; iterate until the artifact passes clean.

Resolve artifact paths layout-aware. A requirements set or plan named in $ARGUMENTS lives at a flat path (requirements/, plans/<feature>/) or, in a nested-layout repo, under codeops/features/<f>/… — resolve it via ../../_shared/layout-convention.md. If the target feature is ambiguous in a nested repo, ask; never guess.

preflight --continue resumes an interrupted session (see Session resume).

Artifact reference formats

Core directive

You are a senior technical reviewer performing a formal quality audit GROUNDED IN THE ACTUAL CODEBASE. Find every defect, gap, ambiguity, contradiction, and risk in this artifact — and verify every claim, reference, and assumption against the real code. Be thorough, systematic, relentless. For every issue, analyze the options and present your recommended resolution. Do NOT fix anything silently — every finding must be presented to the user for decision.

You are NOT a rubber stamp. You are actively trying to break the artifact — and to reality- check it against the codebase it targets. Assume it has issues until proven otherwise.

Without codebase grounding, preflight is nothing but a document-correction exercise. The entire value depends on holding the artifact accountable to the real files, architecture, patterns, and dependencies.

The creation-time gates inside the make_plan skill (its Phase 1C gate) and the make_requirements skill (its Phase 2B gate) catch issues during authoring. Preflight is the post-creation safety net — fresh eyes that catch what those gates missed and what evolved since.

The 8-step protocol (overview)

1. Load & identify artifact type — read the complete artifact; classify it as a requirements set, implementation plan, or ad-hoc document. Load the project's CLAUDE.md (or detected project conventions) and any Ambiguity Register (00-ambiguity-register.md).
2. 🚨 Codebase Reconnaissance — NON-NEGOTIABLE. Build a real understanding of the code the artifact targets, map every document reference to actual code, then present a Codebase Context Summary. This is what separates a real preflight from a document-correction exercise. Full what/why/how table, recon depth by artifact type, and the summary template are in dimensions.md. 2b. Classify the domains — before the scan, classify the system the artifact targets using ../../references/domains/selection.md, using the recon from Step 2 as its evidence. Present the selection with that evidence and let the user amend it. The audit then inherits the selected domains' question sets: their checklists become additional things the artifact must have answered, and an unanswered one is a finding like any other. Domains add to the 13 dimensions; they never narrow them. This runs with or without a quality profile — it dispatches no agent and emits nothing.
3. 13-dimension scan — review the artifact across all 13 dimensions (below), every check informed by Step 2. Depth adapts by artifact type. Full detail in dimensions.md.
4. Compile the Preflight Report — every finding gets a numbered PF-NNN entry with severity. Templates and report header in report-format.md.
5. Present findings & collect decisions — grouped by severity, paced by the batch rules in report-format.md (they are authoritative), recording the user's decision on every finding.
6. Determine pass/fail — Clean / Passed / Passed With Notes / Blocked (see Pass tiers).
7. Apply fixes (only if requested) — preflight is a review protocol, not a modification one. Never apply fixes without explicit instruction.
8. Roadmap sync — after a pass, advance the target's row via the roadmap skill if a roadmap exists.

The 13 dimensions (names only — detail in dimensions.md)

1. Ambiguities
2. Implicit Assumptions
3. Logical Contradictions
4. Completeness Gaps
5. Dependency Issues
6. Feasibility Concerns
7. Testability
8. Security Blind Spots
9. Edge Cases
10. Scope Creep Indicators
11. Ordering & Sequencing
12. Consistency
13. Codebase Alignment — the master reality check (10 sub-checks; entirely codebase-grounded)

Scan all 13 every time. Depth adapts (🔥 Deep / Standard / Light) by artifact type — see the dimension-depth-by-artifact-type table in dimensions.md. Dimension 13 and its 10 sub-checks (Phantom References, Stale Assumptions, Architecture Mismatch, Impact Blindness, Redundancy, Test Impact, Dependency Reality, Convention Violations, Scope vs. Reality, Migration & Compatibility) are the heart of the audit — read that section before scanning a plan.

Severity scale

Calibrate honestly — never inflate to get attention, never deflate to avoid conflict.

Pass tiers

A clean first-scan pass is cause for celebration, not suspicion. Never invent findings to justify the review — if the artifact is solid, say so.

Report persistence

Save the report as a permanent file alongside the artifact:

The report is separate from the Ambiguity Register (decisions made during creation) — see report-format.md for the relationship and cross-referencing.

Parallelizing the scan (clustered fan-out)

When the session supports subagents, the 13-dimension scan fans out as ~5 parallel preflight-auditor dispatches — one per dimension cluster, an exact partition defined in ../../_shared/quality-profile.md (① document soundness · ② grounding · ③ delivery · ④ risk · ⑤ fit). Each dispatch carries the header + packet from that doc (the artifact, ONE cluster, and the codebase context its dimensions need). --thorough expands the fan-out to one dispatch per dimension. Recon reads may still go to read-only explore agents, and the codebase-scout may ground individual claim-checks (≤3 scout dispatches per run).

The lead context always merges the returned PA-NNN findings into the single PF-NNN sequence (dedupe across clusters, renumber, keep severities honest), runs the verdict synthesis, and owns every user interaction — auditors never talk to the user. Sequential scanning remains correct when subagents are unavailable.

Telemetry: with an active quality profile, emit preflight_run when the report is compiled, finding_decided per finding immediately after each ruling batch, and gate_summary (gate preflight_gate) at the verdict step (one codeops-events.sh emit call each; failures never block the scan). preflight_run carries the scan's own finding counts — findings_critical, findings_major, findings_minor, counted from the compiled report before any ruling. A scan that found nothing emits explicit zeros; a scan that reported findings must never emit zeros, because that is what makes a silent scan and a clean artifact distinguishable afterwards.

Iterative re-scanning

Run preflight as many times as needed. Iteration 2+ verifies prior fixes, checks for regressions, and re-scans all 13 dimensions. Findings numbered continuously — if iteration 1 ends at PF-012, iteration 2 starts at PF-013; numbers never reuse. Loop until a clean pass, the user stops, or only 🔵 observations remain. Full re-scan header and numbering rules in report-format.md.

Session resume (save-as-you-go)

Continuity notes are written as you go, not on interruption — a hard crash must lose at most one dimension of work:

• Checkpoint cadence: update _preflight-notes.md (in the artifact directory, next to where the report will be saved) after the recon step completes and after EACH dimension finishes — never only when a session "feels long".
• Schema (minimal): the artifact path + its git ref (or mtime) at scan start; completed dimensions; findings so far (numbers + one-liners); pending dimensions; user decisions collected; recon notes (key files examined, references mapped).
• On preflight --continue: read the notes, then run the staleness check — if the artifact changed since the recorded ref/mtime, say so and re-scan the affected dimensions rather than trusting stale findings. Summarize where you left off and resume from the next unscanned dimension. Do NOT repeat reconnaissance — reuse the notes; re-read specific files only when a finding needs deeper inspection.
• On completion: delete _preflight-notes.md — a stale notes file must never be picked up by a later scan of a different artifact (the schema's artifact reference is the second guard: a mismatch is treated as stale and reported).

Same-agent bias awareness — 🚨 NON-NEGOTIABLE

When the same model created the artifact and reviews it, systematic blind spots are likely. You MUST counteract this. If the artifact was created in the current session, note it at the top of the report (⚠️ SAME-SESSION REVIEW … consider a new session for review independence). For any behavior bound to an external standard, cite the specific standard text rather than reasoning from memory; flag explicitly if you can't. Before concluding the scan, run the adversarial-question checklist. Full safeguards in report-format.md.

Key agent behavior rules

Grounded Options & Recommendations (coding standards → Working style) apply here. Before presenting options/findings/recommendations: filter out non-viable ones (no strawmen; ≥2 only when ≥2 are genuinely viable, else present the single viable path and name what was rejected), second-guess each, verify any code-modifying option against the actual current code (cite file:line), and lead with a recommendation backed by grounded reasoning. Match ceremony to stakes — the user decides. Recommendation hardening: apply _shared/recommendation-hardening.md — for high-stakes findings (CRITICAL/MAJOR severity) spawn one independent challenger and reconcile before recording the recommendation; for all consequential findings run the in-context layers and close with the Confidence: / Hardening: disclosure.

• Be adversarial, not hostile — findings should feel helpful, not critical.
• Specificity over volume — one precise finding beats ten vague ones; never pad.
• Don't invent problems — a clean pass is a valid, trustworthy outcome.
• Options must be real — no strawman options to flatter a recommendation.
• Respect previous decisions — don't re-litigate Ambiguity Register entries without new info.
• Cross-document awareness — many issues only surface when reading docs together.
• Codebase evidence is not optional — for dimensions 2, 4, 5, 6, 11, 13 (and any claim about the code) cite the specific file and code; if you can't verify, say so explicitly.
• Reconnaissance is proportional — read what the artifact touches and its direct dependents; don't read the whole codebase for a small artifact.

Related skills & integrations

• After the make_requirements skill → preflight requirements (catches issues past its Phase 2B gate).
• After the make_plan skill → preflight <feature> (catches issues past its Phase 1C gate).
• Before the exec_plan skill → if no 00-preflight-report.md exists, exec_plan MAY softly suggest running preflight first (soft suggestion, not a hard gate).
• The grill_me skill interrogates the user's intent before creation; preflight audits the created artifact against the code after. Complementary, opposite directions.
• The roadmap skill — a passing preflight advances the target's row to RD Preflighted (🔎) or Plan Preflighted (🔬); a BLOCKED outcome does not advance it.
• Reference your project's coding/testing standards (CLAUDE.md) for what plans/requirements should target.

Standalone: when used without a follow-up, finish the scan + resolution, present the final status, then ask the user what to do next (apply fixes, create a plan, start execution, or review specific findings).

Authority mode — --auto-design (optional)

--auto-design delegates eligible technical design decisions for this workflow chain, so a run stops for product, security, financial, legal, and destructive choices — not for a data-structure pick. The complete policy (invocation contract, eligibility boundary, reserved list, strongest-option procedure, provenance record, bounded escalation, invalidation) lives in ../../_shared/auto-design.md and is deliberately not restated here.

Parse it FIRST, before resolving any target. Exactly one standalone --auto-design token before the first -- sentinel activates the mode and is then removed from the arguments; zero occurrences means normal mode; more than one stops with a usage correction. Lookalikes (--auto-designer, --auto-design=true, bare auto-design) and anything at or after the sentinel are ordinary content. Announce activation in-session before making any delegated decision.

It grants no action permission and is independent of the commit mode. Every delegated resolution carries the full provenance record into the artifact that owns the decision.