mirror of
https://github.com/pbakaus/impeccable.git
synced 2026-09-12 06:06:37 +03:00
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) <noreply@anthropic.com>
This commit is contained in:
Paul Bakaus
co-authored by
Claude Opus 4.6
Claude Opus 4.6
parent
afcff7eea0
commit
2f49a2709f
@@ -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
|
||||
- Prioritize ruthlessly -- if everything is important, nothing is
|
||||
- Don't soften criticism -- developers need honest feedback to ship great design
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user