From 2f49a2709f698929f4e966bdaa789da3a230a483 Mon Sep 17 00:00:00 2001 From: Paul Bakaus Date: Thu, 19 Mar 2026 11:58:07 -0700 Subject: [PATCH] Enhance /critique skill with CLI-first scan and browser visualization The critique skill now has three layers of detection: 1. CLI-first pass (always): Runs the deterministic detector via `node {{skills_dir}}/critique/scripts/detect-antipatterns.mjs --json` with scope checks (file count estimation, --fast for 200-500 files, user prompt for >500 files) 2. Browser visualization (when available): If the AI harness has browser automation (Chrome MCP, Cursor browser), injects the detection script into the page for live visual overlays. Reads the browser script via cat, injects via javascript_tool. 3. LLM analysis (always): The existing deep design critique across 10 dimensions, now informed by deterministic scan results. Add {{skills_dir}} placeholder to build system for cross-provider script paths (.claude/skills, .cursor/skills, .gemini/skills, etc). Co-Authored-By: Claude Opus 4.6 (1M context) --- .claude/skills/critique/SKILL.md | 93 ++++++++++++++++++++++++++------ source/skills/critique/SKILL.md | 93 ++++++++++++++++++++++++++------ 2 files changed, 154 insertions(+), 32 deletions(-) diff --git a/.claude/skills/critique/SKILL.md b/.claude/skills/critique/SKILL.md index 977d32adc..ffca3867d 100644 --- a/.claude/skills/critique/SKILL.md +++ b/.claude/skills/critique/SKILL.md @@ -10,23 +10,77 @@ args: ## MANDATORY PREPARATION -Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Use the frontend-design skill -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: what the interface is trying to accomplish. --- -## AUTOMATED ANTI-PATTERN SCAN +## AUTOMATED ANTI-PATTERN SCAN (First Pass) -Before the manual critique, run the deterministic anti-pattern detector bundled with this skill (`scripts/detect-antipatterns.mjs`): +Before the manual critique, run the deterministic anti-pattern detector. This catches 25 issues across AI slop tells and general design quality problems with zero false negatives. + +### Step 1: Determine the target + +Based on the user's request, identify what to scan: +- **Specific file(s)**: Use the file path(s) directly +- **Component/area**: Identify the relevant directory or files +- **URL**: Use the URL directly (the script supports URL scanning via Puppeteer) +- **Whole project / vague target**: Default to the project root, but check scope first + +### Step 2: Check scope (directories only) + +For directory targets, estimate the number of scannable files first: ```bash -node scripts/detect-antipatterns.mjs [target-area] +find [target-dir] -type f \( -name "*.html" -o -name "*.htm" -o -name "*.css" -o -name "*.scss" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.astro" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" | wc -l ``` -Include the results in your Anti-Patterns Verdict. If the script finds issues, they MUST appear in the Priority Issues list. +- **< 200 files**: Run full scan (jsdom for HTML, regex for the rest) +- **200-500 files**: Run with `--fast` (regex-only, much faster) +- **> 500 files**: Narrow scope. Scan only the most relevant subdirectory, or ask the user which area to focus on. + +### Step 3: Run the scan + +```bash +node scripts/detect-antipatterns.mjs --json [--fast] [target] +``` + +The script exits with code 0 (clean) or 2 (findings). Use `--json` for structured output that's easier to parse. + +### Step 4: Interpret results + +- If findings are found, they MUST appear in the Anti-Patterns Verdict and Priority Issues +- Group findings by type (e.g., "5 side-tab borders across 3 files, 2 gradient text instances") +- Note which files have the most issues +- Deterministic findings are ground truth. Do not contradict them in the LLM analysis. --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +## BROWSER VISUALIZATION (When Available) + +If you have access to browser automation tools that control a real visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool` and `mcp__claude-in-chrome__navigate`, or Cursor's browser integration), AND the target includes a viewable page (HTML file or URL), enhance the critique with live visual overlays. + +### How it works + +1. **Navigate to the page**: For URLs, navigate directly. For local HTML files, check if a dev server is running (look at package.json scripts for `dev`, `start`, or `serve`) and use its URL. As a fallback, try `file:///` + absolute path. + +2. **Read the browser detection script**: +```bash +cat scripts/detect-antipatterns-browser.js +``` + +3. **Inject the script** via `javascript_tool` (or equivalent): Pass the entire script content as JavaScript to evaluate in the page context. The script is an IIFE that auto-executes and shows visual overlays. + +4. **Interpret**: After injection, the user's browser shows pink/magenta outlines around every problematic element with labels describing the issue. A banner at the top shows page-level findings. The user can hover overlays to see detailed tooltips. + +5. **Reference the visuals** in your critique report: "As highlighted in the browser, the card component uses a side-tab border pattern..." + +If the target has multiple important views (e.g., a full site), inject the script on 3-5 representative pages. + +**If injection fails** (tool not available, CSP error, page won't load), continue with CLI scan results only. Do not let browser issues block the critique. + +--- + +Conduct a holistic design critique, evaluating whether the interface actually works -- not just technically, but as a designed experience. Think like a design director giving feedback. ## Design Critique @@ -36,7 +90,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill -- they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -55,7 +109,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk ### 4. Emotional Resonance - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful -- whatever it should feel? - Would the target user feel "this is for me"? ### 5. Discoverability & Affordance @@ -80,7 +134,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically -- does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -99,10 +153,17 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk Structure your feedback as a design director would: ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. + +**Start here.** Does this look AI-generated? + +**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. These are confirmed issues. Do not dispute them. + +**Visual overlays** (if browser was used): Reference what the user can see highlighted in their browser. + +**LLM assessment**: Your own evaluation of AI slop tells beyond what the detector checks. The detector covers 25 specific patterns; your assessment should cover everything else: overall aesthetic feel, layout sameness, generic composition, missed opportunities for personality. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +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. @@ -114,7 +175,7 @@ For each issue: - **What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive — or other installed skills you're sure exist) +- **Command**: Which command to use (prefer: /animate, /quieter, /optimize, /adapt, /clarify, /distill, /delight, /onboard, /normalize, /audit, /harden, /polish, /extract, /bolder, /arrange, /typeset, /critique, /colorize, /overdrive -- or other installed skills you're sure exist) ### Minor Observations Quick notes on smaller issues worth addressing. @@ -126,9 +187,9 @@ Provocative questions that might unlock better solutions: - "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" +- 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, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design \ No newline at end of file +- Prioritize ruthlessly -- if everything is important, nothing is +- Don't soften criticism -- developers need honest feedback to ship great design \ No newline at end of file diff --git a/source/skills/critique/SKILL.md b/source/skills/critique/SKILL.md index a82726e01..262036525 100644 --- a/source/skills/critique/SKILL.md +++ b/source/skills/critique/SKILL.md @@ -10,23 +10,77 @@ user-invokable: true ## MANDATORY PREPARATION -Use the frontend-design skill — it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding — if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: what the interface is trying to accomplish. +Use the frontend-design skill -- it contains design principles, anti-patterns, and the **Context Gathering Protocol**. Follow the protocol before proceeding -- if no design context exists yet, you MUST run teach-impeccable first. Additionally gather: what the interface is trying to accomplish. --- -## AUTOMATED ANTI-PATTERN SCAN +## AUTOMATED ANTI-PATTERN SCAN (First Pass) -Before the manual critique, run the deterministic anti-pattern detector bundled with this skill (`scripts/detect-antipatterns.mjs`): +Before the manual critique, run the deterministic anti-pattern detector. This catches 25 issues across AI slop tells and general design quality problems with zero false negatives. + +### Step 1: Determine the target + +Based on the user's request, identify what to scan: +- **Specific file(s)**: Use the file path(s) directly +- **Component/area**: Identify the relevant directory or files +- **URL**: Use the URL directly (the script supports URL scanning via Puppeteer) +- **Whole project / vague target**: Default to the project root, but check scope first + +### Step 2: Check scope (directories only) + +For directory targets, estimate the number of scannable files first: ```bash -node scripts/detect-antipatterns.mjs [target-area] +find [target-dir] -type f \( -name "*.html" -o -name "*.htm" -o -name "*.css" -o -name "*.scss" -o -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.astro" \) -not -path "*/node_modules/*" -not -path "*/.git/*" -not -path "*/dist/*" -not -path "*/build/*" -not -path "*/.next/*" | wc -l ``` -Include the results in your Anti-Patterns Verdict. If the script finds issues, they MUST appear in the Priority Issues list. +- **< 200 files**: Run full scan (jsdom for HTML, regex for the rest) +- **200-500 files**: Run with `--fast` (regex-only, much faster) +- **> 500 files**: Narrow scope. Scan only the most relevant subdirectory, or ask the user which area to focus on. + +### Step 3: Run the scan + +```bash +node scripts/detect-antipatterns.mjs --json [--fast] [target] +``` + +The script exits with code 0 (clean) or 2 (findings). Use `--json` for structured output that's easier to parse. + +### Step 4: Interpret results + +- If findings are found, they MUST appear in the Anti-Patterns Verdict and Priority Issues +- Group findings by type (e.g., "5 side-tab borders across 3 files, 2 gradient text instances") +- Note which files have the most issues +- Deterministic findings are ground truth. Do not contradict them in the LLM analysis. --- -Conduct a holistic design critique, evaluating whether the interface actually works—not just technically, but as a designed experience. Think like a design director giving feedback. +## BROWSER VISUALIZATION (When Available) + +If you have access to browser automation tools that control a real visual browser in front of the user (e.g., `mcp__claude-in-chrome__javascript_tool` and `mcp__claude-in-chrome__navigate`, or Cursor's browser integration), AND the target includes a viewable page (HTML file or URL), enhance the critique with live visual overlays. + +### How it works + +1. **Navigate to the page**: For URLs, navigate directly. For local HTML files, check if a dev server is running (look at package.json scripts for `dev`, `start`, or `serve`) and use its URL. As a fallback, try `file:///` + absolute path. + +2. **Read the browser detection script**: +```bash +cat scripts/detect-antipatterns-browser.js +``` + +3. **Inject the script** via `javascript_tool` (or equivalent): Pass the entire script content as JavaScript to evaluate in the page context. The script is an IIFE that auto-executes and shows visual overlays. + +4. **Interpret**: After injection, the user's browser shows pink/magenta outlines around every problematic element with labels describing the issue. A banner at the top shows page-level findings. The user can hover overlays to see detailed tooltips. + +5. **Reference the visuals** in your critique report: "As highlighted in the browser, the card component uses a side-tab border pattern..." + +If the target has multiple important views (e.g., a full site), inject the script on 3-5 representative pages. + +**If injection fails** (tool not available, CSP error, page won't load), continue with CLI scan results only. Do not let browser issues block the critique. + +--- + +Conduct a holistic design critique, evaluating whether the interface actually works -- not just technically, but as a designed experience. Think like a design director giving feedback. ## Design Critique @@ -36,7 +90,7 @@ Evaluate the interface across these dimensions: **This is the most important check.** Does this look like every other AI-generated interface from 2024-2025? -Review the design against ALL the **DON'T** guidelines in the frontend-design skill—they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. +Review the design against ALL the **DON'T** guidelines in the frontend-design skill -- they are the fingerprints of AI-generated work. Check for the AI color palette, gradient text, dark mode with glowing accents, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If you showed this to someone and said "AI made this," would they believe you immediately? If yes, that's the problem. @@ -55,7 +109,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk ### 4. Emotional Resonance - What emotion does this interface evoke? Is that intentional? - Does it match the brand personality? -- Does it feel trustworthy, approachable, premium, playful—whatever it should feel? +- Does it feel trustworthy, approachable, premium, playful -- whatever it should feel? - Would the target user feel "this is for me"? ### 5. Discoverability & Affordance @@ -80,7 +134,7 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk - Is color used to communicate, not just decorate? - Does the palette feel cohesive? - Are accent colors drawing attention to the right things? -- Does it work for colorblind users? (not just technically—does meaning still come through?) +- Does it work for colorblind users? (not just technically -- does meaning still come through?) ### 9. States & Edge Cases - Empty states: Do they guide users toward action, or just say "nothing here"? @@ -99,10 +153,17 @@ Review the design against ALL the **DON'T** guidelines in the frontend-design sk Structure your feedback as a design director would: ### Anti-Patterns Verdict -**Start here.** Pass/fail: Does this look AI-generated? List specific tells from the skill's Anti-Patterns section. Be brutally honest. + +**Start here.** Does this look AI-generated? + +**Deterministic scan**: Summarize what the automated detector found, with counts and file locations. These are confirmed issues. Do not dispute them. + +**Visual overlays** (if browser was used): Reference what the user can see highlighted in their browser. + +**LLM assessment**: Your own evaluation of AI slop tells beyond what the detector checks. The detector covers 25 specific patterns; your assessment should cover everything else: overall aesthetic feel, layout sameness, generic composition, missed opportunities for personality. ### Overall Impression -A brief gut reaction—what works, what doesn't, and the single biggest opportunity. +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. @@ -114,7 +175,7 @@ For each issue: - **What**: Name the problem clearly - **Why it matters**: How this hurts users or undermines goals - **Fix**: What to do about it (be concrete) -- **Command**: Which command to use (prefer: {{available_commands}} — or other installed skills you're sure exist) +- **Command**: Which command to use (prefer: {{available_commands}} -- or other installed skills you're sure exist) ### Minor Observations Quick notes on smaller issues worth addressing. @@ -126,9 +187,9 @@ Provocative questions that might unlock better solutions: - "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" +- 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, not just "consider exploring..." -- Prioritize ruthlessly—if everything is important, nothing is -- Don't soften criticism—developers need honest feedback to ship great design +- Prioritize ruthlessly -- if everything is important, nothing is +- Don't soften criticism -- developers need honest feedback to ship great design