# Skill commands reference

> Catalog of `/impeccable` sub-commands with argument hints, categories, reference files, and native variants for audit and adapt.

- 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/scripts/command-metadata.json`
- `skill/SKILL.src.md`
- `scripts/lib/utils.js`
- `scripts/lib/skill-categories.js`
- `skill/reference/audit.native.md`
- `skill/reference/adapt.native.md`
- `skill/reference/doctor.md`

---

---
title: "Skill commands reference"
description: "Catalog of `/impeccable` sub-commands with argument hints, categories, reference files, and native variants for audit and adapt."
---

Impeccable exposes **one** user-invocable skill (`impeccable`) with **23** design sub-commands. Invocation is `{{command_prefix}}impeccable <command> [args]` (for example `/impeccable audit hero`, `$impeccable polish`). The command prefix is provider-specific (`/` vs `$`). Each design command loads a playbook under `skill/reference/<command>.md` after Setup runs `context.mjs`.

Canonical sources:

| Surface | Path | Role |
|---|---|---|
| Router table | `skill/SKILL.src.md` → `## Commands` | Human-facing command list, router categories, reference paths, native variants |
| Metadata | `skill/scripts/command-metadata.json` | `description` + `argumentHint` per command (pin + build) |
| Transformer categories | `scripts/lib/skill-categories.js` | `SKILL_CATEGORIES` / `CATEGORY_ORDER` for generated argument-hint grouping |
| Suggestion list | `scripts/lib/utils.js` → `IMPECCABLE_SUB_COMMANDS` | Names expanded into `{{available_commands}}` in skill text |
| Pin allowlist | `skill/scripts/pin.mjs` → `VALID_COMMANDS` | Commands that may be pinned as standalone shortcuts |

Two utility routes sit **outside** the 23 and are **not** design commands: `hooks` and `doctor`. Pin/unpin is a script, not a sub-command in the table.

## Invocation and routing

| Case | Behavior |
|---|---|
| No argument | Load `reference/routing.md`; present a context-aware menu; **never auto-run** a command |
| Explicit or clearly implied command | Load that command’s reference (native variant when `setup.platform` is native) and follow it |
| Ambiguous between two commands | Ask once |
| Otherwise | Treat as general design work: missing PRODUCT.md on a new surface or replacement world goes through `init` then `new-work`; narrow refinement of existing code proceeds on the incumbent implementation |

Aliases and specials:

| Name | Status | Notes |
|---|---|---|
| `teach` | Alias of `init` | Not a separate catalog entry |
| `craft` | Deprecated compatibility alias | No extra behavior; ordinary new-work uses the same flow as a natural build/redesign request |
| `shape` | Active | Owns task discovery; enters new-work only for visual-world / surface-concept decisions |

Parent skill frontmatter argument shape (after build substitution):

```text
[{{command_hint}}] [target]
```

`{{command_hint}}` is filled from `command-metadata.json` keys grouped by `SKILL_CATEGORIES` order (`create · evaluate · refine · simplify · harden · system`), joined with `|` inside a group and ` · ` between groups. Commands missing a `SKILL_CATEGORIES` entry (today: `craft`) stay out of that generated hint group but still route.

## Two category taxonomies

Do not conflate them.

### Router categories (`SKILL.src.md` table)

Used in the skill’s Commands table and no-argument menu grouping:

| Router category | Commands |
|---|---|
| Build | `craft`, `shape`, `init`, `document`, `extract` |
| Evaluate | `critique`, `audit` |
| Refine | `polish`, `bolder`, `quieter`, `distill`, `harden`, `onboard` |
| Enhance | `animate`, `colorize`, `typeset`, `layout`, `delight`, `overdrive` |
| Fix | `clarify`, `adapt`, `optimize` |
| Iterate | `live` |

### Transformer categories (`SKILL_CATEGORIES`)

Used by the provider build to group the parent skill’s `argument-hint` and related harness metadata:

| Category | Commands |
|---|---|
| `create` | `shape` (parent skill name `impeccable` also maps here; not a sub-command) |
| `evaluate` | `critique`, `audit` |
| `refine` | `typeset`, `layout`, `colorize`, `animate`, `delight`, `bolder`, `quieter`, `overdrive` |
| `simplify` | `distill`, `clarify`, `adapt` |
| `harden` | `polish`, `optimize`, `harden`, `onboard` |
| `system` | `init`, `document`, `extract`, `live` |
| *(unmapped)* | `craft` — deliberately omitted so it stays out of the generated argument-hint while still routing |

`CATEGORY_ORDER`: `create`, `evaluate`, `refine`, `simplify`, `harden`, `system`.

## Full command catalog

Argument hints and long descriptions come from `skill/scripts/command-metadata.json`. Router category and reference path come from the Commands table in `skill/SKILL.src.md`. Empty `argumentHint` means the command takes no positional args in metadata (scope is still often supplied conversationally).

### Build

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `craft` | `[feature description]` | `reference/craft.md` | Deprecated alias for ordinary new-work; do not require users to invoke it |
| `shape` | `[feature to shape]` | `reference/shape.md` | Multi-round discovery interview → confirmed design brief before code |
| `init` | *(none)* | `reference/init.md` | Writes PRODUCT.md (including Platform); may offer DESIGN.md / live pre-config |
| `document` | *(none)* | `reference/document.md` | Generate DESIGN.md from code (Stitch-compatible) |
| `extract` | `[target]` | `reference/extract.md` | Pull repeated patterns/tokens into the design system |

### Evaluate

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `critique` | `[area (feature, page, component...)]` | `reference/critique.md` | UX review, scoring, personas, anti-pattern signal |
| `audit` | `[area (feature, page, component...)]` | `reference/audit.md` · **native:** `reference/audit.native.md` | Technical quality (a11y, perf, theming, responsive, anti-patterns); report only, no auto-fix |

### Refine

| Command | Argument hint | Reference |
|---|---|---|
| `polish` | `[target]` | `reference/polish.md` |
| `bolder` | `[target]` | `reference/bolder.md` |
| `quieter` | `[target]` | `reference/quieter.md` |
| `distill` | `[target]` | `reference/distill.md` |
| `harden` | `[target]` | `reference/harden.md` |
| `onboard` | `[target]` | `reference/onboard.md` |

### Enhance

| Command | Argument hint | Reference |
|---|---|---|
| `animate` | `[target]` | `reference/animate.md` |
| `colorize` | `[target]` | `reference/colorize.md` |
| `typeset` | `[target]` | `reference/typeset.md` |
| `layout` | `[target]` | `reference/layout.md` |
| `delight` | `[target]` | `reference/delight.md` |
| `overdrive` | `[target]` | `reference/overdrive.md` |

### Fix

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `clarify` | `[target]` | `reference/clarify.md` | UX copy, labels, errors, microcopy |
| `adapt` | `[target] [context (mobile, tablet, print...)]` | `reference/adapt.md` · **native:** `reference/adapt.native.md` | Responsive / device / platform adaptation |
| `optimize` | `[target]` | `reference/optimize.md` | UI performance (load, render, animation, images, bundle) |

### Iterate

| Command | Argument hint | Reference | Notes |
|---|---|---|---|
| `live` | *(none)* | `reference/live.md` | Browser variant mode; **web-only**; needs a running dev server |

## Native command variants

When PRODUCT.md platform resolves to `ios`, `android`, or `adaptive`, Setup step 2 routes these commands to the **native** file **instead of** the web file (one variant covers all three native platforms; OS specifics stay in `reference/ios.md` / `reference/android.md`).

| Command | Web reference | Native reference | Web file guard |
|---|---|---|---|
| `audit` | `reference/audit.md` | `reference/audit.native.md` | First lines redirect native readers to the native file |
| `adapt` | `reference/adapt.md` | `reference/adapt.native.md` | Same pattern |

Behavior differences (verified in the native playbooks):

| Concern | Web `audit` / `adapt` | Native variants |
|---|---|---|
| Inspection surface | Browser/HTML tooling, `detect.mjs` when applicable | Source-level (SwiftUI/UIKit/Compose/RN/Flutter); **no** browser tooling or `detect.mjs` |
| Scoring / standards | Web a11y, responsive, theming, anti-patterns | Platform refs: VoiceOver/TalkBack, Dynamic Type / sp, 44 pt / 48 dp targets, size classes, Material/HIG idioms |
| Report shape | `audit.md` skeleton | `audit.native.md` mirrors the same skeleton; keep both in sync when editing dimensions |
| Adaptation model | Breakpoints, fluid layouts, touch targets (incl. mobile web) | Restructure for size class / window class / foldable / platform idioms — not scale-and-stretch |

Commands such as `animate` and `layout` have **no** separate `.native.md`; platform refs loaded by Setup already cover their divergence. Do not add in-file web→native translation notes to those playbooks (native runs would pay for unused web content).

`live` and the bundled detector are **web-only**. No-argument routing must not lead with them when `setup.platform` is native.

## Utilities outside the 23

These are documented in SKILL.src.md after the Commands table. They are **not** in `IMPECCABLE_SUB_COMMANDS`, `command-metadata.json`, `SKILL_CATEGORIES`, or the design menu count.

### Pin / unpin (script)

```bash
node <scripts_path>/pin.mjs pin <command>
node <scripts_path>/pin.mjs unpin <command>
```

Creates or removes a standalone harness shortcut (for example `/audit`) that redirects to `/impeccable <command>` in discovered skill roots. `VALID_COMMANDS` matches the 23 design commands (includes `craft` and `live`).

### Hooks

```text
{{command_prefix}}impeccable hooks <on|off|status|ignore-rule|ignore-file|ignore-value|reset>
```

Load `reference/hooks.md`. Manages the design detector hook for the project (config under `.impeccable/config.json` / `config.local.json`).

### Doctor

```text
{{command_prefix}}impeccable doctor
```

Load `reference/doctor.md`. Maintenance only: schema/config/proxy truth-drift report and auto fixes. Typical script entry:

```bash
node <scripts_path>/doctor.mjs --json
node <scripts_path>/doctor.mjs --fix   # apply severity: auto only
```

Do not run doctor unasked when a design command is in flight. `CONTEXT_STALE` at boot is the cheap subset of the same report.

## Shared playbooks (not sub-commands)

Loaded by Setup or by specific commands; not pinned as design menu entries:

| File | Role |
|---|---|
| `reference/new-work.md` | New surface or replacement visual world |
| `reference/craft-floor.md` | Quality floor / absolute bans immediately before UI edits |
| `reference/operate.md` | Deeper Operate / Read mode guidance |
| `reference/routing.md` | No-argument context-aware menu |
| `reference/ios.md` / `reference/android.md` | Platform conventions (also inlined by `context.mjs` for native platforms) |
| `reference/live-setup.md` | Live pre-config helpers used from init / live setup paths |
| `reference/hooks.md` / `reference/doctor.md` | Utility command playbooks |
| `reference/visualize.md` | Supporting visual-probe material (not a router table command) |

## Suggestion list vs full catalog

`IMPECCABLE_SUB_COMMANDS` (what `{{available_commands}}` expands to for next-step suggestions in skill text) is a **subset** of the 23:

```text
adapt, animate, audit, bolder, clarify, colorize, critique, delight,
distill, document, harden, layout, onboard, optimize, overdrive,
polish, quieter, shape, typeset
```

Omitted from that suggestion list (still real commands): `craft`, `init`, `extract`, `live`.

## Metadata schema

Each key in `skill/scripts/command-metadata.json`:

```json
{
  "<command>": {
    "description": "string — used for pinned shortcut skills and tooling",
    "argumentHint": "string — may be empty"
  }
}
```

There are **23** keys, matching the router table names. Adding a design command requires updating at least: `reference/<name>.md`, the Commands table in `SKILL.src.md`, `IMPECCABLE_SUB_COMMANDS` (if it should appear in suggestions), `VALID_COMMANDS` in `pin.mjs`, `command-metadata.json`, and usually `SKILL_CATEGORIES` (unless deliberately unmapped like `craft`).

## Platform and web-only constraints (command-relevant)

| Constraint | Applies to |
|---|---|
| Native variant replaces web reference | `audit`, `adapt` when platform is `ios` / `android` / `adaptive` |
| Skip live + detector in routing | Any native platform |
| Design hook skips native projects | Hook scan on native PRODUCT.md platforms (web file types only) |
| After `init` writes PRODUCT.md | Resume without re-running `context.mjs`; init itself loads native platform refs when it recorded a native platform |

## Quick invocation examples

```text
/impeccable
/impeccable init
/impeccable document
/impeccable critique pricing
/impeccable audit src/components/Hero.tsx
/impeccable polish checkout
/impeccable adapt dashboard mobile
/impeccable live
/impeccable doctor
/impeccable hooks status
```

Pin example (after skills are installed in the project):

```bash
node .claude/skills/impeccable/scripts/pin.mjs pin audit
# then use /audit as a redirect to /impeccable audit
```

## Related pages

<CardGroup>
  <Card title="Commands and routing" href="/commands-and-routing">
    Setup load order, no-argument menu, craft-floor gate, and when native variants replace web references.
  </Card>
  <Card title="Run design commands" href="/run-design-commands">
    How to invoke evaluate/refine commands with targets, expected artifacts, and verification signals.
  </Card>
  <Card title="Modes and platform" href="/modes-and-platform">
    Visitor modes and platform values that change which references load.
  </Card>
  <Card title="Pin shortcuts" href="/pin-shortcuts">
    Create and remove standalone harness shortcuts for any of the 23 commands.
  </Card>
  <Card title="Doctor" href="/doctor">
    Utility doctor pass: findings, severities, auto fix, and opt-out of boot staleness.
  </Card>
  <Card title="Live browser iteration" href="/live-mode">
    Live command contract, roots, accept/discard, and web-only boundaries.
  </Card>
</CardGroup>