Editorial wrappers for 7 core skills

First batch of hand-written editorial wrappers. Each wrapper lives at content/site/skills/{id}.md and renders above the auto-generated SKILL.md body on the skill detail page. Shape follows the standard four-section template: When to use it / How it works / Try it / Pitfalls. Plus a tagline in frontmatter that the page template uses in place of the bare frontmatter description. Shipped: - impeccable: the foundation skill, why it exists, and when to call teach - critique: the two-assessment design review with heuristic scoring - audit: five-dimension technical quality check with P0-P3 severities - polish: the meticulous final pass, what it covers, when not to run it - shape: discovery interview that produces a design brief - distill: ruthless subtraction, when it helps vs when to reach for arrange - harden: edge cases, i18n, error states, production readiness Tone: direct, opinionated, no hedging, no em dashes, concrete try-it examples with expected output shapes. Next 14 wrappers ship in batches 2 and 3.
2026-09-12 22:26:38 +03:00 · 2026-04-08 10:03:58 -07:00
parent 9b1b709bab
commit 2592db4c80
7 changed files with 310 additions and 0 deletions
@@ -0,0 +1,50 @@
+---
+tagline: "Five-dimension technical quality check with P0 to P3 severity."
+---
+
+## When to use it
+
+`/audit` is the technical counterpart to `/critique`. Where `/critique` asks "does this feel right", `/audit` asks "does this hold up". It runs accessibility, performance, theming, responsive design, and anti-pattern checks against the implementation, scores each dimension 0 to 4, and produces a plan with P0 to P3 severity ratings.
+
+Use it before shipping, during a quality sprint, or whenever a tech lead says "we should really look at accessibility".
+
+## How it works
+
+The skill scans your code across five dimensions:
+
+1. **Accessibility**: WCAG contrast, ARIA, keyboard nav, semantic HTML, form labels.
+2. **Performance**: layout thrashing, expensive animations, missing lazy loading, bundle weight.
+3. **Theming**: hard-coded colors, dark mode coverage, token consistency.
+4. **Responsive**: breakpoint behavior, touch targets, mobile viewport handling.
+5. **Anti-patterns**: the same deterministic 25 checks the detector runs.
+
+Each dimension gets a 0 to 4 score. Each finding gets a severity: P0 blocks the release, P1 should fix this sprint, P2 is next cycle, P3 is polish. You get back a single document you can paste into a ticket tracker.
+
+Audit does not fix anything. It documents. Route the findings to `/polish`, `/harden`, `/normalize`, or `/optimize` depending on the category.
+
+## Try it
+
+```
+/audit the checkout flow
+```
+
+Expected output:
+
+```
+Accessibility: 2/4 (partial)
+  P0: Missing form labels on 4 inputs
+  P1: Contrast 3.1:1 on disabled button state
+  P2: No visible focus indicator on custom dropdown
+
+Performance: 3/4 (good)
+  P1: Hero image not lazy-loaded (340KB)
+  ...
+```
+
+Hand the P0s to `/harden`, the theming and typography P1s to `/normalize` and `/typeset`, the rest to `/polish`.
+
+## Pitfalls
+
+- **Confusing it with `/critique`.** Audit is implementation quality. Critique is design quality. Run both for a full picture.
+- **Fixing P3s before P0s.** The severity scale exists for a reason. Start at the top.
+- **Skipping the dimensions you think are fine.** Theming and responsive are the ones most people assume are fine until they are not.
@@ -0,0 +1,43 @@
+---
+tagline: "A design review with scoring, persona tests, and automated detection."
+---
+
+## When to use it
+
+Reach for `/critique` when you want an honest second opinion on something you already built. Not "does it work" but "is it any good". The skill scores your interface against Nielsen's 10 heuristics, runs cognitive load checks, tests through persona lenses, and cross-references an automated detector for 25 concrete anti-patterns.
+
+Use it when a page is functionally done and you want to know if it reads as intentional or as AI slop.
+
+## How it works
+
+`/critique` runs two independent assessments in parallel so they do not bias each other.
+
+The first is an **LLM design review**: the model reads your source, visually inspects the live page if browser automation is available, and walks the impeccable skill's full DO/DON'T catalog. It scores Nielsen's heuristics, counts cognitive load failures, traces the emotional journey through the flow, and flags AI slop.
+
+The second is an **automated detector** (`npx impeccable detect`) that deterministically finds gradient text, purple palettes, side-tab borders, nested cards, line length problems, and the other visible fingerprints of generic AI output.
+
+The two reports merge into one prioritized list: what is working, the three to five things that need fixing, and the provocative questions worth answering before shipping.
+
+## Try it
+
+Point it at a page:
+
+```
+/critique the homepage hero
+```
+
+You get back a scored report. Typical shape:
+
+- **AI slop verdict**: pass / fail with the specific tells
+- **Heuristic scores**: 10 numbers, 0 to 4
+- **Cognitive load**: failure count out of 8
+- **Priority issues**: three to five items, each with what, why, and fix
+- **Questions to answer**: the ones the interface itself cannot decide for you
+
+From there, pair with `/polish` or `/distill` to act on the fixes.
+
+## Pitfalls
+
+- **Running it on incomplete work.** Critique is for finished pages. An empty state with three TODOs will score badly because it is not done, not because it is bad.
+- **Ignoring the questions at the end.** They are usually the highest-leverage fixes.
+- **Treating the heuristic scores as a grade.** They are diagnostic, not evaluative. A 3/4 on a heuristic that matters less for your context is fine.
@@ -0,0 +1,44 @@
+---
+tagline: "Ruthless subtraction. Strip designs to their essence."
+---
+
+## When to use it
+
+`/distill` removes what should not be there. Competing buttons, redundant information, decorative borders, three fonts where one works, six navigation items where three belong. Use it when an interface feels cluttered, busy, or like it is trying to do too much at once.
+
+Reach for it after `/critique` flags "cognitive load" or "visual noise", or any time a page has grown by accretion and no one has done the editing.
+
+## How it works
+
+The skill starts from one question: what is the single job this interface is trying to do? Everything that does not help that job is on the chopping block.
+
+It works in two passes:
+
+1. **Assess the complexity sources**. Too many elements, excessive variation, information overload, visual noise, confusing hierarchy, feature creep. Name each one.
+2. **Edit ruthlessly**. Remove what is not essential. Combine what can be combined. Hide what can wait. Consolidate variation into a single treatment. Commit to a single visual language.
+
+The principle: simplicity is not about fewer features. It is about fewer obstacles between users and their goals. Every element on the page has to justify its existence.
+
+## Try it
+
+```
+/distill this dashboard
+```
+
+Before: four card styles, three button variants, two header treatments, a sidebar with 14 items grouped into 5 sections.
+
+After a `/distill` pass, typical changes:
+
+- Collapse the four card styles into one
+- Pick one button variant, demote the others to text links
+- Unify the headers
+- Group the sidebar into 3 sections, not 5
+- Hide advanced options behind a disclosure
+
+Fewer things. Each one clearer.
+
+## Pitfalls
+
+- **Confusing distill with delete.** Distill removes obstacles. It does not remove features users need. If a user relies on something daily, find a way to keep it quietly, not a way to cut it.
+- **Running it too early.** If the feature is still growing, distilling it now means distilling the same thing again next week. Wait until the shape is stable.
+- **Expecting it to replace hierarchy work.** Sometimes the right fix is not removing things, it is arranging them. Reach for `/arrange` when the problem is layout, not quantity.
@@ -0,0 +1,44 @@
+---
+tagline: "Make interfaces production-ready. Edge cases, i18n, error states, overflow."
+---
+
+## When to use it
+
+`/harden` is for the day your interface meets reality. Real user data is messy: names that are 60 characters long, product titles in German, prices in the billions, empty lists, 500 errors, offline modes, right-to-left text. Designs that only work with perfect data are not production-ready.
+
+Reach for it before launch, before opening to a new market, or any time a bug report starts with "our user had a really long name and".
+
+## How it works
+
+The skill works through four dimensions of real-world resilience:
+
+1. **Text and data extremes**. Long text, short text, special characters, emoji, RTL, numbers in the billions, 1000-item lists, zero-data empty states.
+2. **Error scenarios**. Network failures, API 4xx/5xx, validation errors, permission errors, rate limits, concurrent operations.
+3. **Internationalization**. Long translations (German is often 30% longer than English), RTL languages, date and number formats, currency symbols, character sets.
+4. **Device and context**. Touch targets, offline behavior, slow connections, low-power mode.
+
+For each dimension it identifies the failure mode, then applies the concrete fix: overflow handling, proper empty states, informative error UI, i18n-safe layouts, pluralization, sensible fallbacks.
+
+## Try it
+
+Start with one page and one dimension:
+
+```
+/harden the user profile page for long names
+```
+
+Expected output:
+
+- `.user-name` now has `text-overflow: ellipsis` with a tooltip for the full value
+- `.bio` switched from fixed height to `max-height` with a "show more" disclosure
+- Added an empty state for users with no bio
+- Added a skeleton loader for the async avatar fetch
+- Tested at name lengths 1, 20, 60, 200 characters
+
+Run it per-page, not all at once. The first run is the biggest; subsequent runs find fewer issues as patterns solidify.
+
+## Pitfalls
+
+- **Waiting for a bug report.** Harden is preventative. If you find yourself fixing the same class of bug twice, run `/harden` across the feature.
+- **Treating error states as an afterthought.** Most hardening work is error UI. Budget time for it, not just a `catch` block.
+- **Skipping i18n because "we are English-only for now".** i18n-safe layouts are still better layouts. Flexible containers, proper text wrapping, generous line-height. None of that hurts English.
@@ -0,0 +1,39 @@
+---
+tagline: "The design intelligence behind every other skill."
+---
+
+## When to use it
+
+`/impeccable` is the foundation. It teaches your AI harness how to design, period. Every other command in this pack leans on it for design principles, anti-patterns, typography, color, and layout guidance.
+
+Call `/impeccable` directly when you want freeform design with the full guidebook loaded. Call `/impeccable craft` for a shape-then-build flow with visual iteration. Call `/impeccable teach` once per project to set up design context.
+
+## How it works
+
+Most AI-generated UIs fail the same way: generic fonts, purple gradients, card grids on card grids, glassmorphism everywhere. `/impeccable` gives your AI a strong point of view. It loads an opinionated design handbook plus a long list of anti-patterns, then pushes the model to commit to a specific aesthetic direction before writing a single line of code.
+
+The skill has a **Context Gathering Protocol** built in. It will not design anything until it knows who uses the product, what they're trying to do, and how the interface should feel. If no context exists yet, it asks you to run `/impeccable teach` first. This is deliberate: design without context produces slop, and slop is the whole problem this pack exists to solve.
+
+## Try it
+
+From a clean project, run once:
+
+```
+/impeccable teach
+```
+
+Answer the discovery questions. The skill writes a `.impeccable.md` file with your brand, audience, and aesthetic direction. Every future skill call reads it automatically.
+
+Then build something:
+
+```
+/impeccable build me a pricing page for a developer tool
+```
+
+You should get a page that commits to one clear aesthetic direction, uses non-default fonts, avoids the AI color palette, and has a real point of view.
+
+## Pitfalls
+
+- **Skipping `/impeccable teach`.** Without a `.impeccable.md` file, the skill has to ask you context questions mid-flight. Faster to set it up once.
+- **Treating it like a style guide.** It is an opinionated design partner, not a linter. If it says "do not use Inter," it means it. Fighting the opinion usually produces worse output.
+- **Expecting it to fix existing code.** For that, reach for `/polish`, `/distill`, or `/critique` instead. `/impeccable` is for creation.
@@ -0,0 +1,46 @@
+---
+tagline: "The meticulous final pass between good and great."
+---
+
+## When to use it
+
+`/polish` is the last thing you run before shipping. It hunts down the small details that separate a shipped feature from a polished one: half-pixel misalignments, inconsistent spacing, forgotten focus states, loading transitions that flash, copy that drifts in tone.
+
+Reach for it when the feature is functionally complete, nothing is broken, and something still feels off.
+
+## How it works
+
+Polish works methodically across six dimensions:
+
+1. **Visual alignment and spacing**: pixel-perfect grid adherence, consistent spacing scale, optical alignment on icons.
+2. **Typography**: hierarchy consistency, line length, widows and orphans, kerning on headlines.
+3. **Color and contrast**: token usage, theme parity, WCAG ratios, focus indicators.
+4. **Interaction states**: hover, focus, active, disabled, loading, error, success. Every state accounted for.
+5. **Transitions and motion**: smooth easing, no layout jank, respect for `prefers-reduced-motion`.
+6. **Copy**: consistent voice, correct tense, no placeholder strings, no stray TODOs.
+
+The skill is explicit about one thing: polish is the last step, not the first. If the feature is not functionally complete, polishing it is wasted work.
+
+## Try it
+
+```
+/polish the pricing page
+```
+
+A healthy run looks like:
+
+```
+Visual alignment: fixed 3 off-grid elements (8px baseline)
+Typography: tightened h1 kerning, fixed widow on testimonial
+Interaction: added hover state on FAQ items, focus ring on email input
+Motion: softened modal entrance, added reduced-motion fallback
+Copy: removed one "Lorem ipsum" stray, aligned button voice
+```
+
+Five small fixes, no rewrites. That is the shape of a good polish pass.
+
+## Pitfalls
+
+- **Polishing work that is not done.** If there are TODOs in the code, you are not ready. Run `/polish` on finished features only.
+- **Treating polish as redesign.** Polish refines what exists. If you find yourself rearchitecting a layout, you needed `/critique` or `/arrange` instead.
+- **Running `/polish` without `/audit` first.** Polish catches feel-based issues. Audit catches measurable ones. Use both.
@@ -0,0 +1,44 @@
+---
+tagline: "Think before you build. Produce a design brief through discovery, not guesswork."
+---
+
+## When to use it
+
+`/shape` is where a feature starts. Before anyone writes code, before anyone argues about the hero treatment, before anyone picks a font. Use it to force a discovery conversation about purpose, users, content, and constraints, then capture the answers as a design brief the implementation skills can lean on.
+
+Reach for it whenever a feature is about to start, a ticket is vague, or you catch yourself writing JSX to figure out what the product should be.
+
+## How it works
+
+Most AI-generated UIs fail not because of bad code, but because of skipped thinking. The model jumps to "here is a card grid" without asking "what is the user trying to accomplish". `/shape` inverts that order.
+
+The skill runs a structured discovery interview in conversation. It will not write code during this phase. The questions cover:
+
+- **Purpose and context**: what the feature is for, who uses it, what state of mind they are in
+- **Content and data**: what is displayed, realistic ranges, edge cases, what is dynamic
+- **Design goals**: the single most important thing, the intended feeling, reference examples
+- **Constraints**: technical, content, accessibility, localization
+
+You answer naturally. The skill asks follow-ups, not a form. At the end it produces a design brief: a structured artifact you can hand to `/impeccable craft`, `/impeccable`, or any other implementation skill.
+
+## Try it
+
+```
+/shape a daily digest email preferences page
+```
+
+Expect a 5 to 10 question conversation. The skill asks things like "who is the person opening this, and are they already committed or still curious" and "what happens when the user has unsubscribed from everything, do we hide the feature or show something". You answer, and a brief materializes.
+
+Then:
+
+```
+/impeccable craft using the brief above
+```
+
+The craft run will reference the brief at every decision. You should feel the difference compared to building without it.
+
+## Pitfalls
+
+- **Skipping it because it feels slow.** The interview is maybe 5 minutes. The rewrites you avoid are measured in hours.
+- **Treating the brief as a spec.** It is a compass, not a checklist. It captures intent, not UI.
+- **Answering with "standard" or "normal".** Specificity is the whole point. If a user is "rushed, on mobile, between meetings", say so. That changes everything downstream.