@monoes/monomindcli 1.8.0 → 1.9.1

package/.claude/skills/monodesign/reference/copy-formulas.md

@@ -0,0 +1,160 @@
+# Copy Formulas
+
+Persuasive writing frameworks for UI copy — CTAs, empty states, error messages, onboarding, landing sections, and confirmations. Use during `clarify` workflows.
+
+---
+
+## Core Frameworks
+
+### PAS (Problem → Agitate → Solution)
+
+**Best for:** Error messages, empty states, pain-point sections.
+
+```
+Problem:  Name the specific issue.
+Agitate:  Show the consequence if unresolved.
+Solution: Offer the direct fix.
+```
+
+**Template:** "[Pain point]? Without [solution], [consequence]. [Action] to fix this."
+
+**UI examples:**
+- Empty state: "No data yet. Without a connected account, nothing here will populate. Connect your first account →"
+- Error: "Payment failed. Your card may have been declined or expired. Try a different card →"
+
+---
+
+### AIDA (Attention → Interest → Desire → Action)
+
+**Best for:** CTAs, landing hero copy, onboarding headlines.
+
+```
+Attention: Bold statement or provocative question.
+Interest:  The relevant benefit detail.
+Desire:    Proof or stakes.
+Action:    The direct CTA.
+```
+
+**Template:** "[Bold statement]. [Benefit]. [Proof/stakes]. [CTA]."
+
+**UI examples:**
+- Hero: "Ship faster. 10,000+ teams cut deploy time in half. Start free →"
+- Onboarding: "Your workspace is ready. Connect your tools and invite your team to see everything in one place. Get started →"
+
+---
+
+### FAB (Feature → Advantage → Benefit)
+
+**Best for:** Feature callouts, tooltip copy, product UI explanations.
+
+```
+Feature:   What it does.
+Advantage: Why that matters.
+Benefit:   What the user gains.
+```
+
+**Template:** "[Feature] lets you [advantage], so you can [benefit]."
+
+**UI examples:**
+- Tooltip: "Batch export sends all files at once, so you spend less time waiting."
+- Feature highlight: "Auto-save preserves your work every 30 seconds, so you never lose a draft."
+
+---
+
+### BAB (Before → After → Bridge)
+
+**Best for:** Onboarding flows, upgrade prompts, transformation moments.
+
+```
+Before: The current pain state.
+After:  The desired state.
+Bridge: Your feature is the path between them.
+```
+
+**Template:** "[Pain before]. [Desired state after]. [Feature] is how you get there."
+
+---
+
+### Cost of Inaction
+
+**Best for:** Upgrade prompts, warning states, deadline-driven copy.
+
+```
+Status quo: What happens if nothing changes.
+Loss:       Quantify or qualify the cost.
+Time:       The consequence compounds.
+```
+
+**Template:** "Without [action], you're losing [cost] every [timeframe]."
+
+---
+
+## UI Copy Patterns by Surface
+
+| Surface | Primary formula | Tone | Key rule |
+|---------|-----------------|------|----------|
+| Empty state | PAS | Helpful | Give an action, not just a message |
+| Error message | PAS | Direct | State cause + how to fix |
+| CTA button | AIDA (action only) | Active | Imperative verb first |
+| Onboarding headline | AIDA | Confident | No "welcome to" openers |
+| Feature tooltip | FAB | Informative | One sentence max |
+| Confirmation dialog | Direct | Neutral | Restate what will happen |
+| Success feedback | Direct | Warm | Specific, not generic ("Saved!" not "Done") |
+| Upgrade prompt | BAB | Aspirational | Show the after, not just the price |
+| Destructive warning | Direct + Cost of Inaction | Serious | Name the exact thing being deleted |
+
+---
+
+## Headline Patterns
+
+### Action-forward
+- "Stop [bad thing]"
+- "Get [desired result] in [timeframe]"
+- "The [adjective] way to [action]"
+- "[Number] [things] in [timeframe]"
+
+### Contrast
+- "[Old way] is [problem]. [New way] is [benefit]."
+- "Don't [bad action] — [good action] instead."
+- "From [pain state] to [desired state]."
+
+### Social proof
+- "[N]+ teams use [product] to [outcome]"
+- "Trusted by [category] at [notable company]"
+
+---
+
+## UI Copy Anti-Patterns
+
+**Never:**
+- Start a CTA with "Click here" or "Learn more" — be specific about the outcome
+- Use passive voice in error messages ("An error was encountered") — say what happened
+- Hedge: "This might help", "You may want to", "Perhaps consider" — be direct
+- Restate the heading in the first sentence of body copy
+- Use em dashes — use commas, colons, or periods instead (monodesign rule)
+- Write "Successfully saved" when "Saved" says the same thing in half the words
+- Put error messages only at the top of a form — repeat them near the field
+
+**Destructive action dialogs — exact pattern:**
+```
+Heading:   Delete "[specific item name]"?
+Body:      This will permanently delete the project and all its files. This cannot be undone.
+Buttons:   [Cancel]   [Delete project]  ← destructive verb, not just "OK" or "Confirm"
+```
+
+---
+
+## Copy Length Rules
+
+| Element | Max words |
+|---------|-----------|
+| CTA button label | 5 |
+| Alert/toast message | 15 |
+| Empty state description | 25 |
+| Error message (cause + fix) | 30 |
+| Tooltip / helper text | 20 |
+| Confirmation dialog body | 40 |
+| Feature callout subtitle | 20 |
+| Onboarding step description | 30 |
+
+Short copy is a skill. Every word that isn't earning its place is costing user attention.

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

@@ -0,0 +1,193 @@
+# Craft Flow
+
+Build a feature with impeccable UX and UI quality through a structured process: shape the design, land the visual direction, build real production code, then inspect and improve in-browser until the result meets a high-end studio bar.
+
+## Build Gate
+
+Craft cannot build until all of these are true:
+
+1. PRODUCT context is valid and current.
+2. The shape design brief is explicitly confirmed by the user for this task, unless the user already provided a confirmed brief.
+3. Implementation references from the brief are loaded.
+4. The shape visual probe decision is recorded: generated, skipped with reason, or already resolved.
+5. The north-star mock decision is recorded: generated, skipped with reason, or not applicable.
+
+PRODUCT.md and `teach` answers do **not** satisfy the shape gate. They are project context only. A compact self-authored brief does not satisfy the shape gate either. `shape=pass` requires a separate user response approving the shape brief or an already-confirmed brief supplied by the user.
+
+Invalid image-skip reasons include: "the final implementation will be semantic HTML/CSS/SVG", "the diagram should stay editable", "a raster mock would not be used directly", or "the product is fictional." Generated probes and mocks are direction artifacts; they are not implementation assets.
+
+## Craft Contract
+
+Craft is not a first pass. It is a loop with these required artifacts:
+
+1. Confirmed design brief from `shape`.
+2. Approved visual direction, from generated probes / mocks when image generation is available.
+3. Mock fidelity inventory: the visible ingredients from the approved direction that must survive into code.
+4. Semantic, functional implementation using the project's real stack and conventions.
+5. Browser evidence across relevant viewports.
+6. At least one critique-and-fix pass after the first browser inspection, unless the first pass has no material defects.
+
+Do not let generated mockups replace interface structure, copy, accessibility, responsive behavior, or state design. But do treat the approved mock as a concrete visual contract for composition, hierarchy, density, atmosphere, signature motifs, image needs, and distinctive visual moves. "North star" means "preserve the important visible ingredients in semantic code," not "use it as loose mood."
+
+## Step 1: Shape the Design
+
+Run /monodesign shape, passing along whatever feature description the user provided.
+
+Wait for the design brief to be fully confirmed by the user before proceeding. The brief is your blueprint, and every implementation decision should trace back to it.
+
+If this craft run resumed after `teach` created PRODUCT.md, run shape now. Do not treat the teach interview, PRODUCT.md, or a summary of project context as a substitute for shape. Shape is task-specific and must cover scope, content/states, visual direction, constraints, anti-goals, probes when applicable, and explicit brief confirmation.
+
+If the user has already run /monodesign shape and has a confirmed design brief, skip this step and use the existing brief.
+
+## 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: Land the Visual Direction (Capability-Gated)
+
+Before implementation, generate high-fidelity visual comps when all of these are true:
+
+- The work is **net-new** or visually open-ended enough that composition exploration will improve the build.
+- The brief's scope is **mid-fi, high-fi, or production-ready**.
+- The current harness has **built-in image generation capability** (for example, Codex with a native image tool). Do **not** ask the user to set up external APIs, shell scripts, or one-off tooling just to do this.
+
+When those conditions are met, this step is mandatory for **both brand and product work** in Codex and any harness with built-in image generation. Use native image generation; in Codex, use the built-in `image_gen` tool via the imagegen skill. If image generation is unavailable, do not ask the user to install APIs or tooling. State in one line that the image step is skipped because the harness lacks native image generation, then proceed.
+
+Do not skip this step because the eventual UI should be semantic, editable, code-native, responsive, or accessible. Those are implementation requirements, not reasons to avoid visual exploration.
+
+### Purpose
+
+Use the mock step to find a stronger visual lane than code-first generation would reliably discover on its own. The brief remains authoritative on user, purpose, content, constraints, states, and anti-goals. The mock clarifies composition, hierarchy, density, typography, and visual tone.
+
+### What to generate
+
+Generate **1 to 3** high-fidelity north-star comps based on the confirmed brief. If shape already produced direction probes, use those results as input and generate a more resolved mock from the winning lane, not another unrelated exploration.
+
+- For brand work, push visual identity, composition, and mood aggressively.
+- For product work, still push hierarchy, topology, density, and tone, but keep the comps grounded in realistic product structure and states.
+- For landing pages and long-form brand surfaces, show enough of the next section or second fold to establish the system beyond the hero.
+
+The comps must be genuinely different in primary visual direction, not just color variants.
+
+### Approval loop
+
+Show the comps and ask what should carry forward. If the user asks for changes or the best direction is still weak, generate a focused revision before implementation. Continue until one direction is approved, or until the user explicitly delegates the choice.
+
+If the user delegates, pick the strongest direction and explain the decision using the brief, not personal taste.
+
+Before moving to implementation, summarize:
+
+- What to carry into code
+- What **not** to literalize from the mock
+
+This summary is required before Step 4. It is the handoff between visual exploration and semantic implementation.
+
+### Mock fidelity inventory
+
+Before building, inventory the approved mock's major visible ingredients:
+
+- Hero silhouette and dominant composition.
+- Signature motifs: planets, devices, portraits, charts, route lines, insets, badges, or other memorable objects.
+- Nav and primary CTA treatment.
+- Section sequence visible in the mock, especially the second fold.
+- Image-native content the concept depends on.
+- Typography, density, color/material treatment, and motion cues.
+
+For each ingredient, decide how it will be implemented: semantic HTML/CSS/SVG, generated asset, sourced project asset, icon library, canvas/WebGL, or an explicitly accepted omission. Do not substitute a different hero composition or new visual driver after approval unless the user approves the change.
+
+Treat the mock as a **north star**, not a screenshot to trace. Do **not** rasterize core UI text or let the mock override the confirmed brief. But if the live result lacks the mock's major visible ingredients, the implementation is wrong.
+
+## Step 4: Asset Extraction (Need-Gated)
+
+If the chosen direction includes image-native visual ingredients that would materially improve the implementation, generate them as separate assets before building.
+
+Good candidates:
+
+- stickers
+- badges
+- seals
+- tickets
+- graphic labels
+- textures
+- abstract objects
+- decorative marks
+- non-semantic scene elements
+
+For travel, editorial, portfolio, venue, product showcase, entertainment, education, or any other image-led brand surface, visual assets are usually core content, not decoration. Do not ship abstract CSS panels where the approved mock or subject matter calls for real imagery, generated plates, illustrations, maps, product/object renders, or destination scenes.
+
+Do **not** export assets for core UI text, navigation, body copy, or any structure that should stay semantic and editable in code.
+
+Usually **1 to 5** extracted assets is enough. If the design can be built cleanly in HTML/CSS/SVG, prefer that over raster assets. If the mock contains major visual content that cannot be built credibly in code, asset extraction is not optional.
+
+## Step 5: Build to Production Quality
+
+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
+
+- Use real or realistic content. Remove placeholder copy, placeholder images, dead links, fake controls, and unused scaffold before presenting.
+- Preserve the approved mock's major ingredients. Missing hero objects, missing world/product imagery, different section structure, downgraded CTA/nav treatment, or generic replacements for distinctive motifs are blocking defects unless the user accepted the change.
+- Build semantically first: real headings, landmarks, labels, form associations, button/link semantics, accessible names, and state announcements where needed.
+- Calibrate spacing, alignment, grid placement, and vertical rhythm deliberately. Do not accept default gaps, arbitrary margins, unbalanced whitespace, or accidental optical misalignment.
+- Make typography intentional: chosen font loading strategy, clear hierarchy, readable measure, stable line breaks, tuned wrapping, and no overflow at mobile or large desktop sizes.
+- Design realistic state coverage: default, hover where supported, focus-visible, active, disabled, loading, error, success, empty, overflow, long text, short text, and first-run states where relevant.
+- Make interaction quality feel finished: keyboard paths, touch targets, feedback timing, scroll behavior, transitions between states, and no hover-only functionality.
+- Use icons from the project's established icon set when available. If no set exists, choose a coherent library or use accessible text controls; do not mix unrelated icon styles.
+- Optimize imagery and media: correct dimensions, useful alt text, lazy loading below the fold, modern formats when practical, responsive `srcset` / `picture` for raster assets, and no project-referenced asset left outside the workspace.
+- Make motion feel premium: use atmospheric blur, filter, mask, shadow, or reveal effects 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.
+- Preserve maintainability: reusable local patterns, clear component boundaries, project conventions, no rasterized UI text, and no hard-coded one-off hacks when a better local pattern exists.
+- Fit the technical context: production build passes, no obvious console errors, no avoidable layout shift, no needless dependency, and no broken asset path.
+- If you discover a design question that materially changes the brief or approved direction, stop and ask rather than guessing.
+
+## Step 6: Browser-Based Iteration
+
+**This step is critical.** Do not stop after the first implementation pass.
+
+Open the result in a browser. In Codex, use browser-use or equivalent browser automation when available; otherwise use Playwright or ask the user for screenshots. Inspect screenshots, not just DOM or terminal output.
+
+### Required viewport pass
+
+Check the experience at the viewports that matter for the brief. Default minimum:
+
+- Mobile narrow
+- Tablet or small laptop
+- Desktop wide
+
+For each viewport, capture or inspect the rendered state and look for visual defects: overlap, clipping, weak hierarchy, off-grid alignment, awkward whitespace, cramped controls, unreadable type, broken imagery, hover-only functionality, layout shift, and text overflow.
+
+### Critique and fix loop
+
+After the first browser pass, write a short critique for yourself and patch the implementation. Repeat browser inspection after fixes. Continue until no material issues remain against this checklist:
+
+1. **Does it match the brief?** Compare the live result against every section of the design brief. Fix discrepancies.
+2. **Does it match the approved mock?** Compare screenshots against the mock fidelity inventory: hero silhouette, major motifs, imagery, nav/CTA, section sequence, density, color/materials, and second-fold substance. Missing major ingredients are P0 defects.
+3. **Does it pass the AI slop test?** If someone saw this and said "AI made this," would they believe it immediately? If yes, it needs more design intention.
+4. **Check against impeccable's DON'T guidelines.** Fix any anti-pattern violations.
+5. **Check every state.** Navigate through empty, error, loading, and edge case states. Each one should feel intentional, not like an afterthought.
+6. **Check responsive behavior.** The design should adapt compositionally, not merely shrink.
+7. **Check craft details.** Spacing consistency, optical alignment, type hierarchy, color contrast, image quality, icon coherence, interactive feedback, motion timing, and focus treatment.
+8. **Check performance basics.** No obviously oversized images, avoidable layout thrash, blocking animations, or heavy assets without a reason.
+
+The exit bar is not "it works." It is: the rendered result looks intentional at all checked viewports, all expected states are handled, no placeholders remain unless explicitly accepted, and the implementation quality would be defensible in a high-end studio review.
+
+## Step 7: 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?"
+
+Iterate based on feedback. Good design is rarely right on the first pass.

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

@@ -0,0 +1,213 @@
+> **Additional context needed**: what the interface is trying to accomplish.
+
+### Gather Assessments
+
+Launch two independent assessments. **Neither may see the other's output.** This isolation is what makes the combined score honest. Running both in one head silently anchors them to each other; do not shortcut it for cost, speed, or context-size reasons.
+
+Delegate each assessment to a separate sub-agent (Claude Code's `Agent` tool, Codex's subagent spawning, etc.). Each returns structured findings as text. Do NOT output findings to the user yet.
+
+Fall back to sequential in-head work only if the environment genuinely cannot spawn sub-agents.
+
+**Tab isolation**: When browser automation is available, each assessment MUST create its own new tab. Never reuse an existing tab, even if one is already open at the correct URL. This prevents the two assessments from interfering with each other's page state.
+
+#### Assessment A: LLM Design Review
+
+Read the relevant source files (HTML, CSS, JS/TS) and, if browser automation is available, visually inspect the live page. **Create a new tab** for this; do not reuse existing tabs. After navigation, label the tab by setting the document title:
+```javascript
+document.title = '[LLM] ' + document.title;
+```
+Think like a design director. Evaluate:
+
+**AI Slop Detection (CRITICAL)**: Does this look like every other AI-generated interface? Review against ALL **DON'T** guidelines from the parent impeccable skill (already loaded in this context). Check for AI color palette, gradient text, dark glows, glassmorphism, hero metric layouts, identical card grids, generic fonts, and all other tells. **The test**: If someone said "AI made this," would you believe them immediately?
+
+**Holistic Design Review**: visual hierarchy (eye flow, primary action clarity), information architecture (structure, grouping, cognitive load), emotional resonance (does it match brand and audience?), discoverability (are interactive elements obvious?), composition (balance, whitespace, rhythm), typography (hierarchy, readability, font choices), color (purposeful use, cohesion, accessibility), states & edge cases (empty, loading, error, success), microcopy (clarity, tone, helpfulness).
+
+**Cognitive Load** (consult [cognitive-load](cognitive-load.md)):
+- Run the 8-item cognitive load checklist. Report failure count: 0-1 = low (good), 2-3 = moderate, 4+ = critical.
+- Count visible options at each decision point. If >4, flag it.
+- Check for progressive disclosure: is complexity revealed only when needed?
+
+**Emotional Journey**:
+- What emotion does this interface evoke? Is that intentional?
+- **Peak-end rule**: Is the most intense moment positive? Does the experience end well?
+- **Emotional valleys**: Check for anxiety spikes at high-stakes moments (payment, delete, commit). Are there design interventions (progress indicators, reassurance copy, undo options)?
+
+**Nielsen's Heuristics** (consult [heuristics-scoring](heuristics-scoring.md)):
+Score each of the 10 heuristics 0-4. This scoring will be presented in the report.
+
+Return structured findings covering: AI slop verdict, heuristic scores, cognitive load assessment, what's working (2-3 items), priority issues (3-5 with what/why/fix), minor observations, and provocative questions.
+
+#### Assessment B: Automated Detection
+
+Run the bundled deterministic detector, which flags 27 specific patterns (AI slop tells + general design quality).
+
+**CLI scan**:
+```bash
+npx impeccable --json [--fast] [target]
+```
+
+- Pass HTML/JSX/TSX/Vue/Svelte files or directories as `[target]` (anything with markup). Do not pass CSS-only files.
+- For URLs, skip the CLI scan (it requires Puppeteer). Use browser visualization instead.
+- For large directories (200+ scannable files), use `--fast` (regex-only, skips jsdom)
+- For 500+ files, narrow scope or ask the user
+- Exit code 0 = clean, 2 = findings
+
+**Browser visualization**: **required** when browser automation tools are available AND the target is a viewable page. The `[Human]` overlay tab is the user-facing deliverable; the critique is incomplete without it. Skip only if the target is not a viewable page (CSS-only file, non-browser target).
+
+The overlay is a **visual aid for the user**. It highlights issues directly in their browser. Do NOT scroll through the page to screenshot overlays. Instead, read the console output to get the results programmatically.
+
+1. **Start the live detection server**:
+   ```bash
+   npx impeccable live &
+   ```
+   Note the port printed to stdout (auto-assigned). Use `--port=PORT` to fix it.
+2. **Create a new tab** and navigate to the page (use dev server URL for local files, or direct URL). Do not reuse existing tabs.
+3. **Label the tab** via `javascript_tool` so the user can distinguish it:
+   ```javascript
+   document.title = '[Human] ' + document.title;
+   ```
+4. **Scroll to top** to ensure the page is scrolled to the very top before injection
+5. **Inject** via `javascript_tool` (replace PORT with the port from step 1):
+   ```javascript
+   const s = document.createElement('script'); s.src = 'http://localhost:PORT/detect.js'; document.head.appendChild(s);
+   ```
+6. Wait 2-3 seconds for the detector to render overlays
+7. **Read results from console** using `read_console_messages` with pattern `impeccable`. The detector logs all findings with the `[impeccable]` prefix. Do NOT scroll through the page to take screenshots of the overlays.
+8. **Cleanup**: Stop the live server when done:
+   ```bash
+   npx impeccable live stop
+   ```
+
+For multi-view targets, inject on 3-5 representative pages. If injection fails, continue with CLI results only.
+
+Return: CLI findings (JSON), browser console findings (if applicable), and any false positives noted.
+
+### 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.
+
+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 browser was used): 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.
+
+#### 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: craft, shape, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live, components, research, images, teach, document, extract)
+
+#### 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 `PRODUCT.md and DESIGN.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.
+
+### Ask the User
+
+**After presenting findings**, use targeted questions based on what was actually found. Ask the user for clarification before proceeding. 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: craft, shape, critique, audit, polish, bolder, quieter, distill, harden, onboard, animate, colorize, typeset, layout, delight, overdrive, clarify, adapt, optimize, live, components, research, images, teach, document, extract
+- 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 `/monodesign 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 `/monodesign critique` after fixes to see your score improve.