/finalize

description: Pre-ship gate — runs detector, verifies brief and tokens, applies the 10-pass finish bar, ranks findings by feedback hierarchy. Use when the user wants to ship, merge, or finalize a surface and needs a verdict (READY / NOT READY / BLOCKED) before committing.
argument-hint: "[file or surface path; defaults to current working surface]"

Load the `ui-craft` skill. This command produces findings only — do NOT edit code.

---

Step 1 — Brief check (gate)

Look for `.ui-craft/brief.md`.

• Absent: STOP. Output: "No brief found. Run `/brief` first. `/finalize` requires a design brief to distinguish intentional decisions from findings." Do not proceed.
• Present: load it. Extract principles (numbered, in conflict-resolution order). These are the override registry for Steps 4–5.

---

Step 2 — Detector

Run `npx ui-craft-detect` on `$ARGUMENTS` (or current working surface if no argument).

Capture all output. Every Critical detector finding maps directly to a block-ship finding in the report. Preserve detector source labels.

---

Step 3 — Token check

Quick three-question audit (no deep read required):

1. Are all three token layers present (primitives → semantic → component)? 2. Are both light and dark modes explicitly authored (not inverted)? 3. Are all seven token categories represented (color, spacing, radius, shadow, typography, motion, z-index)?

Any "no": flag as Major. Do not block ship. Append a recommendation: "Run `/tokens` to close the gap at [category]."

---

Step 3b — Craft-intent check (full surfaces only)

Applies only when the target is a complete surface (dashboard, landing, auth, settings shell, portfolio) — skip for single components.

1. **Signature bet present?** Scan for exactly one memorable decision from `references/craft-intent.md` §3 (product / auth / marketing lists). Zero → **Major** ("no signature — surface is competent but anonymous; run `/bolder` or `/polish`"). Two or more competing → **Major** ("signature bets stack — keep the strongest, cut the rest"). 2. **Variance matches surface?** Layout risk visibly inconsistent with the surface's DESIGN_VARIANCE default (e.g. experimental asymmetry on an auth form, or a landing that is one centered symmetric column) → **Major**, unless the brief or spec records the deviation. 3. **Craft Read recorded?** If a `.ui-craft/spec.md` section or session declared a Craft Read, verify the built surface matches it (theme, variance, signature). Mismatch → **Major** with the specific delta.

These findings are Major, never Critical — they gate NOT READY, not BLOCKED.

---

Step 3c — Copy self-audit + mechanical counts (marketing surfaces only)

Applies to landings, portfolios, and campaign pages — skip for product shells.

Load `references/recipe-landing.md` and run its Acceptance-bar mechanical checks against the built surface — thresholds (eyebrow count, layout-family budget, hero discipline) live there, not here; this step only names which checks apply and where a violation lands.

1. **Copy self-audit.** Read every visible string (headlines, eyebrows, buttons, captions, alt text, footer). Grammatically broken copy, unclear referents, forced-clever labels ("Field notes" over testimonials, "Quietly trusted by"), or fake-precise numbers with no source → **Major** per `references/copy.md` Copy Self-Audit. 2. **Eyebrow count (mechanical)** — per `references/recipe-landing.md` Eyebrow budget. Over budget → **Major** ("eyebrow flood — delete labels until the count passes"). 3. **Layout-family count (mechanical)** — per `references/recipe-landing.md` Layout-family budget. Any repeat or consecutive-split overrun → **Major**. 4. **CTA intent (mechanical)** — per `references/copy.md` CTAs & Buttons (one label per intent; CTA fits one line at desktop). Violation → **Major**. 5. **Hero discipline** — per `references/recipe-landing.md` Hero discipline. Over budget → **Major**.

---

Step 4 — Finish bar

Load `references/finish-bar.md`. Run all 10 passes in document order. Do not reorder.

**Knob behavior (apply before running):**

• `CRAFT_LEVEL ≤ 6` AND user did not explicitly invoke `/finalize`: run Passes 1, 6, 8 only; mark remaining as N/A (knob-gated).
• `CRAFT_LEVEL ≥ 7` OR user explicitly invoked `/finalize`: run all 10 passes.
• `MOTION_INTENSITY ≤ 3`: Pass 7 = motion-gap audit only; do not fail on absent entrance animations.
• `VISUAL_DENSITY ≥ 8` AND brief documents compressed rhythm: Pass 4 accepts compressed spacing values.

**For each pass:**

• Collect findings.
• Assign severity per the severity map in `finish-bar.md` (Critical / Major / Minor).
• If a finding conflicts with a recorded principle in `brief.md`: downgrade to "Deferred per brief" and cite the exact principle. If no brief principle covers it, it remains a finding regardless.
• Record file:line when available.

---

Step 5 — Feedback hierarchy filter

Load `references/review.md` Feedback Hierarchy section.

Group all findings (detector + token + finish-bar) into three tiers:

• **Value** — does the surface solve the problem the brief defines?
• **Ease of Use** — can the user accomplish the primary task?
• **Delight** — is it polished?

If any Value findings exist: surface them first in the report and add a standing recommendation to defer all Delight findings until Value findings are resolved. This prevents polish work masking broken functionality.

---

Step 6 — Output

Print this report. Do not add preamble.

## Finalize report — <surface name>

**Ship verdict:** READY / NOT READY / BLOCKED

> BLOCKED = any Critical finding present.
> NOT READY = any Major finding present, no Critical.
> READY = zero Critical, zero Major (Minor explicitly accepted).

### Block-ship findings (must fix before merge)
- [Pass / detector source] — [finding] — [file:line if available]

### Major findings (fix or defer with recorded reason)
- [...]

### Minor findings (polish; ship-okay if explicitly accepted)
- [...]

### Deferred per bri