1### Purpose
2
3Resolve 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.
4
5### Hard Invariants
6
7- Assessment A (design review) and Assessment B (detector/browser evidence) are both required.
8- Assessment A must finish before detector findings enter the parent synthesis context. Detector output is deterministic, but it still anchors judgment.
9- If sub-agents are unavailable, fall back sequentially: finish and record Assessment A first, then run Assessment B, then synthesize.
10- A skipped detector is a failed critique run unless `detect.mjs` is missing or crashes after a real attempt.
11- Viewable targets require browser inspection when available.
12- 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.
13- Do not claim a user-visible overlay exists unless script injection succeeded and the detector ran in the page.
14
15### Setup
16
171. **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.
18 - "the homepage" -> `site/pages/index.astro` or `index.html`
19 - "the settings modal" -> the primary component file
20 - "this page" -> the current URL or source file
212. **Compute the slug**:
22 ```bash
23 node .trae-cn/skills/impeccable/scripts/critique-storage.mjs slug "<resolved-path-or-url>"
24 ```
25 Keep it. If the command exits non-zero, skip persistence and trend for this run, but continue the critique.
263. **Read `.impeccable/critique/ignore.md`** if it exists. Drop matching findings silently; it is the only prior-run input critique consumes.
27
28### Assessment Orchestration
29
30Delegate 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.
31
32If 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.
33
34### Assessment A: Design Review
35
36Read relevant source files and visually inspect the live page when browser automation is available. Think like a design director.
37
38Evaluate:
39- **AI slop**: Would someone believe "AI made this" immediately? Check all DON'T guidance from the parent Impeccable skill.
40- **Holistic design**: hierarchy, IA, emotional fit, discoverability, composition, typography, color, accessibility, states, copy, and edge cases.
41- **Cognitive load**: consult [cognitive-load](cognitive-load.md); report checklist failures and decision points with >4 visible options.
42- **Emotional journey**: peak-end rule, emotional valleys, reassurance at high-stakes moments.
43- **Nielsen heuristics**: consult [heuristics-scoring](heuristics-scoring.md); score all 10 heuristics 0-4.
44
45Return: AI slop verdict, heuristic scores, cognitive load, emotional journey, 2-3 strengths, 3-5 priority issues, persona red flags, minor observations, and provocative questions.
46
47### Assessment B: Detector + Browser Evidence
48
49Run the bundled detector and browser visualization evidence. Assessment B is mandatory and must remain isolated from Assessment A until both are complete.
50
51CLI scan:
52```bash
53node .trae-cn/skills/impeccable/scripts/detect.mjs --json [--fast] [target]
54```
55
56- Pass markup files/directories as `[target]`; do not pass CSS-only files.
57- For URLs, skip CLI scan and use browser visualization.
58- For 200+ scannable files, use `--fast`; for 500+, narrow scope or ask.
59- Exit code 0 = clean; 2 = findings.
60- If the detector entrypoint is missing or fails to load, report deterministic scan unavailable and continue with browser/manual review.
61
62Browser 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:
63
641. Create a fresh tab and navigate.
652. Preflight mutable injection by setting `document.title` and appending a `<script>` tag. Read-only evaluate APIs do not count.
663. If mutation is unavailable, skip live server, browser presentation, and injection; report fallback signal.
674. If mutation is available, start `node .trae-cn/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.
685. For multi-view targets, inject on 3-5 representative pages.
69
70Return: CLI findings JSON/counts, browser console findings if applicable, false positives, and skipped/failed browser steps with concrete reasons.
71
72After 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.
73
74### Generate Combined Critique Report
75
76Synthesize 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.
77
78The 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.
79
80Structure your feedback as a design director would:
81
82#### Design Health Score
83> *Consult [heuristics-scoring](heuristics-scoring.md)*
84
85Present the Nielsen's 10 heuristics scores as a table:
86
87| # | Heuristic | Score | Key Issue |
88|---|-----------|-------|-----------|
89| 1 | Visibility of System Status | ? | [specific finding or "n/a" if solid] |
90| 2 | Match System / Real World | ? | |
91| 3 | User Control and Freedom | ? | |
92| 4 | Consistency and Standards | ? | |
93| 5 | Error Prevention | ? | |
94| 6 | Recognition Rather Than Recall | ? | |
95| 7 | Flexibility and Efficiency | ? | |
96| 8 | Aesthetic and Minimalist Design | ? | |
97| 9 | Error Recovery | ? | |
98| 10 | Help and Documentation | ? | |
99| **Total** | | **??/40** | **[Rating band]** |
100
101Be honest with scores. A 4 means genuinely excellent. Most real interfaces score 20-32.
102
103#### Anti-Patterns Verdict
104
105**Start here.** Does this look AI-generated?
106
107**LLM assessment**: Your own evaluation of AI slop tells. Cover overall aesthetic feel, layout sameness, generic composition, missed opportunities for personality.
108
109**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.
110
111**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.
112
113#### Overall Impression
114A brief gut reaction: what works, what doesn't, and the single biggest opportunity.
115
116#### What's Working
117Highlight 2-3 things done well. Be specific about why they work.
118
119#### Priority Issues
120The 3-5 most impactful design problems, ordered by importance.
121
122For each issue, tag with **P0-P3 severity** (consult [heuristics-scoring](heuristics-scoring.md) for severity definitions):
123- **[P?] What**: Name the problem clearly
124- **Why it matters**: How this hurts users or undermines goals
125- **Fix**: What to do about it (be concrete)
126- **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)
127
128#### Persona Red Flags
129> *Consult [personas](personas.md)*
130
131Auto-select 2-3 personas most relevant to this interface type (use the selection table in the reference). If `RULES.md` contains a `## Design Context` section from `impeccable teach`, also generate 1-2 project-specific personas from the audience/brand info.
132
133For each selected persona, walk through the primary user action and list specific red flags found:
134
135**Alex (Power User)**: No keyboard shortcuts detected. Form requires 8 clicks for primary action. Forced modal onboarding. High abandonment risk.
136
137**Jordan (First-Timer)**: Icon-only nav in sidebar. Technical jargon in error messages ("404 Not Found"). No visible help. Will abandon at step 2.
138
139Be specific. Name the exact elements and interactions that fail each persona. Don't write generic persona descriptions; write what broke for them.
140
141#### Minor Observations
142Quick notes on smaller issues worth addressing.
143
144#### Questions to Consider
145Provocative questions that might unlock better solutions:
146- "What if the primary action were more prominent?"
147- "Does this need to feel this complex?"
148- "What would a confident version of this look like?"
149
150**Remember**:
151- Be direct. Vague feedback wastes everyone's time.
152- Be specific. "The submit button," not "some elements."
153- Say what's wrong AND why it matters to users.
154- Give concrete suggestions. Cut "consider exploring..." entirely.
155- Prioritize ruthlessly. If everything is important, nothing is.
156- Don't soften criticism. Developers need honest feedback to ship great design.
157
158### Persist the Snapshot
159
160Once 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.
161
162Skip this step if the Setup slug was null (vague or root-level target).
163
1641. **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.
165
1662. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command:
167 ```bash
168 IMPECCABLE_CRITIQUE_META='{"target":"<user phrasing>","total_score":<n>,"p0_count":<n>,"p1_count":<n>}' \
169 node .trae-cn/skills/impeccable/scripts/critique-storage.mjs write <slug> <body-file>
170 ```
171 The helper prints the absolute path it wrote.
172
1733. **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.
174
1754. **Read the trend** for context:
176 ```bash
177 node .trae-cn/skills/impeccable/scripts/critique-storage.mjs trend <slug> 5
178 ```
179 This returns a JSON array of the last 5 frontmatter entries (including the one you just wrote).
180
1815. **Append a single line to the user-visible output**, after the report and before the questions:
182
183 > **Trend for `<slug>` (last 5 runs): 24 → 28 → 32 → 29 → 32**
184 > Wrote `.impeccable/critique/<filename>`.
185
186 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."
187
188This 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.
189
190### Ask the User
191
192**After presenting findings**, use targeted questions based on what was actually found. ask the user directly to clarify what you cannot infer. These answers will shape the action plan.
193
194Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions):
195
1961. **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.
197
1982. **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.
199
2003. **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".
201
2024. **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.
203
204**Rules for questions**:
205- Every question must reference specific findings from the report. Never ask generic "who is your audience?" questions.
206- Keep it to 2-4 questions maximum. Respect the user's time.
207- Offer concrete options, not open-ended prompts.
208- If findings are straightforward (e.g., only 1-2 clear issues), skip questions and go directly to Recommended Actions.
209
210### Recommended Actions
211
212**After receiving the user's answers**, present a prioritized action summary reflecting the user's priorities and scope from Ask the User.
213
214#### Action Summary
215
216List recommended commands in priority order, based on the user's answers:
217
2181. **`/command-name`**: Brief description of what to fix (specific context from critique findings)
2192. **`/command-name`**: Brief description (specific context)
220...
221
222**Rules for recommendations**:
223- 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
224- Order by the user's stated priorities first, then by impact
225- Each item's description should carry enough context that the command knows what to focus on
226- Map each Priority Issue to the appropriate command
227- Skip commands that would address zero issues
228- If the user chose a limited scope, only include items within that scope
229- If the user marked areas as off-limits, exclude commands that would touch those areas
230- End with `/impeccable polish` as the final step if any fixes were recommended
231
232After presenting the summary, tell the user:
233
234> You can ask me to run these one at a time, all at once, or in any order you prefer.
235>
236> Re-run `/impeccable critique` after fixes to see your score improve.