impeccable · slash commands

v4.0.4 · 27 commands · read left to right, then click a command for what it does and what to use it with.

Setup → plan / build → diagnose → choose fix & style commands → polish. Utilities sit in their own bottom lane.

Best-practice order

1Setupinit · document · extract
2Plan / buildshape · craft
3Diagnosecritique + audit
4Fix & styleharden … bolder, animate
5Finishpolish, always last

Commands · click to expand steps

Setup

/impeccablewhat next?Run /impeccable with no argument. It reads your project's state and suggests the 2–3 commands most worth running next. It never runs one for you.

Use with Start here when unsure; it points to init on a fresh project.

  1. Read context.mjs result
  2. NO_PRODUCT_MD → lead with init
  3. Else read context-signals.mjs
  4. Run detect.mjs once on scan targets (web only)
  5. Show 2–3 picks + full menu; never auto-run

In context signals, git changes, detector hits
Out 2–3 recommended commands to type

reference/routing.md

initno PRODUCT.mdInterviews you about users, purpose and constraints, then writes PRODUCT.md. Every other command reads that file first.

Use with Run once per project, first. Then shape or a build; document if code already exists.

  1. Load current state (update, never overwrite)
  2. Explore repo before asking
  3. Interview: users, purpose, constraints (≥1 round)
  4. Write PRODUCT.md (schema 1)
  5. Configure live mode if web + runnable
  6. Recommend next command / resume caller

In repo evidence + user answers
Out PRODUCT.md (+ .impeccable/live/config.json)

reference/init.md

documentno DESIGN.mdReads your existing CSS, tokens and components and writes DESIGN.md, a visual spec that keeps later AI edits on-brand.

Use with After init on existing code, or let a build write it at the finish. Re-run when the design drifts.

  1. Scan: find tokens, Tailwind, themes, components
  2. Auto-extract colors, type, elevation, components
  3. Stage YAML frontmatter
  4. Ask 2 rounds of descriptive language
  5. Write DESIGN.md (Stitch format) + sidecar
  6. Seed mode (no code): route via init + new-work workshop

In codebase tokens/components (scan) or PRODUCT.md (seed)
Out DESIGN.md + .impeccable/design.json

reference/document.md

extractrepeated UIPulls UI that repeats 3+ times into shared tokens and components, then migrates every use.

Use with During setup on an existing codebase, or whenever repeated UI drifts apart. Run independently when needed.

  1. Discover the design system (ask if none)
  2. Identify patterns used 3+ times
  3. Plan extraction
  4. Extract & enrich components/tokens
  5. Migrate all uses
  6. Document

In codebase repeats
Out Shared tokens + components, migrated uses

reference/extract.md

Plan & build

shapeplan firstPlans a feature before any code: a short interview, then a design brief you confirm. It never writes code.

Use with After init. Hand the confirmed brief to a build (craft).

  1. Discovery interview: purpose, people, outcome
  2. Round 2 only for material gaps
  3. Resolve direction via new-work (new surfaces only)
  4. Write the smallest useful brief
  5. Confirm, then stop — no code

In user answers, PRODUCT.md
Out Confirmed design brief (no code)

reference/shape.md

craftbuild newBuilds a new surface or redesign end to end: picks a visual direction, renders comps, builds, has a fresh reviewer check it, records DESIGN.md. Deprecated name: just ask for the build.

Use with init → (shape) → build. Follow with critique, then the fix commands, then polish.

  1. Alias: runs the normal new-work flow
  2. Decide what is already true
  3. Ask one round
  4. Choose invention level; concept-seed.mjs roll
  5. Commit world + direction contract
  6. Visualize 3 comps (if image gen)
  7. Build → finish reviewer → documenter

In PRODUCT.md, DESIGN.md, brief
Out Built surface + direction contract + DESIGN.md

reference/craft.md → new-work.md

Diagnose

critiqueUX reviewA design review. Two isolated reviewers (design judgment + automated detector) score usability out of 40 and list P0–P3 issues, each with the command that fixes it.

Use with Pair with audit to diagnose. Run the commands it suggests, then polish last; re-run to see the score move.

  1. Resolve target + slug
  2. A: design review sub-agent (heuristics /40)
  3. B: detector + browser sub-agent (isolated)
  4. Synthesize: P0–P3 issues, personas, cognitive load
  5. Persist snapshot + trend
  6. Ask user priority/scope
  7. Recommend commands, end with polish

In target file/URL, detect.mjs, ignore.md
Out Report /40 + snapshot in .impeccable/critique/

reference/critique.md

audittech checkA technical check of accessibility, performance, theming, responsive and implementation, scored out of 20. It reports only; it does not fix anything.

Use with Pair with critique. Its findings go to harden, optimize, adapt…; end with polish.

  1. Scan 5 dimensions: a11y, perf, theming, responsive, integrity
  2. Score each 0–4 (/20)
  3. Integrity verdict first
  4. Findings by P0–P3 with suggested command
  5. Recommend commands, end with polish (no fixes)

In target code (native: audit.native.md)
Out Health score /20 + P0–P3 action plan

reference/audit.md

Fix

hardenedge casesMakes the UI survive real data: long text, errors, empty and loading states, other languages, bad input.

Use with Usually from an audit finding. Hand off to polish.

  1. Assess hardening needs
  2. Text overflow & wrapping
  3. i18n
  4. Error handling
  5. Edge cases + input validation
  6. A11y + performance resilience
  7. Verify → hand to polish

In target, real-world data ranges
Out Resilient states (errors, overflow, i18n)

reference/harden.md

clarifyconfusing copyRewrites labels, buttons, errors and help text so people know what happened and what to do next.

Use with Often from a critique finding. Hand off to polish.

  1. Audit the language
  2. Set message hierarchy
  3. Rewrite actions, forms, errors, states, help
  4. Voice, a11y, localization
  5. Verify → hand to polish

In audience knowledge + emotional state
Out Clearer microcopy, labels, errors

reference/clarify.md

adaptother screensReworks the design for another screen or context (phone, tablet, print, email), not just a shrunk copy.

Use with From audit's responsive findings. Hand off to polish.

  1. Assess adaptation challenge
  2. Plan strategy (mobile/tablet/desktop/print/email)
  3. Implement breakpoints, touch, content, nav
  4. Verify → hand to polish

In target platforms/devices (native: adapt.native.md)
Out Layout adapted to the new context

reference/adapt.md

optimizefeels slowFinds what actually makes the UI slow (loading, rendering, animation, bundle) and fixes it, with before/after numbers.

Use with From audit's performance findings. Hand off to polish.

  1. Assess: find the actual bottleneck
  2. Loading, rendering, animation, framework, network
  3. Core Web Vitals (LCP, INP, CLS)
  4. Measure before/after
  5. Verify → hand to polish

In target + measurements
Out Faster UI + before/after numbers

reference/optimize.md

onboardfirst runDesigns first-run flows and empty states that get a new user to the 'aha' moment fast.

Use with Hand off to polish.

  1. Assess onboarding needs (aha moment)
  2. Apply principles: show, optional, time-to-value
  3. Design onboarding / discovery / tours
  4. Empty-state design
  5. Verify → hand to polish

In aha moment + user experience level
Out First-run flow and empty states

reference/onboard.md

distilltoo clutteredRemoves whatever does not earn its place: duplicate info, extra options, decorative noise.

Use with Often suggested by critique. Hand off to polish.

  1. Assess current state
  2. Plan simplification
  3. Simplify IA, visual, layout, interaction, content, code
  4. Verify
  5. Document removed complexity → polish

In target
Out Simpler UI + list of what was removed

reference/distill.md

Style

layoutspacing offFixes structure: reading order, grouping, spacing rhythm and hierarchy, inside the current look.

Use with Pair with typeset. A new identity goes to a build instead. Then polish.

  1. Pick visitor mode
  2. Two isolated assessments (design + detector)
  3. Set the spatial thesis
  4. Apply inside current world
  5. Verify → hand to polish

In target, DESIGN.md
Out Restructured layout and rhythm

reference/layout.md

typesettype offFixes typography: font roles, scale, weight, line length and readability.

Use with Pair with layout. New fonts = new identity → build + DESIGN.md. Then polish.

  1. Pick visitor mode
  2. Two isolated assessments (design + detector)
  3. Set the type system
  4. Apply
  5. Verify → hand to polish

In target, DESIGN.md fonts
Out Type roles, scale, measure fixed

reference/typeset.md

colorizetoo grayAdds color with a purpose (hierarchy, meaning, atmosphere) to a gray or flat UI.

Use with Opposite of quieter. A new palette identity goes to a build. Then polish.

  1. Pick visitor mode
  2. Audit before choosing
  3. Choose a color strategy
  4. Apply at system scale
  5. Contrast + perception check
  6. Verify → hand to polish

In existing brand colors, DESIGN.md
Out Color roles applied across the system

reference/colorize.md

boldertoo blandTurns up one flat section to the confidence the rest of the page already has. Everything else stays untouched.

Use with Opposite of quieter/distill. Polish suggests it when a concept is too timid. Then polish.

  1. Scope is sovereign: touch only the target
  2. Diagnose why it reads flat
  3. Amplify what the system already owns
  4. Skeleton test
  5. Before-you-finish checks → polish

In target section + what stays untouched
Out One section amplified, same brand

reference/bolder.md

quietertoo loudTurns down a loud or garish design (color, weight, motion) without making it generic.

Use with Opposite of bolder/colorize. Hand off to polish.

  1. Pick visitor mode
  2. Assess current state
  3. Plan refinement
  4. Reduce color, weight, motion; simplify
  5. Verify → hand to polish

In target
Out Calmer UI, personality kept

reference/quieter.md

Motion

animateneeds motionAdds motion that explains state and hierarchy, plus at most one authored moment. No decoration for its own sake.

Use with delight uses it for motion. Hand off to polish.

  1. Pick visitor mode
  2. Find the motion's job
  3. Set the motion thesis
  4. Choose material, timing, easing
  5. Implement to runtime + reduced motion
  6. Verify → hand to polish

In target + performance constraints
Out Purposeful motion implemented

reference/animate.md

delightneeds charmAdds one memorable, on-brand moment of personality where the experience has earned it.

Use with Calls animate for motion. Hand off to polish.

  1. Pick visitor mode
  2. Find the opportunity
  3. Define one delight thesis
  4. Build for the emotional moment (loads animate)
  5. Protect the experience
  6. Verify → hand to polish

In brand's emotional range
Out One memorable moment, built

reference/delight.md

overdrivewow factorGoes technically all-out (shaders, scroll-driven effects, physics). It proposes 2–3 directions and waits for your pick first.

Use with Use on its own when the brief asks for wow; verify in the browser.

  1. Propose 2–3 directions, user picks
  2. Assess what extraordinary means here
  3. Pick from toolkit (shaders, scroll, physics…)
  4. Implement with progressive enhancement
  5. Iterate in browser + verify

In target + user's chosen direction
Out Technically ambitious implementation

reference/overdrive.md

Polish last

polishbefore shipThe final pass before shipping: alignment, consistency, every state, a clean diff. It reads the last critique as its to-do list.

Use with Always last, after diagnose + fixes. If the concept is wrong it suggests bolder or a redesign.

  1. Establish the system (DESIGN.md, tokens)
  2. Gather evidence + latest critique snapshot
  3. Triage functional vs cosmetic
  4. Polish the whole path
  5. Verify every state + clean diff

In DESIGN.md, critique snapshot, quality bar
Out Shippable path + clean source diff

reference/polish.md

Utilities

livetry variantsPick an element in the running app and get 3 design variants hot-swapped in the browser. Accept one and it is written to source.

Use with Needs a dev server; init sets it up. Uses the style commands' rules for its variants.

  1. Boot live.mjs (+ live-setup on first run)
  2. Open the app URL
  3. Background poll loop
  4. On generate: load verb ref, 3 variants via HMR
  5. Accept / discard → write source
  6. Exit cleanup

In running dev server, PRODUCT.md, DESIGN.md
Out Chosen variant written to source

reference/live.md

hooksauto-detectTurns the automatic design detector on or off. When on, it checks every UI file edit and flags problems.

Use with Leave on while building; it catches mechanical defects as you edit.

  1. on / off / status
  2. ignore-rule / ignore-file / ignore-value
  3. reset
  4. Edits .impeccable/config.json

In subcommand
Out Hook config; detector runs after UI edits

reference/hooks.md

doctorstale filesChecks whether PRODUCT.md, DESIGN.md and impeccable config are stale for this version, and auto-fixes the safe parts.

Use with When context looks stale; it hands real gaps to init or document.

  1. Run doctor.mjs --json
  2. auto → --fix silently
  3. mention / decide by severity
  4. Truth drift → hand gap to init / document

In PRODUCT.md, DESIGN.md, config, briefs, hook
Out Drift report + safe auto-fixes

reference/doctor.md

pin / unpinshortcutCreates (or removes) a standalone /<command> shortcut, e.g. /polish instead of /impeccable polish.

Use with Pin the commands you run most (polish, critique).

  1. pin.mjs pin|unpin <command>
  2. Report result; relay stderr

In command name
Out Standalone /<command> shortcut

reference/SKILL.md

Mapped from .agents/skills/impeccable v4.0.4. BookKeepingApp's v4.4.0 adds generate (named-element variants in the live browser) and a single scripts/impeccable launcher; otherwise the same commands. teach = init; craft is deprecated (plain build requests run the same flow); audit and adapt use *.native.md on iOS/Android.