@delegance/claude-autopilot 5.2.2 → 6.2.2

package/skills/migrate/SKILL.md

@@ -1,83 +1,229 @@
 ---
 name: migrate
-description: Run database migrations against Supabase environments (dev → QA → prod). Validates SQL, executes with ledger tracking, and auto-generates types/supabase.ts.
+description: Framework-agnostic database migration orchestrator. Reads .autopilot/stack.md, runs the configured per-env command (Rails, Alembic, Prisma, Drizzle, golang-migrate, dbmate, flyway, supabase-cli, custom), enforces policy gates, and emits a structured result artifact. For Supabase-specific repos with data/deltas/* layout use `migrate-supabase` instead.
 ---
 
-# Database Migration
+# /migrate — Generic database migration orchestrator
 
-Run a migration through the dev → QA → prod pipeline with validation at each step.
+The thin, framework-agnostic migrate skill. Wraps any migration tool in a uniform contract:
 
-## Usage
+1. Validate `.autopilot/stack.md` against the JSON schema
+2. Resolve the configured skill + apply policy (clean git, manual approval, prod-in-CI gate)
+3. Run `migrate.envs.<env>.command` via `spawn(shell: false)` — no shell injection surface
+4. Capture stdout/stderr, parse the result artifact, append an audit-log entry
+5. Return a `ResultArtifact` to the caller (autopilot pipeline or CLI)
 
-### 1. Identify the migration file
+This skill **does not know what your migration tool is**. It just executes the command you point it at and reports the outcome. Tool-specific behavior (e.g., Supabase's `data/deltas/*.sql` ledger or auto-regenerating `types/supabase.ts`) lives in `migrate-supabase`. Everything else uses this one.
 
-If given as argument, use that. Otherwise find the most recently modified `.sql` file in `data/deltas/`.
+## Usage
 
-### 2. Validate (dry run on dev)
+### CLI
 
 ```bash
-npx tsx scripts/supabase/migrate.ts <file> --env dev --dry-run
+claude-autopilot migrate                  # default env: dev
+claude-autopilot migrate --env qa
+claude-autopilot migrate --env prod --yes # required for prod (manual approval)
+claude-autopilot migrate doctor           # validate stack.md without running
 ```
 
-Present validation results. If errors, help the user fix them before proceeding.
+### Autopilot pipeline
+
+The dispatcher invokes the skill automatically when `migrate` is in the pipeline plan. The skill receives the invocation envelope via `AUTOPILOT_ENVELOPE` and writes its result to `AUTOPILOT_RESULT_PATH`.
+
+## Configuration
+
+Add a `migrate` block to `.autopilot/stack.md`:
+
+```yaml
+schema_version: 1
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "<tool>", args: ["<args>"] }
+      env_file: ".env.dev"
+    qa:
+      command: { exec: "<tool>", args: ["<args>"] }
+    prod:
+      command: { exec: "<tool>", args: ["<args>"] }
+  policy:
+    allow_prod_in_ci: false
+    require_clean_git: true
+    require_manual_approval: true
+    require_dry_run_first: false
+```
 
-### 3. Run on dev
+The `init` flow auto-detects most common toolchains and pre-fills sensible commands. Run `claude-autopilot init` once to bootstrap.
 
-```bash
-npx tsx scripts/supabase/migrate.ts <file> --env dev
+## Examples by toolchain
+
+### Rails (Active Record)
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "rails", args: ["db:migrate"] }
+      env_file: ".env.development"
+    prod:
+      command: { exec: "rails", args: ["db:migrate", "RAILS_ENV=production"] }
 ```
 
-### 4. Ask the user
+### Alembic (Python)
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "alembic", args: ["upgrade", "head"] }
+      env_file: ".env.dev"
+    prod:
+      command: { exec: "alembic", args: ["-x", "env=prod", "upgrade", "head"] }
+```
 
-> "Migration succeeded on dev. `types/supabase.ts` updated. Promote to QA?"
+### Django
 
-### 5. Run on QA
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "python", args: ["manage.py", "migrate"] }
+      env_file: ".env.dev"
+```
 
-```bash
-npx tsx scripts/supabase/migrate.ts --promote qa
+### golang-migrate
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "migrate", args: ["-database", "$DATABASE_URL", "-path", "migrations", "up"] }
+      env_file: ".env.dev"
 ```
 
-### 6. Ask the user
+### Prisma
 
-> "Migration succeeded on QA. Promote to prod?"
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "prisma", args: ["migrate", "dev"] }
+    prod:
+      command: { exec: "prisma", args: ["migrate", "deploy"] }
+```
 
-### 7. Run on prod
+### Drizzle
 
-```bash
-npx tsx scripts/supabase/migrate.ts --promote prod --confirm-prod
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "drizzle-kit", args: ["migrate"] }
+      env_file: ".env.dev"
 ```
 
-### 8. Commit
+### dbmate
 
-After all environments are done, commit the updated `types/supabase.ts` and the migration file:
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "dbmate", args: ["up"] }
+      env_file: ".env.dev"
+```
 
-```bash
-git add types/supabase.ts data/deltas/<migration-file>
-git commit -m "feat: <description of schema change>"
+### Flyway
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "flyway", args: ["migrate"] }
 ```
 
-## Flags
+### Supabase CLI
+
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "supabase", args: ["migration", "up"] }
+```
 
-| Flag | Purpose |
-|------|---------|
-| `--env dev\|qa\|prod` | Target environment |
-| `--dry-run` | Validate only, don't execute |
-| `--force` | Allow destructive operations (DROP, TRUNCATE) |
-| `--confirm-prod` | Required for prod execution |
-| `--promote qa\|prod` | Run missing migrations from source env |
+### Custom script
 
-## Validation Checks
+Anything goes — the dispatcher just runs `exec` with `args`:
 
-The system validates before every execution:
-- Duplicate table/column detection
-- snake_case naming enforcement
-- RLS + policy required for every new table
-- Destructive operation blocking (unless --force)
-- Cross-env prerequisite verification
-- Checksum integrity (modified files are rejected)
-- Promotion chain enforcement (prod requires QA first)
+```yaml
+migrate:
+  skill: "migrate@1"
+  envs:
+    dev:
+      command: { exec: "./scripts/db/migrate.sh", args: ["--env", "dev"] }
+      env_file: ".env.dev"
+```
+
+## When to use `migrate-supabase` instead
+
+Use `migrate.supabase@1` if your repo has the canonical Delegance/Supabase layout:
+- `data/deltas/<timestamp>_<name>.sql` files as the source of truth
+- `.claude/supabase-envs.json` with per-env `dbUrl`
+- Auto-regeneration of `types/supabase.ts` after each apply
+- Built-in promotion chain (dev → qa → prod with checksum verification)
+
+Otherwise, use `migrate@1` with the appropriate command above.
+
+## Policy enforcement
+
+Every run goes through `policy-enforcer.ts` before the command executes. The default policy:
+
+| Setting | Default | Effect |
+|---------|---------|--------|
+| `allow_prod_in_ci` | `false` | Fail if `--env prod` runs in CI without explicit override |
+| `require_clean_git` | `true` | Fail if working tree has uncommitted changes |
+| `require_manual_approval` | `true` | Fail prod runs without `--yes` flag |
+| `require_dry_run_first` | `false` | Force a dry-run before apply (opt-in) |
+
+Override per-environment if your workflow needs it. Tighter is better — these defaults catch real foot-guns.
+
+## Result artifact
+
+When invoked under the autopilot pipeline (`AUTOPILOT_ENVELOPE` set), the skill writes:
+
+```json
+{
+  "contractVersion": "1.0",
+  "skillId": "migrate@1",
+  "invocationId": "<uuid>",
+  "nonce": "<from envelope>",
+  "status": "applied" | "skipped" | "validation-failed" | "needs-human" | "error",
+  "reasonCode": "<short string>",
+  "appliedMigrations": [],
+  "destructiveDetected": false,
+  "sideEffectsPerformed": ["no-side-effects"],
+  "nextActions": []
+}
+```
+
+The generic skill cannot enumerate `appliedMigrations` (that's tool-specific) — it leaves the array empty and reports `status: "applied"` if the command exited 0. Tool-specific result enrichment is the job of skills like `migrate-supabase` that understand the migration ledger format.
+
+## Auditing
+
+Every dispatch — success, failure, dry-run — writes one entry to `.autopilot/audit.log` (chained via `seq` + `prev_hash`). Inspect with:
+
+```bash
+claude-autopilot migrate doctor --audit-tail 10
+```
 
-## Requirements
+## Stack.md schema
 
-- `.claude/supabase-envs.json` with `dbUrl` for each env (gitignored)
-- `postgres` npm package installed
+See `presets/schemas/migrate.schema.json` for the full JSON schema. Validation happens automatically on every dispatch — invalid `.autopilot/stack.md` fails closed before any command runs.

package/skills/simplify-ui/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: simplify-ui
+description: Ruthless subtraction pass on an existing UI — visual/UX reduction only. Use when the user says "cut it down", "too much going on", "too cluttered", "remove noise", "pare down", "less is more", "it's too busy", or wants the page trimmed without rebuilding it. This is the "remove before adding" lens — complementary to /ui (full polish pass), /ui-ux-pro-max (correctness audit), and /make-interfaces-feel-better (craft layer). For code-level deduplication, use the plugin /simplify instead.
+---
+
+# Simplify — remove before you add
+
+You are looking at a UI and cutting what doesn't earn its place. The default answer is **delete**. Every element has to justify why it survives. If you can't state its purpose in a short sentence, it goes.
+
+## The guiding question
+
+For every visible element on the screen, answer:
+
+> "What would break for the user if this weren't here?"
+
+If the answer is "nothing" or "aesthetics", delete it. If the answer names a concrete user failure, keep it — and then see if it can be smaller.
+
+## What to cut, in priority order
+
+### Tier 1 — cut without thinking
+
+1. **Section headers above single-item sections.** "LIABILITY COVERAGE" over a single field is structural vanity.
+2. **Helper text that restates the label.** "Enter your email address" under an "Email" field. Pick one.
+3. **Placeholders that duplicate labels.** Ditto.
+4. **Status pills identical to adjacent counts.** "5/5" badge next to a "5 of 5 complete" progress bar.
+5. **Default-zero values displayed as content.** `$0`, `0%`, `null` — render as empty.
+6. **Decorative icons** that don't carry meaning or affordance. Briefcase next to "Company" is ornament.
+7. **Explanatory captions** for patterns the user already knows ("Click Submit to submit").
+8. **"Powered by…" footers on internal tools.**
+9. **Animated spinners on < 200ms operations.** They flash and look broken.
+
+### Tier 2 — cut after a second look
+
+1. **Duplicate buttons.** "Save" at top and bottom of a form — keep one, usually the bottom if the form is long.
+2. **Multiple paths to the same action.** A "Create quote" primary button + a "+" FAB + a "New quote" menu item.
+3. **Breadcrumbs on 2-level-deep pages.** Overkill; use a back button.
+4. **Card shadows stacked on card borders.** Pick one.
+5. **Grid lines *and* alternating row backgrounds.** Pick one.
+6. **Count/progress indicators that update instantly.** If the user answered the field, they know.
+7. **Summary sentences above tables** that restate what the table shows. ("This table shows quotes. There are 3 quotes.")
+8. **Emoji or flag icons** next to text that already says the same thing.
+9. **Confirmation dialogs for non-destructive actions.** "Save draft?" — just save.
+
+### Tier 3 — cut with caution (verify with the user)
+
+1. **Tooltips on self-explanatory controls.** If the icon is standard (× for close), no tooltip needed — unless a11y is the reason.
+2. **Onboarding hints that persist after first use.**
+3. **Tutorial steps that could be inferred from labels.**
+4. **Analytics-only elements** that don't serve the user (tracking pixels belong in code, not chrome).
+
+## What not to cut (hold the line)
+
+- Labels, even when obvious — they are your a11y surface.
+- Error messages — always keep; tune the copy under `/make-interfaces-feel-better`.
+- Validation — never cut; maybe defer to blur instead of on-change.
+- Skip links and screen-reader-only text.
+- The single "Undo" or "Back" that lets users recover.
+
+## Density rules after simplification
+
+Once you've cut:
+- **3–6 fields per card.** Fewer = sleepy; more = oppressive.
+- **One accent color dominant per card.** Not one per chip.
+- **At most 2 type sizes per card** (label + input/value). Title of the card is the third.
+- **One CTA per screen region.** Multiple = the user has to choose, and they'd rather not.
+- **Zero horizontal scroll.** If the layout forces it on common widths, the layout is wrong.
+
+## Workflow
+
+1. **Screenshot or open the screen.** Read every visible string. Don't cut blind.
+2. **List every distinct element.** Cards, headers, chips, buttons, helper text, icons, images.
+3. **Mark each: keep / cut / reduce.** "Reduce" means the element stays but smaller/shorter/less prominent.
+4. **Cut Tier 1 items immediately.** No discussion.
+5. **Surface Tier 2/3 cuts as proposals** to the user before applying.
+6. **After the cut, measure.** Did vertical density improve? Did the primary action get more visible? If neither, you cut the wrong things.
+
+## Micro-patterns
+
+- **Collapse single-field sections into the parent card.** Don't delete the field, delete the section wrapper.
+- **Merge two adjacent chips with the same color into one.** "Required + Auto-filled" → "Auto-filled (required)".
+- **Replace "X of Y" with "Y - X remaining"** when remaining is what the user cares about.
+- **Fold secondary actions into an overflow menu (⋯).** Don't show 5 buttons when 1 primary + ⋯ works.
+- **Use whitespace as a divider** before reaching for a `<hr>` or border.
+
+## Red flags that you're over-cutting
+
+- Users can't tell which field is required.
+- A keyboard-only user can't move through the form.
+- A screen-reader user can't distinguish regions.
+- The page looks like a wireframe, not a product.
+- You removed something and then had to re-add it in the next session.
+
+## Interactions
+
+- Runs best after `/ui-ux-pro-max` (knows what's broken) and before `/make-interfaces-feel-better` (which adds back *quality*, not noise).
+- Combine with `/ui` for a full pass in one shot.
+- Do not run on a screen that's already minimalist — you'll cut into muscle.
+
+## One rule above all
+
+> Every element survives by earning its pixel count.
+
+If you wouldn't fight to keep it at the next design review, delete it now.

package/skills/ui/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: ui
+description: Opinionated full-pass UI polish on an existing screen — audit, simplify, align, polish in one shot. Use when the user wants to condense, level, align, clean up, tighten, or "make it feel better." Trigger phrases include "condense the UI", "level these out", "clean up and condense", "waste of space", "align better", "feels cluttered", "tighten this up", "polish", "not a great use of space", "make it look right", "fix the alignment". Self-contained — runs all four lenses internally. For subtraction-only, use /simplify-ui. For correctness-only audit, use /ui-ux-pro-max. For craft/feel-only, use /make-interfaces-feel-better. For greenfield design, escalate to frontend-design:frontend-design.
+---
+
+# UI polish pass
+
+You are doing a targeted polish of an **existing** UI, not a greenfield design. The user already has something on screen and wants it to feel better. Match their energy — if they send a screenshot with one complaint, fix that complaint first; don't redesign the whole thing.
+
+Run the four steps below **in order**. Skip steps that don't apply — but never skip step 1 (audit).
+
+## Scope contract — what this skill will and won't do
+
+**Will:** improve hierarchy, spacing, alignment, copy density, interaction states, typographic balance, and visual finish on the existing screen. Touch the components that produce what's on screen and the styles they inherit.
+
+**Won't:** redesign the entire flow, change the data model, restructure information architecture beyond the current screen, introduce a new visual identity, or add net-new features. Preserve the product's existing intent.
+
+If the request needs any of the "won't" items, stop and route:
+- New screen / no concept yet → `frontend-design:frontend-design`
+- Subtraction-only ("just cut, don't polish") → `/simplify-ui`
+- Correctness audit only ("what would a senior designer catch?") → `/ui-ux-pro-max`
+- Craft/feel only ("feels off, lacks soul") → `/make-interfaces-feel-better`
+
+## 1. Audit — look at it, don't guess
+
+Before touching code:
+- **Look at the actual screen.** If the user sent a screenshot, use Read on it. Don't edit blind.
+- **Measure the complaint.** Read the user's words precisely. "Condense" ≠ "redesign." "Level these out" = fix baseline alignment of specific fields, not every field on the page.
+- **Trace the render path.** Find the component(s) that produced what's on screen. Don't assume — grep for the visible strings (section titles, labels, button text) to locate the exact file/line.
+- **Capture the surrounding system.** Note what styles the component inherits: global input classes, grid wrappers, parent padding, font families. The bug is usually upstream of the visible element.
+
+Common blind spots to probe:
+- A "grid alignment issue" is almost always wrapper-margin mismatch, not the grid itself.
+- A "wasted space" complaint is usually `maxWidth` + grid columns + single-field groups compounding.
+- A "doesn't feel right" complaint usually points at typographic hierarchy, not color.
+
+## 2. Simplify — subtract first, add never (almost never)
+
+Before adding anything, ask: **what can I remove?**
+
+Remove these first, in priority order:
+1. **Redundant containers and wrappers.** One `<div>` can usually replace three.
+2. **Subcategory headers for 1-item groups.** "LIABILITY COVERAGE" above a single field burns a row for zero signal. Collapse into the parent.
+3. **Helper text that restates the label.** "Enter your email here" under an "Email" field is noise.
+4. **Default-zero values displayed as content.** `$0` and `0` with grey styling look like empty state — just leave empty.
+5. **Summary/status chips that say what the count already says.** "5 fields required" + a "5/5" badge = one of them goes.
+6. **Decorative icons that don't map to action or meaning.** A briefcase next to "Company Information" is decoration; a checkmark next to "Complete" is meaning. Keep meaning, cut decoration.
+7. **Multiple font sizes in the same row.** If a label and its chip are different sizes for no reason, they should match.
+
+If something genuinely has to be added, it must carry its weight. A new indicator justifies itself by preventing a user mistake or accelerating a decision; otherwise it's noise.
+
+## 3. Align — everything lives on a grid
+
+Misalignment is mostly caused by **inconsistent margins**, not inconsistent grids. Audit these in order:
+
+1. **Wrapper margins across sibling fields.** If `<DateInput>` returns a div with `mb-3` and `<CurrencyInput>` returns a div with `mb-1.5`, an `alignItems: 'end'` grid will put them at different baselines — by exactly the margin delta. Normalize wrappers before touching the grid.
+2. **Input heights across field types.** Date, select, currency, text, and yes/no all need the same `py` value, same `border-width`, same font-size. One `py-3` among a row of `py-2`s looks like a bug to the eye even if the user can't name it.
+3. **Label block heights.** Use `min-h-[20px]` on all labels so a 1-line label and a 1-line label-with-chip occupy the same vertical footprint. Labels that wrap to 2 lines *because they have to* are fine; labels that appear to wrap because the column is 20px too narrow are not.
+4. **Grid column strategies in the same card.** Don't mix `repeat(3, 1fr)` and `repeat(auto-fill, minmax(260px, 1fr))` in sibling rows — column widths will jump between rows for no reason the user understands.
+5. **`align-items`: prefer `end` for forms.** Anchoring inputs to the row's bottom means they line up regardless of how many lines the labels or helper texts above them take.
+
+When a "leveling" complaint comes in, the fix is almost always one of (1) or (2). Check those before rewriting the grid.
+
+## 4. Polish — small things that disproportionately matter
+
+These are low-effort, high-payoff tweaks. Apply them in this order:
+- **Sentence-case labels.** "Requested Effective Date" → "Requested effective date" unless the product strongly prefers title case.
+- **Tighten the padding scale.** `py-2 px-3` for inputs, `p-3` / `p-4` for cards, `gap-2` / `gap-3` for flex rows. Don't invent new values.
+- **Right-size interactive affordances.** Yes/No buttons should match adjacent input heights (same `py`). "Submit" buttons should be one step larger, not three.
+- **Consistent green/red semantics.** One accent color for success (`#40C288` / green-100 bg), one for destructive — don't introduce a third.
+- **Chip restraint.** If multiple chips can appear on one label ("Auto-filled", "Suggested", "Required"), reserve one color per meaning and hide conflicting combinations (e.g., a "Suggested" chip disappears the moment "Auto-filled" applies).
+- **Hover states that mean something.** Border color shift > shadow shift > scale transform. Don't use animation where color communicates the change.
+- **Motion only for state changes the user caused.** Page-load staggers are cheap delight; surprise-wiggle on data arrival is usually annoying.
+
+## Opinionated defaults
+
+When the user hasn't specified, default to these and move on:
+- **Content width:** 1200px max. Sidebar + main = 220 + 980 with 24–32px gutters. Wider reads as "enterprise app with too many fields"; narrower cramps.
+- **Card padding:** `px-4 py-3`. Cards tighter than this feel underbaked; looser feels sleepy.
+- **Grid gap between fields:** `12px` horizontally, `12px` vertically. Don't exceed 16px unless there's a strong reason.
+- **Typography scale:** label 11–12px semibold, input text 14px regular, body 13px regular, section title 14–15px semibold. Avoid introducing a 4th or 5th size.
+- **Borders:** `1px solid` at all times. `border-2` reads as "please notice me" — reserve it for selected/active states, not defaults.
+- **Corner radius:** `rounded-lg` (8px) for inputs and cards, `rounded-full` only for pills/avatars.
+
+## Anti-patterns — flag these on sight
+
+- A single-field "section" with its own uppercase header.
+- `maxWidth` > 1280 on a form-heavy page.
+- `gap: 4` next to `gap: 16` inside the same card.
+- `mb-3` on some wrappers and `mb-1.5` on others, in the same grid.
+- `border-2` on non-selected default states.
+- Helper text that is grammatically a sentence but visually the same size as the label.
+- "Auto-filled" and "Suggested" chips shown simultaneously on one field.
+- Yes/No buttons noticeably taller than neighboring selects.
+- Progress bar counts that include optional fields in the denominator. "X of Y required" is what users actually want.
+- Content that expands to fill whatever width it's given (currency inputs stretched to 600px for a 6-digit number).
+
+## Workflow the user sees
+
+1. **Restate the complaint in one sentence** so the user knows you understood. ("Fields don't line up in Coverage Details" — not "let me analyze the UI.")
+2. **Diagnose out loud.** Say what's causing it. ("Date wrapper has `mb-3`, currency wrapper has `mb-1.5` — that's the 6px offset.")
+3. **Make the minimum edit that fixes it.** Don't bundle unrelated cleanup.
+4. **Say what was left alone and why**, if there are obvious nearby things you chose not to touch.
+5. **Don't commit** unless the user asked.
+
+## When to escalate
+
+Hand off to a different skill when:
+- Request is "design a new X from scratch" → `frontend-design:frontend-design`
+- Request is "write a comprehensive spec for the redesign" → `superpowers:writing-plans`
+- Request is "this feels bad, but I don't know why" and you've already done a polish pass → ask targeted questions before another round.
+
+## Verification
+
+After edits, state which complaint was addressed and which were not. If the user sent one screenshot showing one row of fields misaligned, don't report "condensed the whole page" — they'll suspect you did more than asked.
+
+If you can run the dev server and re-check visually, do. If you can't (backend-only session, no browser access), say so explicitly: "I can't verify visually — please reload and confirm."

package/skills/ui-ux-pro-max/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: ui-ux-pro-max
+description: Senior-level UX audit of an existing screen — produces a prioritized findings list, does NOT auto-fix. Use when the user asks for a "pro review", "expert critique", "ux audit", "senior take", "what would a designer catch", "is this production-grade", or wants rigorous evaluation of information architecture, cognitive load, accessibility, heuristic violations, and error states. Applies Nielsen heuristics, Fitts/Hick, WCAG, and measurable UX principles — not vibes. Complements /simplify-ui (subtraction) and /make-interfaces-feel-better (craft). For one-shot polish that includes audit + fix, use /ui instead.
+---
+
+# UI/UX Pro Max — the senior review
+
+Apply senior-designer rigor to an existing screen. This is **evaluation**, not creation. Do not rebuild from scratch; produce a prioritized list of defects with evidence.
+
+## Rules of engagement
+
+- **No vibes.** Every finding names a principle (heuristic, law, or WCAG rule) and points at a specific element.
+- **No rewrites during audit.** First list the findings; fix only what the user explicitly approves.
+- **Prioritize by user impact.** Severity ranks: blocker (user cannot complete task) > major (noticeable friction) > minor (polish) > nit.
+- **Cite evidence from the screen.** Don't generalize from principle — point at the component, class name, or pixel distance.
+
+## 1. Heuristics pass (Nielsen + practical extensions)
+
+Walk the screen against these in order. Flag violations with severity.
+
+1. **Visibility of system status** — every long operation shows progress; every state change is visible within 1s.
+2. **Match with real-world language** — field labels use the user's vocabulary, not internal schema names (`bop_160_occupancy` → "Occupancy Type").
+3. **User control & undo** — destructive actions have confirm + undo; optimistic updates reveal failures.
+4. **Consistency** — same action uses same verb/icon/color/position across the app. Note inconsistencies by exact location.
+5. **Error prevention** — disable buttons that can't act yet, constrain inputs (dates, phone masks), validate on blur.
+6. **Recognition over recall** — never ask users to remember what they typed on page 2 to fill page 3.
+7. **Flexibility (power users)** — check for keyboard shortcuts, bulk actions, saved state, intelligent defaults.
+8. **Aesthetic & minimalist design** — every visible element earns its spot; label + chip + helper + placeholder overlap is noise.
+9. **Help users recognize/recover from errors** — error messages name the field, explain the problem, propose a fix.
+10. **Help & docs in-context** — help text next to the field, not on a separate help page.
+
+## 2. Physics + cognition
+
+- **Fitts' Law** — target size ≥ 44×44 px for touch, ≥ 24×24 px for desktop; dangerous targets need *more* distance and size, not less. Close-buttons on toasts that are 18px is a defect.
+- **Hick's Law** — flag dropdowns > 12 options without search. Lists > 5 items on a form field should be grouped or filtered.
+- **Miller's 7±2** — flag screens asking for > 9 decisions at once; break into steps or collapse the optional ones.
+- **Doherty threshold** — anything > 400ms without feedback reads as "broken". Note any interaction that is synchronous and slow.
+- **Serial-position effect** — important CTAs go first or last, not middle.
+
+## 3. Information architecture
+
+- **Section cardinality** — can a user explain what goes in each section in one sentence? If no, the section is doing two jobs.
+- **Field grouping** — fields that are answered from the same mental context go together (address block, employee counts, coverage limits). Cross-group fields that live together are a defect.
+- **Progressive disclosure** — required first, optional expandable, rarely-used hidden. Note any section that leads with optional fields.
+- **Scannability** — can the user scan and find the fields they've already answered in < 2 seconds? Test by reading only bold text and labels.
+- **Density** — count fields per card. Under 3 is sleepy, over 9 is oppressive; target 3–6.
+
+## 4. Accessibility (WCAG 2.2 AA baseline)
+
+Run this as a pre-merge gate, not a "nice to have".
+
+- **Color contrast** — body text ≥ 4.5:1, large text ≥ 3:1, UI components ≥ 3:1. Chips and pill backgrounds usually fail here; measure them.
+- **Focus visible** — tab through the form. Every focusable element needs a visible ring *different* from the hover state.
+- **Labels programmatically associated** — every input has a `<label for>` or `aria-labelledby`. Placeholder-as-label is a defect.
+- **Error identification** — errors are announced to screen readers via `aria-live="polite"` or `aria-invalid`.
+- **Motion preferences** — any non-essential animation respects `prefers-reduced-motion`.
+- **Target size** — per WCAG 2.2, interactive targets ≥ 24×24 CSS px or have sufficient spacing.
+- **Form autofill** — inputs use appropriate `autocomplete` attributes (email, tel, address-line1, …).
+
+## 5. States — all of them
+
+For every interactive component, check: default, hover, focus, active, disabled, loading, empty, error, success. Note which states are missing or visually identical.
+
+## 6. Microcopy
+
+- **Button verbs match action.** "Submit" is rarely right — "Send quote", "Save draft", "Request bind" are better.
+- **Labels as statements, not questions.** "Do you own the building?" → "Building ownership" with a Yes/No.
+- **Placeholders don't repeat the label.** "Email" label + "Enter your email" placeholder = pick one.
+- **Error messages propose the fix**, not just the problem.
+- **Empty states** tell users what will appear here and what to do to make it appear.
+
+## Deliverable
+
+A severity-sorted list shaped like this:
+
+```
+[blocker] Inputs are rendered without associated <label> — WCAG 1.3.1 violation — app/portal/quotes/new/info/page.tsx:3486
+[major] "Application Progress" denominator counts optional fields; misleads users about completion — sidebar line 5049
+[major] Yes/No buttons (px-6 py-3) are 44px tall next to 32px select inputs — violates consistency heuristic — acord-question-bridge.tsx:67
+[minor] "Auto-filled" + "Suggested" chips render simultaneously on same field — visual noise — page.tsx:3470–3476
+[nit] Section 2 header uses Playfair Display at 26px; rest of form is Figtree — typographic inconsistency
+```
+
+After the list, stop. Wait for the user to pick which to fix. Do not batch everything into one edit — that's a different skill.
+
+## Known interactions
+
+- Pair with `/simplify-ui` after this audit: its job is to cut what yours identifies as low-value.
+- Pair with `/make-interfaces-feel-better` after the structural fixes land: its job is the craft layer above correctness.
+- If your audit reveals the screen needs a redesign, not a polish, escalate to `frontend-design:frontend-design`.