# Run design commands

> Invoke evaluate and refine commands (audit, critique, polish, harden, layout, typeset, and related) with targets, expected artifacts, and verification signals.

- Repository: pbakaus/impeccable
- GitHub: https://github.com/pbakaus/impeccable
- Human docs: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4
- Complete Markdown: https://grok-wiki.com/public/docs/pbakaus-impeccable-adadc04d8de4/llms-full.txt

## Source Files

- `skill/SKILL.src.md`
- `skill/scripts/command-metadata.json`
- `skill/reference/audit.md`
- `skill/reference/critique.md`
- `skill/reference/polish.md`
- `skill/reference/new-work.md`
- `skill/scripts/critique-storage.mjs`

---

---
title: "Run design commands"
description: "Invoke evaluate and refine commands (audit, critique, polish, harden, layout, typeset, and related) with targets, expected artifacts, and verification signals."
---

Design work under `/impeccable` is command-driven: Setup loads project context once, the matching `skill/reference/<command>.md` playbook owns the run, and evaluate commands produce scored reports while refine/enhance/fix commands edit UI and hand off to a final polish pass. Invocation is always `/impeccable <command> [target]` (or a pin shortcut such as `/audit`).

## Prerequisites

| Requirement | Role |
|---|---|
| Skill installed in a supported harness | Hosts the single `impeccable` skill and sub-command router |
| Project cwd at the user repo | `context.mjs` and artifacts resolve relative to the project, not the skill install |
| `PRODUCT.md` (preferred) | Product truth; missing it does not block narrow refinement of existing code, but blocks new-surface / replacement-world work until init |
| `DESIGN.md` (preferred) | Visual system for refine commands; missing file alone is not greenfield |
| Optional: running web dev server | Critique browser overlays; live mode; URL-based inspection |

<Note>
Live mode and the bundled HTML detector are **web-only**. On `ios` / `android` / `adaptive`, do not lead with live or `detect.mjs`; use native audit/adapt variants and platform references instead.
</Note>

## Session setup (every design command)

Setup is non-optional for skill runs. Order is fixed in `skill/SKILL.src.md`:

<Steps>
  <Step title="Load context once">
    Run `node <skill-scripts>/context.mjs` once per session (optionally `--target <path>` for a named surface). Follow its directives; do not re-run it for the next command in the same session.
  </Step>
  <Step title="Load the command playbook">
    For an explicit or clearly implied sub-command, load `skill/reference/<command>.md`. On native platforms, prefer native variants when the Commands table lists them (`audit.native.md`, `adapt.native.md`). For a new surface or replacement visual world, load `new-work.md` instead.
  </Step>
  <Step title="Inspect the target">
    Resolve a concrete file, route, or URL, and at least one representative source of incumbent visual truth (tokens, theme, CSS, component, asset) before editing.
  </Step>
  <Step title="Load the craft floor before UI edits">
    Load `skill/reference/craft-floor.md` immediately before editing UI. Skip it for planning-only evaluate runs (critique/audit report generation).
  </Step>
</Steps>

**Refinement vs redesign:** refinement preserves incumbent identity, behavior, copy, and out-of-scope areas. Redesign keeps product truth and function but replaces the visual world via new-work and a new `DESIGN.md`. Do not smuggle a redesign through polish.

## Command map (evaluate and improve)

User-facing categories come from the skill Commands table. Metadata categories in `scripts/lib/skill-categories.js` (create / evaluate / refine / simplify / harden / system) are for harness menus and differ slightly in naming.

### Evaluate (report only; do not fix)

| Command | What it scores | Primary artifact |
|---|---|---|
| `critique [target]` | UX / design review: Nielsen heuristics, design specificity, cognitive load, personas, detector evidence | Chat report + `.impeccable/critique/<timestamp>__<slug>.md` |
| `audit [target]` | Technical quality: a11y, performance, theming, responsive, implementation integrity (web) or native dimensions | Chat report with P0–P3 findings and recommended commands |

### Refine / enhance / fix (edit, then polish)

| Command | Intent | Typical detector scope |
|---|---|---|
| `polish [target]` | Final shipping quality pass; consumes latest critique snapshot as backlog | Full path judgment + hook/context detector when active |
| `harden [target]` | Errors, overflow, i18n, empty/edge data | Manual stress tests |
| `bolder` / `quieter` / `distill` | Amplify, calm, or strip complexity inside the incumbent world | Visual judgment |
| `onboard [target]` | First-run, empty states, activation | Flow completeness |
| `layout [target]` | Spacing, rhythm, hierarchy | `detect.mjs --json --scope layout` |
| `typeset [target]` | Type roles, measure, hierarchy | `detect.mjs --json --scope type` |
| `colorize` / `animate` / `delight` / `overdrive` | Color, motion, personality, ambitious craft | Command-specific verify lists |
| `clarify [target]` | UX copy, labels, errors | Copy walkthrough |
| `adapt [target]` | Responsive / multi-context (native: `adapt.native.md`) | Viewport / platform checks |
| `optimize [target]` | UI performance | Measure before/after |

Most improve commands end with a handoff to `/impeccable polish` when the targeted change holds.

## How to invoke

<CodeGroup>

```bash title="Evaluate UX"
/impeccable critique src/pages/settings.tsx
```

```bash title="Technical audit (web)"
/impeccable audit src/components/Checkout
```

```bash title="Final polish with target"
/impeccable polish src/pages/settings.tsx
```

```bash title="Scoped enhance"
/impeccable layout src/components/Dashboard
/impeccable typeset src/pages/docs
```

</CodeGroup>

Pin shortcuts (`/audit`, `/polish`, …) resolve to the same playbooks when created with `pin.mjs`. No-argument `/impeccable` never auto-runs a command; it presents a context-aware menu from `routing.md` and optional `context-signals.mjs` / detector hits.

### Target resolution

| User phrasing | Resolve to |
|---|---|
| "the homepage" | Primary source file (e.g. `index.html`, `app/page.tsx`) preferred over a fragile dev-server URL |
| "the settings modal" | Primary component file |
| "this page" | Current URL **or** source file; prefer path when both name the same surface |
| Git-dirty surface | Scope audit/polish to changed markup/style files when signals expose them |

Vague or project-root targets may still run critique/audit, but critique **skips snapshot persistence** when the slug helper cannot derive a stable slug.

## Evaluate: critique

`critique` is dual-assessment UX review. Chat is the primary deliverable; disk snapshots are archive/backlog for later polish.

### Flow

```text
Resolve target → slug check → read ignore.md (optional)
        │
        ├─ Assessment A: design review (no detector)
        └─ Assessment B: detect.mjs + optional browser overlay
        │
   Synthesize report (chat)
        │
   Persist snapshot → trend line → ask user → recommend commands
```

**Hard rules (from `critique.md`):**

- Assessment A and B run as **two isolated sub-agents** when a sub-agent/Task tool exists. Inline single-context is degraded and must open with `⚠️ DEGRADED: single-context (<reason>)`.
- A skipped detector is a failed critique unless `detect.mjs` is missing or crashes after a real attempt.
- Detector findings must not enter synthesis until A is finished.
- Viewable targets use browser inspection when automation is available; local servers started only for critique must be stopped before the final report unless the user keeps them.

### Detector CLI used in Assessment B

```bash
node <skill-scripts>/detect.mjs --json [target]
```

- Pass markup files/directories; do not pass CSS-only paths as the sole target.
- For URLs, skip CLI scan and use browser visualization.
- Exit `0` = clean, `2` = findings (non-advisory).
- Optional browser path injects live-server `detect.js` into a **fresh** tab labeled `[Human]` when mutation is available.

### Report shape (chat)

1. Provenance header: `Method: dual-agent (...)` or degraded banner  
2. Design Health Score (Nielsen 10 heuristics, 0–4; n/a allowed on some Persuade/Experience heuristics; total over applicable max, e.g. `/40` or `/32`)  
3. Design Specificity Verdict (LLM + deterministic scan + overlays)  
4. Overall impression, what’s working, priority issues (P0–P3), persona red flags, minor observations, questions  
5. Trend line after persistence  
6. User questions (or skip with reason) → recommended `/impeccable …` actions, ending with polish when fixes are planned  

### Persistence: `critique-storage.mjs`

Snapshots live under `.impeccable/critique/`. Filenames: `<UTC-stamp>__<slug>.md`.

| Subcommand | Purpose | Exit notes |
|---|---|---|
| `slug <resolved-target>` | Print stable slug from path/URL | Non-zero → skip persistence for this run |
| `write <slug-or-target> <body-file>` | Write snapshot; meta via `IMPECCABLE_CRITIQUE_META` JSON | Prints absolute path written |
| `latest <slug-or-target>` | Print latest snapshot body | Exit `2` if none |
| `trend <slug-or-target> [limit]` | Last N frontmatter rows as JSON (default 5) | — |

Meta keys written by critique:

```json
{
  "target": "<user phrasing>",
  "total_score": 28,
  "max_score": 40,
  "na_heuristics": "7,10",
  "p0_count": 1,
  "p1_count": 2
}
```

Optional prior input: `.impeccable/critique/ignore.md` (plain markdown; matching findings dropped silently). No `ignore` subcommand exists on the helper.

Only **polish** auto-reads the latest matching snapshot as a fix backlog. Other commands do not.

## Evaluate: audit

`audit` is a **technical** code-level report, not UX critique. It documents issues for other commands; it does not apply fixes.

### Web (`audit.md`) — five dimensions, 0–4 each

| # | Dimension | Focus |
|---|---|---|
| 1 | Accessibility | Contrast, motion, ARIA, keyboard, semantics, forms |
| 2 | Performance | Layout thrash, expensive effects, assets, re-renders |
| 3 | Theming | Tokens vs hard-coded colors, dark mode |
| 4 | Responsive | Fixed widths, touch targets, overflow, breakpoints |
| 5 | Implementation integrity | Bundled detector findings verified in context |

**Audit Health Score** total `/20`. Rating bands: 18–20 Excellent, 14–17 Good, 10–13 Acceptable, 6–9 Poor, 0–5 Critical.

Issues use **P0–P3** severity with location, category, impact, standard, recommendation, and a **suggested command** from the available command list. Recommended actions should end with polish when any fixes are proposed. Re-run audit after fixes to rescore.

### Native (`audit.native.md`)

Used when platform is `ios` / `android` / `adaptive`. No browser tooling and no `detect.mjs`. Dimensions become: Accessibility (VoiceOver/TalkBack), Performance, Appearance & Theming, Platform Conformance, Adaptivity — still `/20` with the same report skeleton.

## Refine and enhance: common loop

<Steps>
  <Step title="Establish the system">
    Read `DESIGN.md`, tokens, shared components, and neighboring flows. Classify drift (missing token, one-off, conceptual mismatch, local defect) before editing.
  </Step>
  <Step title="Gather evidence">
    Use the feature at representative sizes and states. For polish, optionally load prior critique:
    `node <skill-scripts>/critique-storage.mjs latest "<resolved target>"` (exit 0 = body; exit 2 = none). Perform an independent pass either way.
  </Step>
  <Step title="Two assessments when the playbook requires it">
    Layout and typeset run a design assessment and a mechanical scan in isolation when sub-agents exist, then synthesize before editing. Do not let detector output anchor the first assessment.
  </Step>
  <Step title="Apply the minimal correct fix">
    Stay inside the incumbent world and named scope. Amplify/calm/distill commands must not invent a new identity; that routes to new-work.
  </Step>
  <Step title="Verify with evidence">
    Answer the playbook’s verify checklist with rendered or source evidence, rerun scoped detect when used, then hand off to polish.
  </Step>
</Steps>

### Polish triage order

1. Broken tasks, data loss, misleading state, inaccessible paths  
2. Missing loading / empty / error / success / disabled / permission states  
3. Flow, hierarchy, responsive, design-system drift  
4. Visual and motion inconsistencies  
5. Code and asset cleanup  

Ship only when the full path is functionally complete and consistent. Bounded verification: one batched inspect (desktop + mobile), one fix batch, at most one confirm round—not open-ended self-QA loops.

### Layout and typeset mechanical scans

```bash
node <skill-scripts>/detect.mjs --json --scope layout [files-or-dirs]
node <skill-scripts>/detect.mjs --json --scope type [files-or-dirs]
```

`--scope` filters detector rules by design domain (`layout`, `type`, and other rule-declared scopes). A clean scan is a floor, not proof of good hierarchy or typography.

Live-mode signature params (when generating live variants for these commands): layout uses coarse `density` → `var(--p-density, 1)`; typeset uses `scale` → `var(--p-scale, 1)`. Full live protocol is out of scope here.

### Harden focus areas

- Extreme inputs (long/short/RTL/CJK/emoji, large lists, empty data)  
- Error and network scenarios  
- i18n expansion (~30–40% text budget), logical CSS properties, `Intl` formatting  
- Overflow: truncation, line-clamp, `min-width: 0` on flex/grid children  

### Craft floor (edit-time)

Before UI edits, craft-floor enforces contrast, spacing rhythm, type measure, motion restraint, control states, themed browser chrome, product copy, and bans on common AI-default scaffolds (identical card grids, kickers on every section, gradient text as emphasis, hard offset shadows outside neobrutalist worlds, and related habits). A pinned brief or committed world overrides the floor when it explicitly earns an exception; model habit does not.

## Expected artifacts and verification signals

| Command | User-visible output | On-disk / side effects | “Done” signals |
|---|---|---|---|
| `critique` | Full structured report in chat; optional questions + command plan | `.impeccable/critique/<ts>__<slug>.md`; trend line | Dual-agent (or explicit degraded) header; scores + P0/P1 counts; snapshot path or skip reason |
| `audit` | Health table `/20`, P0–P3 findings, recommended commands | None required | Dimension scores, integrity verdict, prioritized next commands |
| `polish` and other improve commands | Code/UI diffs in project sources | May consume critique snapshot; no new critique file unless critique re-run | Verify checklist answered with evidence; unexplained detector findings cleared; optional re-critique/re-audit scores improve |
| Scoped layout/typeset | Source edits | Detector JSON during run | Squint/role hierarchy holds; scoped scan clean |

Detector exit codes during mechanical steps: **0** clean, **2** findings. Critique storage `latest` exit **2** means no prior snapshot (not a product failure).

## Recommended sequencing

```text
init / document (once per project)
        │
   critique  ──►  layout | typeset | colorize | clarify | …
        │                    │
   audit (parallel or after) │
        │                    ▼
        └────────────►  polish
                              │
                     re-critique / re-audit (scores)
```

- Start evaluate when you need a backlog; start a named enhance/fix when the defect is already known.  
- End multi-command fix trains with polish.  
- Re-run critique/audit to measure movement; trend lines only work when targets resolve to stable slugs.

## Troubleshooting

| Symptom | Likely cause | Action |
|---|---|---|
| Critique opens with degraded banner | No sub-agent tool, user declined, or spawn failed | Accept sequential run only when declared; prefer dual-agent when available |
| No snapshot written | Unstable slug (root/vague target) or `slug` exit non-zero | Resolve a concrete path/URL; re-run slug |
| Polish ignores prior critique | Slug mismatch or no snapshot for that target | Use the same resolved path; check `latest` exit code |
| Detector skipped / unavailable | Native platform, missing `detect.mjs`, CSS-only target | Use native audit; pass markup; browser path for URLs |
| Audit recommended wrong commands | Recommendations must stay inside available command list | Map findings to evaluate→improve mapping above |
| Redesign attempted via polish | Wrong world-change semantics | Stop; run new-work / replace DESIGN.md intentionally |
| Live or detect suggested on native | Platform is ios/android/adaptive | Use `audit.native` / platform refs; skip HTML detector |
| Hook re-scans after every edit | Design hook enabled | Act on findings; do not add an extra full detect pass in polish when context says the hook already covers it |

## Next

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, no-argument menu, craft-floor gate, and native variants.
  </Card>
  <Card title="Skill commands reference" href="/skill-commands-reference">
    Full sub-command catalog with argument hints and categories.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    In-browser variants after evaluate/improve plans are clear.
  </Card>
  <Card title="Detector rules" href="/detector-rules">
    Rule ids, scopes, and finding shape used by critique and scoped scans.
  </Card>
  <Card title="Initialize product context" href="/init-and-document">
    Write PRODUCT.md and DESIGN.md before first critique or polish.
  </Card>
  <Card title="Project artifacts" href="/project-artifacts">
    `.impeccable/` layout, surface briefs, and context resolution.
  </Card>
</CardGroup>