pm-workflow-studio 0.1.0

package/.claude/skills/impeccable/reference/color-and-contrast.md

@@ -0,0 +1,105 @@
+# Color & Contrast
+
+## Color Spaces: Use OKLCH
+
+**Stop using HSL.** Use OKLCH (or LCH) instead. It's perceptually uniform, meaning equal steps in lightness *look* equal, unlike HSL where 50% lightness in yellow looks bright while 50% in blue looks dark.
+
+The OKLCH function takes three components: `oklch(lightness chroma hue)` where lightness is 0-100%, chroma is roughly 0-0.4, and hue is 0-360. To build a primary color and its lighter / darker variants, hold the chroma+hue roughly constant and vary the lightness, but **reduce chroma as you approach white or black**, because high chroma at extreme lightness looks garish.
+
+The hue you pick is a brand decision and should not come from a default. Do not reach for blue (hue 250) or warm orange (hue 60) by reflex; those are the dominant AI-design defaults, not the right answer for any specific brand.
+
+## Building Functional Palettes
+
+### Tinted Neutrals
+
+**Pure gray is dead.** A neutral with zero chroma feels lifeless next to a colored brand. Add a tiny chroma value (0.005-0.015) to all your neutrals, hued toward whatever your brand color is. The chroma is small enough not to read as "tinted" consciously, but it creates subconscious cohesion between brand color and UI surfaces.
+
+The hue you tint toward should come from THIS project's brand, not from a "warm = friendly, cool = tech" formula. If your brand color is teal, your neutrals lean toward teal. If your brand color is amber, they lean toward amber. The point is cohesion with the SPECIFIC brand, not a stock palette.
+
+**Avoid** the trap of always tinting toward warm orange or always tinting toward cool blue. Those are the two laziest defaults and they create their own monoculture across projects.
+
+### Palette Structure
+
+A complete system needs:
+
+| Role | Purpose | Example |
+|------|---------|---------|
+| **Primary** | Brand, CTAs, key actions | 1 color, 3-5 shades |
+| **Neutral** | Text, backgrounds, borders | 9-11 shade scale |
+| **Semantic** | Success, error, warning, info | 4 colors, 2-3 shades each |
+| **Surface** | Cards, modals, overlays | 2-3 elevation levels |
+
+**Skip secondary/tertiary unless you need them.** Most apps work fine with one accent color. Adding more creates decision fatigue and visual noise.
+
+### The 60-30-10 Rule (Applied Correctly)
+
+This rule is about **visual weight**, not pixel count:
+
+- **60%**: Neutral backgrounds, white space, base surfaces
+- **30%**: Secondary colors: text, borders, inactive states
+- **10%**: Accent: CTAs, highlights, focus states
+
+The common mistake: using the accent color everywhere because it's "the brand color." Accent colors work *because* they're rare. Overuse kills their power.
+
+## Contrast & Accessibility
+
+### WCAG Requirements
+
+| Content Type | AA Minimum | AAA Target |
+|--------------|------------|------------|
+| Body text | 4.5:1 | 7:1 |
+| Large text (18px+ or 14px bold) | 3:1 | 4.5:1 |
+| UI components, icons | 3:1 | 4.5:1 |
+| Non-essential decorations | None | None |
+
+**The gotcha**: Placeholder text still needs 4.5:1. That light gray placeholder you see everywhere? Usually fails WCAG.
+
+### Dangerous Color Combinations
+
+These commonly fail contrast or cause readability issues:
+
+- Light gray text on white (the #1 accessibility fail)
+- **Gray text on any colored background**: gray looks washed out and dead on color. Use a darker shade of the background color, or transparency
+- Red text on green background (or vice versa): 8% of men can't distinguish these
+- Blue text on red background (vibrates visually)
+- Yellow text on white (almost always fails)
+- Thin light text on images (unpredictable contrast)
+
+### Never Use Pure Gray or Pure Black
+
+Pure gray (`oklch(50% 0 0)`) and pure black (`#000`) don't exist in nature; real shadows and surfaces always have a color cast. Even a chroma of 0.005-0.01 is enough to feel natural without being obviously tinted. (See tinted neutrals example above.)
+
+### Testing
+
+Don't trust your eyes. Use tools:
+
+- [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- Browser DevTools → Rendering → Emulate vision deficiencies
+- [Polypane](https://polypane.app/) for real-time testing
+
+## Theming: Light & Dark Mode
+
+### Dark Mode Is Not Inverted Light Mode
+
+You can't just swap colors. Dark mode requires different design decisions:
+
+| Light Mode | Dark Mode |
+|------------|-----------|
+| Shadows for depth | Lighter surfaces for depth (no shadows) |
+| Dark text on light | Light text on dark (reduce font weight) |
+| Vibrant accents | Desaturate accents slightly |
+| White backgrounds | Never pure black; use dark gray (oklch 12-18%) |
+
+In dark mode, depth comes from surface lightness, not shadow. Build a 3-step surface scale where higher elevations are lighter (e.g. 15% / 20% / 25% lightness). Use the SAME hue and chroma as your brand color (whatever it is for THIS project; do not reach for blue) and only vary the lightness. Reduce body text weight slightly (e.g. 350 instead of 400) because light text on dark reads as heavier than dark text on light.
+
+### Token Hierarchy
+
+Use two layers: primitive tokens (`--blue-500`) and semantic tokens (`--color-primary: var(--blue-500)`). For dark mode, only redefine the semantic layer; primitives stay the same.
+
+## Alpha Is A Design Smell
+
+Heavy use of transparency (rgba, hsla) usually means an incomplete palette. Alpha creates unpredictable contrast, performance overhead, and inconsistency. Define explicit overlay colors for each context instead. Exception: focus rings and interactive states where see-through is needed.
+
+---
+
+**Avoid**: Relying on color alone to convey information. Creating palettes without clear roles for each color. Using pure black (#000) for large areas. Skipping color blindness testing (8% of men affected).

package/.claude/skills/impeccable/reference/colorize.md

@@ -0,0 +1,154 @@
+> **Additional context needed**: existing brand colors.
+
+Replace timid grayscale or single-accent designs with a strategic palette: pick a color strategy, choose a hue family that fits the brand, then apply color with intent. More color ≠ better. Strategic color beats rainbow vomit.
+
+---
+
+## Register
+
+Brand: palette IS voice. Pick a color strategy first per SKILL.md (Restrained / Committed / Full palette / Drenched) and follow its dosage. Committed, Full palette, and Drenched deliberately exceed the ≤10% rule; that rule is Restrained only. Unexpected combinations are allowed; a dominant color can own the page when the chosen strategy calls for it.
+
+Product: semantic-first and almost always Restrained. Accent color is reserved for primary action, current selection, and state indicators. Not decoration. Every color has a consistent meaning across every screen.
+
+---
+
+## Assess Color Opportunity
+
+Analyze the current state and identify opportunities:
+
+1. **Understand current state**:
+   - **Color absence**: Pure grayscale? Limited neutrals? One timid accent?
+   - **Missed opportunities**: Where could color add meaning, hierarchy, or delight?
+   - **Context**: What's appropriate for this domain and audience?
+   - **Brand**: Are there existing brand colors we should use?
+
+2. **Identify where color adds value**:
+   - **Semantic meaning**: Success (green), error (red), warning (yellow/orange), info (blue)
+   - **Hierarchy**: Drawing attention to important elements
+   - **Categorization**: Different sections, types, or states
+   - **Emotional tone**: Warmth, energy, trust, creativity
+   - **Wayfinding**: Helping users navigate and understand structure
+   - **Delight**: Moments of visual interest and personality
+
+If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify.
+
+**CRITICAL**: More color ≠ better. Strategic color beats rainbow vomit every time. Every color should have a purpose.
+
+## Plan Color Strategy
+
+Create a purposeful color introduction plan:
+
+- **Color palette**: What colors match the brand/context? (Choose 2-4 colors max beyond neutrals)
+- **Dominant color**: Which color owns 60% of colored elements?
+- **Accent colors**: Which colors provide contrast and highlights? (30% and 10%)
+- **Application strategy**: Where does each color appear and why?
+
+**IMPORTANT**: Color should enhance hierarchy and meaning, not create chaos. Less is more when it matters more.
+
+## Introduce Color Strategically
+
+Add color systematically across these dimensions:
+
+### Semantic Color
+- **State indicators**:
+  - Success: Green tones (emerald, forest, mint)
+  - Error: Red/pink tones (rose, crimson, coral)
+  - Warning: Orange/amber tones
+  - Info: Blue tones (sky, ocean, indigo)
+  - Neutral: Gray/slate for inactive states
+
+- **Status badges**: Colored backgrounds or borders for states (active, pending, completed, etc.)
+- **Progress indicators**: Colored bars, rings, or charts showing completion or health
+
+### Accent Color Application
+- **Primary actions**: Color the most important buttons/CTAs
+- **Links**: Add color to clickable text (maintain accessibility)
+- **Icons**: Colorize key icons for recognition and personality
+- **Headers/titles**: Add color to section headers or key labels
+- **Hover states**: Introduce color on interaction
+
+### Background & Surfaces
+- **Tinted backgrounds**: Replace pure gray (`#f5f5f5`) with warm neutrals (`oklch(97% 0.01 60)`) or cool tints (`oklch(97% 0.01 250)`)
+- **Colored sections**: Use subtle background colors to separate areas
+- **Gradient backgrounds**: Add depth with subtle, intentional gradients (not generic purple-blue)
+- **Cards & surfaces**: Tint cards or surfaces slightly for warmth
+
+**Use OKLCH for color**: It's perceptually uniform, meaning equal steps in lightness *look* equal. Great for generating harmonious scales.
+
+### Data Visualization
+- **Charts & graphs**: Use color to encode categories or values
+- **Heatmaps**: Color intensity shows density or importance
+- **Comparison**: Color coding for different datasets or timeframes
+
+### Borders & Accents
+- **Hairline borders**: 1px colored borders on full perimeter (not side-stripes; see the absolute ban on `border-left/right > 1px`)
+- **Underlines**: Color underlines for emphasis or active states
+- **Dividers**: Subtle colored dividers instead of gray lines
+- **Focus rings**: Colored focus indicators matching brand
+- **Surface tints**: A 4-8% background wash of the accent color instead of a stripe
+
+**NEVER**: `border-left` or `border-right` greater than 1px as a colored accent stripe. This is one of the three absolute bans in the parent skill. If you want to mark a card as "active" or "warning", use a full hairline border, a background tint, a leading glyph, or a numbered prefix. Not a side stripe.
+
+### Typography Color
+- **Colored headings**: Use brand colors for section headings (maintain contrast)
+- **Highlight text**: Color for emphasis or categories
+- **Labels & tags**: Small colored labels for metadata or categories
+
+### Decorative Elements
+- **Illustrations**: Add colored illustrations or icons
+- **Shapes**: Geometric shapes in brand colors as background elements
+- **Gradients**: Colorful gradient overlays or mesh backgrounds
+- **Blobs/organic shapes**: Soft colored shapes for visual interest
+
+## Balance & Refinement
+
+Ensure color addition improves rather than overwhelms:
+
+### Maintain Hierarchy
+- **Dominant color** (60%): Primary brand color or most used accent
+- **Secondary color** (30%): Supporting color for variety
+- **Accent color** (10%): High contrast for key moments
+- **Neutrals** (remaining): Gray/black/white for structure
+
+### Accessibility
+- **Contrast ratios**: Ensure WCAG compliance (4.5:1 for text, 3:1 for UI components)
+- **Don't rely on color alone**: Use icons, labels, or patterns alongside color
+- **Test for color blindness**: Verify red/green combinations work for all users
+
+### Cohesion
+- **Consistent palette**: Use colors from defined palette, not arbitrary choices
+- **Systematic application**: Same color meanings throughout (green always = success)
+- **Temperature consistency**: Warm palette stays warm, cool stays cool
+
+**NEVER**:
+- Use every color in the rainbow (choose 2-4 colors beyond neutrals)
+- Apply color randomly without semantic meaning
+- Put gray text on colored backgrounds. It looks washed out; use a darker shade of the background color or transparency instead
+- Use pure gray for neutrals. Add subtle color tint (warm or cool) for depth
+- Use pure black (`#000`) or pure white (`#fff`) for large areas
+- Violate WCAG contrast requirements
+- Use color as the only indicator (accessibility issue)
+- Make everything colorful (defeats the purpose)
+- Default to purple-blue gradients (AI slop aesthetic)
+
+## Verify Color Addition
+
+Test that colorization improves the experience:
+
+- **Better hierarchy**: Does color guide attention appropriately?
+- **Clearer meaning**: Does color help users understand states/categories?
+- **More engaging**: Does the interface feel warmer and more inviting?
+- **Still accessible**: Do all color combinations meet WCAG standards?
+- **Not overwhelming**: Is color balanced and purposeful?
+
+When the palette earns its place, hand off to `/impeccable polish` for the final pass.
+
+## Live-mode signature params
+
+When invoked from live mode, each variant MUST declare a `color-amount` param so the user can dial between a restrained accent and a drenched surface without regeneration. Author the variant's CSS against `var(--p-color-amount, 0.5)`, typically as the alpha multiplier on backgrounds, or as a scaling factor on the chroma axis in an OKLCH expression. 0 = neutral/monochrome, 1 = full saturation / dominant coverage.
+
+```json
+{"id":"color-amount","kind":"range","min":0,"max":1,"step":0.05,"default":0.5,"label":"Color amount"}
+```
+
+Layer 1-2 variant-specific params on top: palette selection (`steps` with named options), temperature warmth, or tint vs. true color. See `reference/live.md` for the full params contract.

package/.claude/skills/impeccable/reference/craft.md

@@ -0,0 +1,123 @@
+# Craft Flow
+
+Build a feature with impeccable UX and UI quality: shape the design, land the visual direction, build real production code, inspect and improve in-browser until it meets a high-end studio bar.
+
+Before writing code, you need: PRODUCT.md loaded, register identified and the matching reference loaded, and a confirmed design direction for this task (either from `shape` or supplied by the user). PRODUCT.md is project context, not a task-specific brief.
+
+Treat any approved visual direction (generated mock or stated reference) as a concrete contract for composition, hierarchy, density, atmosphere, signature motifs, and distinctive visual moves. Don't let mocks replace structure, copy, accessibility, or state design. But if the live result lacks the approved direction's major ingredients, the implementation is wrong.
+
+### Gates: do not compress
+
+Craft has **multiple user gates**, not one. When the harness has native image generation (Codex via `image_gen`), the gate sequence before code is:
+
+1. **Shape brief confirmed** (Step 1)
+2. **Direction questions answered** (codex.md Step A)
+3. **Palette confirmed** (codex.md Step B)
+4. **One mock direction approved or delegated** (codex.md Step D)
+
+You must stop at every gate. **Shape confirmation alone is NOT a green light to start coding.** It is the green light to begin codex.md Step A. Compressing gates 2 through 4 because the shape brief felt complete is the dominant failure mode of this flow.
+
+When the harness lacks native image generation, gates 2-4 collapse into the brief itself, and shape confirmation does advance straight to code.
+
+## Step 0: Project Foundation
+
+Before shape, before code: figure out what kind of project you're working in.
+
+Look at the working directory. Run `ls`. Check for:
+
+- An existing framework: `astro.config.mjs/ts`, `next.config.js/ts`, `nuxt.config.ts`, `svelte.config.js`, `vite.config.js/ts`, `package.json` with framework deps, `Cargo.toml` + Leptos/Yew, `Gemfile` + Rails. **If found, use it.** Do not start a parallel build, do not introduce a second framework, do not write to `dist/` or `build/` directly. Whatever pipeline the project has, respect it.
+- An existing component library or design system: `src/components/`, `app/components/`, a `tokens.css` / `theme.ts`, an `astro.config` `integrations`. Read what's there before adding to it.
+- An existing icon set: `lucide-react`, `@phosphor-icons/react`, `@iconify/*`, hand-rolled SVG sprites in `assets/icons/`. **Use what's already in the project**; don't introduce a second set.
+
+If the directory is empty (greenfield), don't pick a framework silently. Ask the user via the AskUserQuestion tool, with sensible defaults framed by the brief:
+
+```text
+What should this be built on?
+  - Astro (default for content-led brand sites, landing pages, marketing surfaces)
+  - SvelteKit / Next.js / Nuxt (when the brief implies an app surface or significant interactivity)
+  - Single index.html (one-shot demo, prototype, or a deliberately framework-free experiment)
+```
+
+Default: Astro for brand briefs, the project's existing framework for product briefs. Ask once; don't re-ask mid-task.
+
+## Step 1: Shape the Design
+
+Run /impeccable shape, passing along whatever feature description the user provided. Shape is **required** for craft; it is what produces a confirmed direction.
+
+Present the shape output and stop. Wait for the user to confirm, override, or course-correct before writing code.
+
+If the user already supplied a confirmed brief or ran shape separately, use it and skip this step.
+
+When the original prompt + PRODUCT.md already answer scope, content, and visual direction with no real ambiguity, the shape output can be **compact** (3-5 bullets stating what you're building and the visual lane, ending with one or two specific questions or "confirm or override"). The full 10-section structured brief is reserved for genuinely ambiguous, multi-screen, or stakeholder-heavy tasks. Don't pad a clear brief into a long one to look thorough; equally, don't skip the pause to look efficient.
+
+If the harness has native image generation (Codex), a compact shape's "confirm or override" advances to **Step 3 and the codex.md flow**, not to Step 4. Phrase the closing line accordingly: "Confirm or override; once we lock direction, I'll run a couple of palette and reference questions before generating any mocks." This stops the model from reading shape confirmation as code-green.
+
+## Step 2: Load References
+
+Based on the design brief's "Recommended References" section, consult the relevant impeccable reference files. At minimum, always consult:
+
+- [spatial-design.md](spatial-design.md) for layout and spacing
+- [typography.md](typography.md) for type hierarchy
+
+Then add references based on the brief's needs:
+- Complex interactions or forms? Consult [interaction-design.md](interaction-design.md)
+- Animation or transitions? Consult [motion-design.md](motion-design.md)
+- Color-heavy or themed? Consult [color-and-contrast.md](color-and-contrast.md)
+- Responsive requirements? Consult [responsive-design.md](responsive-design.md)
+- Heavy on copy, labels, or errors? Consult [ux-writing.md](ux-writing.md)
+
+## Step 3: Visual Direction & Assets (Harness-Gated)
+
+If the harness has **native image generation** (currently Codex via `image_gen`), this step is mandatory. **Stop and load [codex.md](codex.md)**. It covers palette generation, mock exploration, the approval loop, mock-fidelity inventory, and asset slicing via the `impeccable_asset_producer` subagent. Follow Steps A-F in that file, then return here for Step 4.
+
+If the harness lacks native image generation, **state in one line that the visual-direction-by-generation step is being skipped because the harness lacks native image generation, then proceed**. The one-line announcement is required; it forces a conscious decision instead of letting the step quietly evaporate. The brief is your only visual reference. Implement directly from it, treating any named anchor references and the brief's "Design Direction" as the contract.
+
+Whether you generated mocks or not: don't replace required imagery with generic cards, bullets, emoji, fake metrics, decorative CSS panels, or filler copy. Image-led briefs (restaurants, hotels, magazines, photography, hobbyist communities, food, travel, fashion, product) need real or sourced imagery in the build, not CSS scenery.
+
+## Step 4: Build to Production Quality
+
+**Precondition.** If Step 3 routed you to codex.md (native image generation available), Steps A through D in that file must be complete before any code: questions answered, palette confirmed, mocks generated, one direction approved or delegated. **Do not mention implementation, file paths, or patch plans until that's done.** A confirmed shape brief is not enough; the model that compressed those gates is the model that already failed this flow.
+
+Implement the feature following the design brief. Build in passes so structure, visual system, states, motion/media, and responsive behavior each get deliberate attention. The list below is the definition of done, not inspiration.
+
+### Production bar
+
+- **Real content.** No placeholder copy, placeholder images, dead links, fake controls, or unused scaffold at presentation time.
+- **Preserve the approved mock's major ingredients.** Missing hero objects, world/product imagery, section structure, CTA/nav treatment, or distinctive motifs are blocking defects unless the user accepted the change.
+- **Semantic first.** Real headings, landmarks, labels, form associations, button/link semantics, accessible names, state announcements where needed.
+- **Deliberate spacing and alignment.** No default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
+- **Intentional typography.** Chosen loading strategy, clear hierarchy, readable measure, stable line breaks, no overflow at any width.
+- **Realistic state coverage.** Default, hover, focus-visible, active, disabled, loading, error, success, empty, overflow, long/short text, first-run.
+- **Finished interaction quality.** Keyboard paths, touch targets, feedback timing, scroll behavior, state transitions, no hover-only functionality.
+- **Coherent icon set.** Use the project's established set; otherwise pick one library or use accessible text. Don't mix.
+- **Respect the build pipeline.** Edit source files and run the project's build (`npm run build` or equivalent). Don't write to `build/` / `dist/` / `.next/` with `cat`, heredoc, or Bash redirects; that skips asset hashing, image optimization, code splitting, and CSS extraction, and produces output the dev server won't serve.
+- **Verify image URLs before referencing them.** Use image-search MCP or web-fetch when available; guessed photo IDs ship as broken-image placeholders. Without verification, prefer fewer images you're confident about.
+- **Optimized imagery and media.** Correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset`/`picture` for raster, no project-referenced asset left outside the workspace.
+- **Premium motion.** Use atmospheric blur, filter, mask, shadow, reveal when they improve the experience. Avoid casual layout-property animation, bound expensive effects, verify smoothness in-browser, respect reduced motion, and avoid choreography that blocks task completion.
+- **Maintainable.** Reusable local patterns, clear component boundaries, project conventions. No rasterized UI text or one-off hacks when a local pattern exists.
+- **Technically clean.** Production build passes, no console errors, no avoidable layout shift, no needless dependencies, no broken asset paths.
+- **Ask when uncertain.** If a discovery materially changes the brief or approved direction, stop and ask. Don't guess.
+
+## Step 5: Iterate Visually
+
+Look at what you built like a designer would. Your eyes are whatever the harness gives you: a connected browser, a screenshotting tool, Playwright, or asking the user. Use them for responsive testing (mobile, tablet, desktop minimum) and general visual validation.
+
+If your tool returns a file path, read the PNG back into the conversation. A screenshot you didn't read doesn't count.
+
+For long-form brand surfaces, inspect major sections individually. Thumbnails hide spacing, clipping, and cascade defects.
+
+After the first pass, write an honest critique against the brief, the approved mock's major ingredients (hero silhouette, motifs, imagery, nav/CTA, density), and impeccable's DON'Ts. Patch material defects and re-inspect. **Don't invent defects to demonstrate iteration.** A confident "first pass clean, shipping" beats a fake fix.
+
+Actively check: responsive behavior (composes, not shrinks), every state (empty / error / loading / edge), craft details (spacing, alignment, hierarchy, contrast, motion timing, focus), performance basics. The exit bar: defensible in a high-end studio review.
+
+Detector or QA output is defect evidence only; never proof the work is finished.
+
+## Step 6: Present
+
+Present the result to the user:
+- Show the feature in its primary state
+- Summarize the browser/viewports checked and the most important fixes made after inspection
+- Walk through the key states (empty, error, responsive)
+- Explain design decisions that connect back to the design brief and, when used, the chosen north-star mock. Include any accepted deviations from the mock; do not hide unimplemented mock ingredients.
+- Note any remaining limitations or follow-up risks honestly
+- Ask: "What's working? What isn't?"

package/.claude/skills/impeccable/reference/critique.md

@@ -0,0 +1,236 @@
+### Purpose
+
+Resolve one stable target, run two independent assessments, synthesize a design critique, persist a snapshot, and ask the user what to improve next. The chat response is the primary deliverable; the snapshot is an archive/backlog for future commands.
+
+### Hard Invariants
+
+- Assessment A (design review) and Assessment B (detector/browser evidence) are both required.
+- Assessment A must finish before detector findings enter the parent synthesis context. Detector output is deterministic, but it still anchors judgment.
+- If sub-agents are unavailable, fall back sequentially: finish and record Assessment A first, then run Assessment B, then synthesize.
+- A skipped detector is a failed critique run unless `detect.mjs` is missing or crashes after a real attempt.
+- Viewable targets require browser inspection when available.
+- Any local server started only for critique visualization must run in the background, have a recorded stop method, and be stopped before final reporting unless the user asks to keep it.
+- Do not claim a user-visible overlay exists unless script injection succeeded and the detector ran in the page.
+
+### Setup
+
+1. **Resolve the target** to a concrete file path or URL. Prefer a source path over a dev-server URL when both identify the same surface; ports drift, paths do not.
+   - "the homepage" -> `site/pages/index.astro` or `index.html`
+   - "the settings modal" -> the primary component file
+   - "this page" -> the current URL or source file
+2. **Compute the slug**:
+   ```bash
+   node .claude/skills/impeccable/scripts/critique-storage.mjs slug "<resolved-path-or-url>"
+   ```
+   Keep it. If the command exits non-zero, skip persistence and trend for this run, but continue the critique.
+3. **Read `.impeccable/critique/ignore.md`** if it exists. Drop matching findings silently; it is the only prior-run input critique consumes.
+
+### Assessment Orchestration
+
+Delegate Assessment A and Assessment B to separate sub-agents when possible. They must not see each other's output. Do not show findings to the user until synthesis.
+
+If browser automation is available, each assessment creates its own new tab. Never reuse an existing tab, even if it is already at the right URL.
+
+### Assessment A: Design Review
+
+Read relevant source files and visually inspect the live page when browser automation is available. Think like a design director.
+
+Evaluate:
+- **AI slop**: Would someone believe "AI made this" immediately? Check all DON'T guidance from the parent Impeccable skill.
+- **Holistic design**: hierarchy, IA, emotional fit, discoverability, composition, typography, color, accessibility, states, copy, and edge cases.
+- **Cognitive load**: consult [cognitive-load](cognitive-load.md); report checklist failures and decision points with >4 visible options.
+- **Emotional journey**: peak-end rule, emotional valleys, reassurance at high-stakes moments.
+- **Nielsen heuristics**: consult [heuristics-scoring](heuristics-scoring.md); score all 10 heuristics 0-4.
+
+Return: AI slop verdict, heuristic scores, cognitive load, emotional journey, 2-3 strengths, 3-5 priority issues, persona red flags, minor observations, and provocative questions.
+
+### Assessment B: Detector + Browser Evidence
+
+Run the bundled detector and browser visualization evidence. Assessment B is mandatory and must remain isolated from Assessment A until both are complete.
+
+CLI scan:
+```bash
+node .claude/skills/impeccable/scripts/detect.mjs --json [--fast] [target]
+```
+
+- Pass markup files/directories as `[target]`; do not pass CSS-only files.
+- For URLs, skip CLI scan and use browser visualization.
+- For 200+ scannable files, use `--fast`; for 500+, narrow scope or ask.
+- Exit code 0 = clean; 2 = findings.
+- If the detector entrypoint is missing or fails to load, report deterministic scan unavailable and continue with browser/manual review.
+
+Browser visualization is required for a viewable target when browser automation is available. Use a localhost dev/static URL for local files; avoid `file://` unless the available browser explicitly supports this workflow. Overlay flow:
+
+1. Create a fresh tab and navigate.
+2. Preflight mutable injection by setting `document.title` and appending a `<script>` tag. Read-only evaluate APIs do not count.
+3. If mutation is unavailable, skip live server, browser presentation, and injection; report fallback signal.
+4. If mutation is available, start `node .claude/skills/impeccable/scripts/live-server.mjs --background`, present the browser if supported, label `[Human]`, scroll top, inject `http://localhost:PORT/detect.js`, wait 2-3 seconds, read `impeccable` console messages, then stop the live server.
+5. For multi-view targets, inject on 3-5 representative pages.
+
+Return: CLI findings JSON/counts, browser console findings if applicable, false positives, and skipped/failed browser steps with concrete reasons.
+
+After Assessment B returns usable CLI findings, reuse them. Do not rerun `detect.mjs` in the parent unless Assessment B failed, was truncated, or omitted count, rule names, or file locations.
+
+### Generate Combined Critique Report
+
+Synthesize both assessments into a single report. Do NOT simply concatenate. Weave the findings together, noting where the LLM review and detector agree, where the detector caught issues the LLM missed, and where detector findings are false positives.
+
+The chat response is the primary user-facing deliverable. Present the full structured critique below in chat; do not replace it with a summary and a link. The persisted snapshot is only an archive/backlog for later commands.
+
+Structure your feedback as a design director would:
+
+#### Design Health Score
+> *Consult [heuristics-scoring](heuristics-scoring.md)*
+
+Present the Nielsen's 10 heuristics scores as a table:
+
+| # | Heuristic | Score | Key Issue |
+|---|-----------|-------|-----------|
+| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] |
+| 2 | Match System / Real World | ? | |
+| 3 | User Control and Freedom | ? | |
+| 4 | Consistency and Standards | ? | |
+| 5 | Error Prevention | ? | |
+| 6 | Recognition Rather Than Recall | ? | |
+| 7 | Flexibility and Efficiency | ? | |
+| 8 | Aesthetic and Minimalist Design | ? | |
+| 9 | Error Recovery | ? | |
+| 10 | Help and Documentation | ? | |
+| **Total** | | **??/40** | **[Rating band]** |
+
+Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32.
+
+#### Anti-Patterns Verdict
+
+**Start here.** Does this look AI-generated?
+
+**LLM assessment**: Your own evaluation of AI slop tells. Cover overall aesthetic feel, layout sameness, generic composition, missed opportunities for personality.
+
+**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. Note any additional issues the detector caught that you missed, and flag any false positives.
+
+**Visual overlays** (if injection succeeded): Tell the user that overlays are now visible in the **[Human]** tab in their browser, highlighting the detected issues. Summarize what the console output reported. If browser visualization was attempted but injection failed, say that no reliable user-visible overlay is available and report the fallback signal instead.
+
+#### Overall Impression
+A brief gut reaction: what works, what doesn't, and the single biggest opportunity.
+
+#### What's Working
+Highlight 2-3 things done well. Be specific about why they work.
+
+#### Priority Issues
+The 3-5 most impactful design problems, ordered by importance.
+
+For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuristics-scoring.md) for severity definitions):
+- **[P?] What**: Name the problem clearly
+- **Why it matters**: How this hurts users or undermines goals
+- **Fix**: What to do about it (be concrete)
+- **Suggested command**: Which command could address this (from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset)
+
+#### Persona Red Flags
+> *Consult [personas](personas.md)*
+
+Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `CLAUDE.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info.
+
+For each selected persona, walk through the primary user action and list specific red flags found:
+
+**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.
+
+**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.
+
+Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them.
+
+#### Minor Observations
+Quick notes on smaller issues worth addressing.
+
+#### Questions to Consider
+Provocative questions that might unlock better solutions:
+- "What if the primary action were more prominent?"
+- "Does this need to feel this complex?"
+- "What would a confident version of this look like?"
+
+**Remember**:
+- Be direct. Vague feedback wastes everyone's time.
+- Be specific. "The submit button," not "some elements."
+- Say what's wrong AND why it matters to users.
+- Give concrete suggestions. Cut "consider exploring..." entirely.
+- Prioritize ruthlessly. If everything is important, nothing is.
+- Don't soften criticism. Developers need honest feedback to ship great design.
+
+### Persist the Snapshot
+
+Once the report above is finalized, write it to `.impeccable/critique/` so the user can refer back, and so `/impeccable polish` can pick up the priority issues without a copy-paste.
+
+Skip this step if the Setup slug was null (vague or root-level target).
+
+1. **Write the body to a temp file** so you can pipe it to the helper. Use the full critique report (heuristic table, anti-patterns verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later.
+
+2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command:
+   ```bash
+   IMPECCABLE_CRITIQUE_META='{"target":"<user phrasing>","total_score":<n>,"p0_count":<n>,"p1_count":<n>}' \
+     node .claude/skills/impeccable/scripts/critique-storage.mjs write <slug> <body-file>
+   ```
+   The helper prints the absolute path it wrote.
+
+3. **Delete the temp body file** after the write attempt completes, whether the write succeeded or failed. If deletion fails, mention `temp-file cleanup failed: <reason>` briefly in the final output, but do not block the critique.
+
+4. **Read the trend** for context:
+   ```bash
+   node .claude/skills/impeccable/scripts/critique-storage.mjs trend <slug> 5
+   ```
+   This returns a JSON array of the last 5 frontmatter entries (including the one you just wrote).
+
+5. **Append a single line to the user-visible output**, after the report and before the questions:
+
+   > **Trend for `<slug>` (last 5 runs): 24 → 28 → 32 → 29 → 32**
+   > Wrote `.impeccable/critique/<filename>`.
+
+   If this is the first run for the slug, the trend is just one score; say so: "First run for this target, no trend yet."
+
+This is fire-and-forget. Do not show the user the helper's JSON output; only the human-readable trend line and the written path. Failures here should not block the rest of the flow; print the error and move on.
+
+### Ask the User
+
+**After presenting findings**, use targeted questions based on what was actually found. STOP and call the AskUserQuestion tool to clarify. These answers will shape the action plan.
+
+Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions):
+
+1. **Priority direction**: Based on the issues found, ask which category matters most to the user right now. For example: "I found problems with visual hierarchy, color usage, and information overload. Which area should we tackle first?" Offer the top 2-3 issue categories as options.
+
+2. **Design intent**: If the critique found a tonal mismatch, ask whether it was intentional. For example: "The interface feels clinical and corporate. Is that the intended tone, or should it feel warmer/bolder/more playful?" Offer 2-3 tonal directions as options based on what would fix the issues found.
+
+3. **Scope**: Ask how much the user wants to take on. For example: "I found N issues. Want to address everything, or focus on the top 3?" Offer scope options like "Top 3 only", "All issues", "Critical issues only".
+
+4. **Constraints** (optional; only ask if relevant): If the findings touch many areas, ask if anything is off-limits. For example: "Should any sections stay as-is?" This prevents the plan from touching things the user considers done.
+
+**Rules for questions**:
+- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions.
+- Keep it to 2-4 questions maximum. Respect the user's time.
+- Offer concrete options, not open-ended prompts.
+- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Recommended Actions.
+
+### Recommended Actions
+
+**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Ask the User.
+
+#### Action Summary
+
+List recommended commands in priority order, based on the user's answers:
+
+1. **`/command-name`**: Brief description of what to fix (specific context from critique findings)
+2. **`/command-name`**: Brief description (specific context)
+...
+
+**Rules for recommendations**:
+- Only recommend commands from: /impeccable adapt, /impeccable animate, /impeccable audit, /impeccable bolder, /impeccable clarify, /impeccable colorize, /impeccable critique, /impeccable delight, /impeccable distill, /impeccable document, /impeccable harden, /impeccable layout, /impeccable onboard, /impeccable optimize, /impeccable overdrive, /impeccable polish, /impeccable quieter, /impeccable shape, /impeccable typeset
+- Order by the user's stated priorities first, then by impact
+- Each item's description should carry enough context that the command knows what to focus on
+- Map each Priority Issue to the appropriate command
+- Skip commands that would address zero issues
+- If the user chose a limited scope, only include items within that scope
+- If the user marked areas as off-limits, exclude commands that would touch those areas
+- End with `/impeccable polish` as the final step if any fixes were recommended
+
+After presenting the summary, tell the user:
+
+> You can ask me to run these one at a time, all at once, or in any order you prefer.
+>
+> Re-run `/impeccable critique` after fixes to see your score improve.