From ddd23b1807c05f921c1f72780ef0e475f0d5d2bd Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Thu, 13 Aug 2026 21:13:30 +0000 Subject: [PATCH] Sync generated provider output --- .agents/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 20 +++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .claude/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 20 ++++++++++++++++- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .cursor/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .cursor/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .gemini/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .gemini/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .github/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .github/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .grok/skills/impeccable/reference/bolder.md | 2 +- .grok/skills/impeccable/reference/critique.md | 20 ++++++++++++++++- .grok/skills/impeccable/reference/distill.md | 2 +- .grok/skills/impeccable/reference/document.md | 2 +- .grok/skills/impeccable/reference/extract.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .grok/skills/impeccable/reference/quieter.md | 2 +- .hermes/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .hermes/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .kiro/skills/impeccable/reference/bolder.md | 2 +- .kiro/skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .kiro/skills/impeccable/reference/distill.md | 2 +- .kiro/skills/impeccable/reference/document.md | 2 +- .kiro/skills/impeccable/reference/extract.md | 2 +- .kiro/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .kiro/skills/impeccable/reference/quieter.md | 2 +- .../skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 20 ++++++++++++++++- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .pi/skills/impeccable/reference/bolder.md | 2 +- .pi/skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .pi/skills/impeccable/reference/distill.md | 2 +- .pi/skills/impeccable/reference/document.md | 2 +- .pi/skills/impeccable/reference/extract.md | 2 +- .pi/skills/impeccable/reference/init.md | 2 +- .pi/skills/impeccable/reference/overdrive.md | 2 +- .pi/skills/impeccable/reference/quieter.md | 2 +- .qoder/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .qoder/skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .qoder/skills/impeccable/reference/extract.md | 2 +- .qoder/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .qoder/skills/impeccable/reference/quieter.md | 2 +- .../skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .rovodev/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .../skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .../skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- .../skills/impeccable/reference/extract.md | 2 +- .trae-cn/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .../skills/impeccable/reference/quieter.md | 2 +- .trae/skills/impeccable/reference/bolder.md | 2 +- .trae/skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .trae/skills/impeccable/reference/distill.md | 2 +- .trae/skills/impeccable/reference/document.md | 2 +- .trae/skills/impeccable/reference/extract.md | 2 +- .trae/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .trae/skills/impeccable/reference/quieter.md | 2 +- .vibe/skills/impeccable/reference/bolder.md | 2 +- .vibe/skills/impeccable/reference/critique.md | 22 +++++++++++++++++-- .vibe/skills/impeccable/reference/distill.md | 2 +- .vibe/skills/impeccable/reference/document.md | 2 +- .vibe/skills/impeccable/reference/extract.md | 2 +- .vibe/skills/impeccable/reference/init.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- .vibe/skills/impeccable/reference/quieter.md | 2 +- plugin/skills/impeccable/reference/bolder.md | 2 +- .../skills/impeccable/reference/critique.md | 20 ++++++++++++++++- plugin/skills/impeccable/reference/distill.md | 2 +- .../skills/impeccable/reference/document.md | 2 +- plugin/skills/impeccable/reference/extract.md | 2 +- .../skills/impeccable/reference/overdrive.md | 2 +- plugin/skills/impeccable/reference/quieter.md | 2 +- 123 files changed, 421 insertions(+), 135 deletions(-) diff --git a/.agents/skills/impeccable/reference/bolder.md b/.agents/skills/impeccable/reference/bolder.md index 026c10a6a..0ea9bcc0e 100644 --- a/.agents/skills/impeccable/reference/bolder.md +++ b/.agents/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.agents/skills/impeccable/reference/critique.md b/.agents/skills/impeccable/reference/critique.md index 7f4450f44..82cae84ed 100644 --- a/.agents/skills/impeccable/reference/critique.md +++ b/.agents/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -192,6 +194,14 @@ Codex Run Notes are final-chat only. Do not include this section in the persiste - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -200,6 +210,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + Codex: exclude Run Notes from the temp body file; Run Notes are final-chat only because persistence, trend read, and temp cleanup happen after the snapshot write. 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: @@ -226,12 +238,16 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `$impeccable polish` with no priorities to inherit. + 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 use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. These answers will shape the action plan. +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. + 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. @@ -246,9 +262,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. -Codex final-question gate: The user-visible response must either include the targeted questions or explicitly say `Questions skipped: ` because the findings were straightforward. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions. +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.agents/skills/impeccable/reference/distill.md b/.agents/skills/impeccable/reference/distill.md index 9c8322669..13f6cd584 100644 --- a/.agents/skills/impeccable/reference/distill.md +++ b/.agents/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.agents/skills/impeccable/reference/document.md b/.agents/skills/impeccable/reference/document.md index c44ed24ba..83abb54b8 100644 --- a/.agents/skills/impeccable/reference/document.md +++ b/.agents/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.agents/skills/impeccable/reference/extract.md b/.agents/skills/impeccable/reference/extract.md index f8d863ce1..7e98bd046 100644 --- a/.agents/skills/impeccable/reference/extract.md +++ b/.agents/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.agents/skills/impeccable/reference/overdrive.md b/.agents/skills/impeccable/reference/overdrive.md index bbee3f48a..34dface28 100644 --- a/.agents/skills/impeccable/reference/overdrive.md +++ b/.agents/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.agents/skills/impeccable/reference/quieter.md b/.agents/skills/impeccable/reference/quieter.md index 50d110229..870ea8659 100644 --- a/.agents/skills/impeccable/reference/quieter.md +++ b/.agents/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. STOP and use Codex's structured user-input/question tool when available; if unavailable, ask directly in chat to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.claude/skills/impeccable/reference/bolder.md b/.claude/skills/impeccable/reference/bolder.md index a5c34cd3e..1cad2f1d1 100644 --- a/.claude/skills/impeccable/reference/bolder.md +++ b/.claude/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and STOP and call the AskUserQuestion tool to clarify. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and call the AskUserQuestion tool to clarify. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.claude/skills/impeccable/reference/critique.md b/.claude/skills/impeccable/reference/critique.md index 42c3f0d92..637e73fca 100644 --- a/.claude/skills/impeccable/reference/critique.md +++ b/.claude/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,12 +216,16 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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 in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. + 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. @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.claude/skills/impeccable/reference/distill.md b/.claude/skills/impeccable/reference/distill.md index 887d1bbb3..7b93f0fb7 100644 --- a/.claude/skills/impeccable/reference/distill.md +++ b/.claude/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.claude/skills/impeccable/reference/document.md b/.claude/skills/impeccable/reference/document.md index 073274850..033ff9b3e 100644 --- a/.claude/skills/impeccable/reference/document.md +++ b/.claude/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the AskUserQuestion tool to clarify. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. STOP and call the AskUserQuestion tool to clarify. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.claude/skills/impeccable/reference/extract.md b/.claude/skills/impeccable/reference/extract.md index 6783a970c..fb1cd199e 100644 --- a/.claude/skills/impeccable/reference/extract.md +++ b/.claude/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, STOP and call the AskUserQuestion tool to clarify. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. STOP and call the AskUserQuestion tool to clarify. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.claude/skills/impeccable/reference/overdrive.md b/.claude/skills/impeccable/reference/overdrive.md index 11efe7d27..764740e4e 100644 --- a/.claude/skills/impeccable/reference/overdrive.md +++ b/.claude/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **STOP and call the AskUserQuestion tool to clarify.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** STOP and call the AskUserQuestion tool to clarify. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.claude/skills/impeccable/reference/quieter.md b/.claude/skills/impeccable/reference/quieter.md index c20b38fb3..5c1331c25 100644 --- a/.claude/skills/impeccable/reference/quieter.md +++ b/.claude/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.cursor/skills/impeccable/reference/bolder.md b/.cursor/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.cursor/skills/impeccable/reference/bolder.md +++ b/.cursor/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.cursor/skills/impeccable/reference/critique.md b/.cursor/skills/impeccable/reference/critique.md index 1d609ba17..5f5026768 100644 --- a/.cursor/skills/impeccable/reference/critique.md +++ b/.cursor/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.cursor/skills/impeccable/reference/distill.md b/.cursor/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.cursor/skills/impeccable/reference/distill.md +++ b/.cursor/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.cursor/skills/impeccable/reference/document.md b/.cursor/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.cursor/skills/impeccable/reference/document.md +++ b/.cursor/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.cursor/skills/impeccable/reference/extract.md b/.cursor/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.cursor/skills/impeccable/reference/extract.md +++ b/.cursor/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.cursor/skills/impeccable/reference/init.md b/.cursor/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.cursor/skills/impeccable/reference/init.md +++ b/.cursor/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.cursor/skills/impeccable/reference/overdrive.md b/.cursor/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.cursor/skills/impeccable/reference/overdrive.md +++ b/.cursor/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.cursor/skills/impeccable/reference/quieter.md b/.cursor/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.cursor/skills/impeccable/reference/quieter.md +++ b/.cursor/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.gemini/skills/impeccable/reference/bolder.md b/.gemini/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.gemini/skills/impeccable/reference/bolder.md +++ b/.gemini/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.gemini/skills/impeccable/reference/critique.md b/.gemini/skills/impeccable/reference/critique.md index 168e4a9a4..a56b6dd6b 100644 --- a/.gemini/skills/impeccable/reference/critique.md +++ b/.gemini/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.gemini/skills/impeccable/reference/distill.md b/.gemini/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.gemini/skills/impeccable/reference/distill.md +++ b/.gemini/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.gemini/skills/impeccable/reference/document.md b/.gemini/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.gemini/skills/impeccable/reference/document.md +++ b/.gemini/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.gemini/skills/impeccable/reference/extract.md b/.gemini/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.gemini/skills/impeccable/reference/extract.md +++ b/.gemini/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.gemini/skills/impeccable/reference/init.md b/.gemini/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.gemini/skills/impeccable/reference/init.md +++ b/.gemini/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.gemini/skills/impeccable/reference/overdrive.md b/.gemini/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.gemini/skills/impeccable/reference/overdrive.md +++ b/.gemini/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.gemini/skills/impeccable/reference/quieter.md b/.gemini/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.gemini/skills/impeccable/reference/quieter.md +++ b/.gemini/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.github/skills/impeccable/reference/bolder.md b/.github/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.github/skills/impeccable/reference/bolder.md +++ b/.github/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.github/skills/impeccable/reference/critique.md b/.github/skills/impeccable/reference/critique.md index a4256e3ed..7038a321d 100644 --- a/.github/skills/impeccable/reference/critique.md +++ b/.github/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.github/skills/impeccable/reference/distill.md b/.github/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.github/skills/impeccable/reference/distill.md +++ b/.github/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.github/skills/impeccable/reference/document.md b/.github/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.github/skills/impeccable/reference/document.md +++ b/.github/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.github/skills/impeccable/reference/extract.md b/.github/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.github/skills/impeccable/reference/extract.md +++ b/.github/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.github/skills/impeccable/reference/init.md b/.github/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.github/skills/impeccable/reference/init.md +++ b/.github/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.github/skills/impeccable/reference/overdrive.md b/.github/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.github/skills/impeccable/reference/overdrive.md +++ b/.github/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.github/skills/impeccable/reference/quieter.md b/.github/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.github/skills/impeccable/reference/quieter.md +++ b/.github/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.grok/skills/impeccable/reference/bolder.md b/.grok/skills/impeccable/reference/bolder.md index a5c34cd3e..1cad2f1d1 100644 --- a/.grok/skills/impeccable/reference/bolder.md +++ b/.grok/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and STOP and call the AskUserQuestion tool to clarify. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and call the AskUserQuestion tool to clarify. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.grok/skills/impeccable/reference/critique.md b/.grok/skills/impeccable/reference/critique.md index 00cb210e7..4da7a7a72 100644 --- a/.grok/skills/impeccable/reference/critique.md +++ b/.grok/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,12 +216,16 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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 in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. + 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. @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.grok/skills/impeccable/reference/distill.md b/.grok/skills/impeccable/reference/distill.md index 887d1bbb3..7b93f0fb7 100644 --- a/.grok/skills/impeccable/reference/distill.md +++ b/.grok/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.grok/skills/impeccable/reference/document.md b/.grok/skills/impeccable/reference/document.md index 073274850..033ff9b3e 100644 --- a/.grok/skills/impeccable/reference/document.md +++ b/.grok/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the AskUserQuestion tool to clarify. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. STOP and call the AskUserQuestion tool to clarify. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.grok/skills/impeccable/reference/extract.md b/.grok/skills/impeccable/reference/extract.md index 6783a970c..fb1cd199e 100644 --- a/.grok/skills/impeccable/reference/extract.md +++ b/.grok/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, STOP and call the AskUserQuestion tool to clarify. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. STOP and call the AskUserQuestion tool to clarify. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.grok/skills/impeccable/reference/overdrive.md b/.grok/skills/impeccable/reference/overdrive.md index 11efe7d27..764740e4e 100644 --- a/.grok/skills/impeccable/reference/overdrive.md +++ b/.grok/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **STOP and call the AskUserQuestion tool to clarify.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** STOP and call the AskUserQuestion tool to clarify. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.grok/skills/impeccable/reference/quieter.md b/.grok/skills/impeccable/reference/quieter.md index c20b38fb3..5c1331c25 100644 --- a/.grok/skills/impeccable/reference/quieter.md +++ b/.grok/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.hermes/skills/impeccable/reference/bolder.md b/.hermes/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.hermes/skills/impeccable/reference/bolder.md +++ b/.hermes/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.hermes/skills/impeccable/reference/critique.md b/.hermes/skills/impeccable/reference/critique.md index e2ed526ed..a862ca951 100644 --- a/.hermes/skills/impeccable/reference/critique.md +++ b/.hermes/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.hermes/skills/impeccable/reference/distill.md b/.hermes/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.hermes/skills/impeccable/reference/distill.md +++ b/.hermes/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.hermes/skills/impeccable/reference/document.md b/.hermes/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.hermes/skills/impeccable/reference/document.md +++ b/.hermes/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.hermes/skills/impeccable/reference/extract.md b/.hermes/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.hermes/skills/impeccable/reference/extract.md +++ b/.hermes/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.hermes/skills/impeccable/reference/init.md b/.hermes/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.hermes/skills/impeccable/reference/init.md +++ b/.hermes/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.hermes/skills/impeccable/reference/overdrive.md b/.hermes/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.hermes/skills/impeccable/reference/overdrive.md +++ b/.hermes/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.hermes/skills/impeccable/reference/quieter.md b/.hermes/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.hermes/skills/impeccable/reference/quieter.md +++ b/.hermes/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.kiro/skills/impeccable/reference/bolder.md b/.kiro/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.kiro/skills/impeccable/reference/bolder.md +++ b/.kiro/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.kiro/skills/impeccable/reference/critique.md b/.kiro/skills/impeccable/reference/critique.md index 15c7d0052..1dfa1e2da 100644 --- a/.kiro/skills/impeccable/reference/critique.md +++ b/.kiro/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.kiro/skills/impeccable/reference/distill.md b/.kiro/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.kiro/skills/impeccable/reference/distill.md +++ b/.kiro/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.kiro/skills/impeccable/reference/document.md b/.kiro/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.kiro/skills/impeccable/reference/document.md +++ b/.kiro/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.kiro/skills/impeccable/reference/extract.md b/.kiro/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.kiro/skills/impeccable/reference/extract.md +++ b/.kiro/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.kiro/skills/impeccable/reference/init.md b/.kiro/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.kiro/skills/impeccable/reference/init.md +++ b/.kiro/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.kiro/skills/impeccable/reference/overdrive.md b/.kiro/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.kiro/skills/impeccable/reference/overdrive.md +++ b/.kiro/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.kiro/skills/impeccable/reference/quieter.md b/.kiro/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.kiro/skills/impeccable/reference/quieter.md +++ b/.kiro/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.opencode/skills/impeccable/reference/bolder.md b/.opencode/skills/impeccable/reference/bolder.md index 1055d6a9f..25fdcdb8a 100644 --- a/.opencode/skills/impeccable/reference/bolder.md +++ b/.opencode/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and STOP and call the `question` tool to clarify. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and call the `question` tool to clarify. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.opencode/skills/impeccable/reference/critique.md b/.opencode/skills/impeccable/reference/critique.md index 4cbf860a7..6f05e1a2d 100644 --- a/.opencode/skills/impeccable/reference/critique.md +++ b/.opencode/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,12 +216,16 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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 `question` tool to clarify. These answers will shape the action plan. +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. + 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. @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.opencode/skills/impeccable/reference/distill.md b/.opencode/skills/impeccable/reference/distill.md index 75c40ae46..96dfcd85f 100644 --- a/.opencode/skills/impeccable/reference/distill.md +++ b/.opencode/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and call the `question` tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the `question` tool to clarify. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.opencode/skills/impeccable/reference/document.md b/.opencode/skills/impeccable/reference/document.md index 57fcf4ca8..ae5e3de20 100644 --- a/.opencode/skills/impeccable/reference/document.md +++ b/.opencode/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the `question` tool to clarify. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. STOP and call the `question` tool to clarify. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.opencode/skills/impeccable/reference/extract.md b/.opencode/skills/impeccable/reference/extract.md index 54b8c2e65..a08541f16 100644 --- a/.opencode/skills/impeccable/reference/extract.md +++ b/.opencode/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, STOP and call the `question` tool to clarify. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. STOP and call the `question` tool to clarify. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.opencode/skills/impeccable/reference/overdrive.md b/.opencode/skills/impeccable/reference/overdrive.md index 82ce611e1..65cf924d4 100644 --- a/.opencode/skills/impeccable/reference/overdrive.md +++ b/.opencode/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **STOP and call the `question` tool to clarify.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** STOP and call the `question` tool to clarify. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.opencode/skills/impeccable/reference/quieter.md b/.opencode/skills/impeccable/reference/quieter.md index 7bc1dd548..ef4fb7f0a 100644 --- a/.opencode/skills/impeccable/reference/quieter.md +++ b/.opencode/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and call the `question` tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the `question` tool to clarify. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.pi/skills/impeccable/reference/bolder.md b/.pi/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.pi/skills/impeccable/reference/bolder.md +++ b/.pi/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.pi/skills/impeccable/reference/critique.md b/.pi/skills/impeccable/reference/critique.md index f24981c95..dcf4a98b0 100644 --- a/.pi/skills/impeccable/reference/critique.md +++ b/.pi/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.pi/skills/impeccable/reference/distill.md b/.pi/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.pi/skills/impeccable/reference/distill.md +++ b/.pi/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.pi/skills/impeccable/reference/document.md b/.pi/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.pi/skills/impeccable/reference/document.md +++ b/.pi/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.pi/skills/impeccable/reference/extract.md b/.pi/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.pi/skills/impeccable/reference/extract.md +++ b/.pi/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.pi/skills/impeccable/reference/init.md b/.pi/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.pi/skills/impeccable/reference/init.md +++ b/.pi/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.pi/skills/impeccable/reference/overdrive.md b/.pi/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.pi/skills/impeccable/reference/overdrive.md +++ b/.pi/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.pi/skills/impeccable/reference/quieter.md b/.pi/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.pi/skills/impeccable/reference/quieter.md +++ b/.pi/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.qoder/skills/impeccable/reference/bolder.md b/.qoder/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.qoder/skills/impeccable/reference/bolder.md +++ b/.qoder/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.qoder/skills/impeccable/reference/critique.md b/.qoder/skills/impeccable/reference/critique.md index 8ac0cb2ce..8faa84eb1 100644 --- a/.qoder/skills/impeccable/reference/critique.md +++ b/.qoder/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.qoder/skills/impeccable/reference/distill.md b/.qoder/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.qoder/skills/impeccable/reference/distill.md +++ b/.qoder/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.qoder/skills/impeccable/reference/document.md b/.qoder/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.qoder/skills/impeccable/reference/document.md +++ b/.qoder/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.qoder/skills/impeccable/reference/extract.md b/.qoder/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.qoder/skills/impeccable/reference/extract.md +++ b/.qoder/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.qoder/skills/impeccable/reference/init.md b/.qoder/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.qoder/skills/impeccable/reference/init.md +++ b/.qoder/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.qoder/skills/impeccable/reference/overdrive.md b/.qoder/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.qoder/skills/impeccable/reference/overdrive.md +++ b/.qoder/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.qoder/skills/impeccable/reference/quieter.md b/.qoder/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.qoder/skills/impeccable/reference/quieter.md +++ b/.qoder/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.rovodev/skills/impeccable/reference/bolder.md b/.rovodev/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.rovodev/skills/impeccable/reference/bolder.md +++ b/.rovodev/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.rovodev/skills/impeccable/reference/critique.md b/.rovodev/skills/impeccable/reference/critique.md index 4a8883e66..b544990c9 100644 --- a/.rovodev/skills/impeccable/reference/critique.md +++ b/.rovodev/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.rovodev/skills/impeccable/reference/distill.md b/.rovodev/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.rovodev/skills/impeccable/reference/distill.md +++ b/.rovodev/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.rovodev/skills/impeccable/reference/document.md b/.rovodev/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.rovodev/skills/impeccable/reference/document.md +++ b/.rovodev/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.rovodev/skills/impeccable/reference/extract.md b/.rovodev/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.rovodev/skills/impeccable/reference/extract.md +++ b/.rovodev/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.rovodev/skills/impeccable/reference/init.md b/.rovodev/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.rovodev/skills/impeccable/reference/init.md +++ b/.rovodev/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.rovodev/skills/impeccable/reference/overdrive.md b/.rovodev/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.rovodev/skills/impeccable/reference/overdrive.md +++ b/.rovodev/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.rovodev/skills/impeccable/reference/quieter.md b/.rovodev/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.rovodev/skills/impeccable/reference/quieter.md +++ b/.rovodev/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.trae-cn/skills/impeccable/reference/bolder.md b/.trae-cn/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.trae-cn/skills/impeccable/reference/bolder.md +++ b/.trae-cn/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.trae-cn/skills/impeccable/reference/critique.md b/.trae-cn/skills/impeccable/reference/critique.md index 4b2dbf270..52c17fc8e 100644 --- a/.trae-cn/skills/impeccable/reference/critique.md +++ b/.trae-cn/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.trae-cn/skills/impeccable/reference/distill.md b/.trae-cn/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.trae-cn/skills/impeccable/reference/distill.md +++ b/.trae-cn/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.trae-cn/skills/impeccable/reference/document.md b/.trae-cn/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.trae-cn/skills/impeccable/reference/document.md +++ b/.trae-cn/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.trae-cn/skills/impeccable/reference/extract.md b/.trae-cn/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.trae-cn/skills/impeccable/reference/extract.md +++ b/.trae-cn/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.trae-cn/skills/impeccable/reference/init.md b/.trae-cn/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.trae-cn/skills/impeccable/reference/init.md +++ b/.trae-cn/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.trae-cn/skills/impeccable/reference/overdrive.md b/.trae-cn/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.trae-cn/skills/impeccable/reference/overdrive.md +++ b/.trae-cn/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.trae-cn/skills/impeccable/reference/quieter.md b/.trae-cn/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.trae-cn/skills/impeccable/reference/quieter.md +++ b/.trae-cn/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.trae/skills/impeccable/reference/bolder.md b/.trae/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.trae/skills/impeccable/reference/bolder.md +++ b/.trae/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.trae/skills/impeccable/reference/critique.md b/.trae/skills/impeccable/reference/critique.md index 66dc6af33..75d5063f5 100644 --- a/.trae/skills/impeccable/reference/critique.md +++ b/.trae/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.trae/skills/impeccable/reference/distill.md b/.trae/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.trae/skills/impeccable/reference/distill.md +++ b/.trae/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.trae/skills/impeccable/reference/document.md b/.trae/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.trae/skills/impeccable/reference/document.md +++ b/.trae/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.trae/skills/impeccable/reference/extract.md b/.trae/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.trae/skills/impeccable/reference/extract.md +++ b/.trae/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.trae/skills/impeccable/reference/init.md b/.trae/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.trae/skills/impeccable/reference/init.md +++ b/.trae/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.trae/skills/impeccable/reference/overdrive.md b/.trae/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.trae/skills/impeccable/reference/overdrive.md +++ b/.trae/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.trae/skills/impeccable/reference/quieter.md b/.trae/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.trae/skills/impeccable/reference/quieter.md +++ b/.trae/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/.vibe/skills/impeccable/reference/bolder.md b/.vibe/skills/impeccable/reference/bolder.md index c5446cfe0..78ceb8dfd 100644 --- a/.vibe/skills/impeccable/reference/bolder.md +++ b/.vibe/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and ask the user directly to clarify what you cannot infer. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. Ask the user directly to clarify what you cannot infer. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/.vibe/skills/impeccable/reference/critique.md b/.vibe/skills/impeccable/reference/critique.md index 7446db250..0c65a923c 100644 --- a/.vibe/skills/impeccable/reference/critique.md +++ b/.vibe/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,11 +216,15 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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. ask the user directly to clarify what you cannot infer. These answers will shape the action plan. +**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. + +Ask in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. Ask questions along these lines (adapt to the specific findings; do NOT ask generic questions): @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/.vibe/skills/impeccable/reference/distill.md b/.vibe/skills/impeccable/reference/distill.md index 9dcac4676..6eb4f19b3 100644 --- a/.vibe/skills/impeccable/reference/distill.md +++ b/.vibe/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/.vibe/skills/impeccable/reference/document.md b/.vibe/skills/impeccable/reference/document.md index 21d7a3e9d..9da0bc743 100644 --- a/.vibe/skills/impeccable/reference/document.md +++ b/.vibe/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and ask the user directly to clarify what you cannot infer. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. Ask the user directly to clarify what you cannot infer. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/.vibe/skills/impeccable/reference/extract.md b/.vibe/skills/impeccable/reference/extract.md index a5d652ee2..64ccab40b 100644 --- a/.vibe/skills/impeccable/reference/extract.md +++ b/.vibe/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, ask the user directly to clarify what you cannot infer. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. Ask the user directly to clarify what you cannot infer. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/.vibe/skills/impeccable/reference/init.md b/.vibe/skills/impeccable/reference/init.md index 22c32a71b..9951874ed 100644 --- a/.vibe/skills/impeccable/reference/init.md +++ b/.vibe/skills/impeccable/reference/init.md @@ -24,7 +24,7 @@ Form a platform hypothesis: `web`, `ios`, `android`, or `adaptive` (one product ## Step 3: Interview for product truth -ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. +Ask the user directly to clarify what you cannot infer. Ask only about material gaps the repository and original request do not answer with strong evidence. Use the structured question tool when available; otherwise ask and wait. Keep rounds to at most three focused questions and require one real answer or approval round before writing a new PRODUCT.md. Confirm inferences. diff --git a/.vibe/skills/impeccable/reference/overdrive.md b/.vibe/skills/impeccable/reference/overdrive.md index e50bfbc85..76953e24e 100644 --- a/.vibe/skills/impeccable/reference/overdrive.md +++ b/.vibe/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **ask the user directly to clarify what you cannot infer.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** Ask the user directly to clarify what you cannot infer. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/.vibe/skills/impeccable/reference/quieter.md b/.vibe/skills/impeccable/reference/quieter.md index bb163e40f..a04100bf2 100644 --- a/.vibe/skills/impeccable/reference/quieter.md +++ b/.vibe/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, ask the user directly to clarify what you cannot infer. +If any of these are unclear from the codebase, do not guess. Ask the user directly to clarify what you cannot infer. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness. diff --git a/plugin/skills/impeccable/reference/bolder.md b/plugin/skills/impeccable/reference/bolder.md index a5c34cd3e..1cad2f1d1 100644 --- a/plugin/skills/impeccable/reference/bolder.md +++ b/plugin/skills/impeccable/reference/bolder.md @@ -6,7 +6,7 @@ An open direction round owns the word first: "bolder" said while a direction dec ## Scope is sovereign -"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, stop and STOP and call the AskUserQuestion tool to clarify. before expanding it, naming the exact addition and the job it would do. +"Everything else stays" is a literal instruction. Touch only the named target. Do not restyle its neighbors, do not migrate the page to a new idea, do not add colors, fonts, radii, shadows, or system primitives the surface does not already own. If the existing system genuinely cannot express the direction, do not expand it on your own. STOP and call the AskUserQuestion tool to clarify. Name the exact addition and the job it would do. ## Why it reads flat diff --git a/plugin/skills/impeccable/reference/critique.md b/plugin/skills/impeccable/reference/critique.md index 42c3f0d92..637e73fca 100644 --- a/plugin/skills/impeccable/reference/critique.md +++ b/plugin/skills/impeccable/reference/critique.md @@ -12,6 +12,8 @@ Resolve one stable target, run two independent assessments, synthesize a design - 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. +- The question is the LAST thing in the response. Write the entire report out first, then ask; nothing follows the question. Prose emitted after a structured question is withheld until the user answers it, so a report written after the question reads as if the critique never ran. +- A run that ends with neither the targeted questions nor a literal `Questions skipped: ` line is an incomplete run. The report is not the finish; the close is. ### Setup @@ -172,6 +174,14 @@ Provocative questions that might unlock better solutions: - Prioritize ruthlessly. If everything is important, nothing is. - Don't soften criticism. Developers need honest feedback to ship great design. +### Deliver the Report + +Write the full report into the chat response now, before any persistence work. This is the deliverable; everything below it is bookkeeping. + +Do this first because the alternative is the most common way this command fails: the report gets composed once, straight into the persistence heredoc, and the run ends with a perfect archive nobody has read. Composing it into a file is not delivering it. If the report exists only in `.impeccable/critique/`, the run produced nothing. + +Persistence is not the end of the run. After it, the response continues with the trend line and the close. + ### 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. @@ -180,6 +190,8 @@ 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, design-specificity verdict, priority issues, persona red flags, minor observations, and questions), but stop before the "Ask the User" / "Recommended Actions" sections that come later. + This is a copy of the report you already delivered above, for later commands to read. It is not delivery. If you find yourself composing the report for the first time inside this heredoc, you have skipped Deliver the Report; go back and send it. + 2. **Pass the structured metadata** through `IMPECCABLE_CRITIQUE_META` (JSON), then run the write command: ```bash IMPECCABLE_CRITIQUE_META='{"target":"","total_score":,"max_score":,"na_heuristics":"","p0_count":,"p1_count":}' \ @@ -204,12 +216,16 @@ Skip this step if the Setup slug was null (vague or root-level target). 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." +6. **Close the run.** Go to Ask the User below and emit the questions, or the `Questions skipped: ` line when the count allows it. The run is not complete until you do. Persistence is bookkeeping and cleanup is not an ending; stopping here leaves the user with a report and no way forward, and leaves `/impeccable polish` with no priorities to inherit. + 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 in the same message that carries the report, with the report written out first and the question last. Do not split the two across turns: a turn that ends on the report is a turn that ends, and the questions never arrive. Order within the message is what matters, because prose emitted after a structured question is withheld until the user answers. + 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. @@ -224,7 +240,9 @@ Ask questions along these lines (adapt to the specific findings; do NOT ask gene - 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. +- Skipping is allowed only when the report listed **fewer than 3 Priority Issues**. Count them; do not judge the findings "straightforward" by feel. At 3 or more, the questions are required. + +**Final-question gate.** The user-visible response must either include the targeted questions or carry the literal line `Questions skipped: ` naming the count that permitted the skip. Each question must include 2-3 concrete answer options tied to the actual critique findings. Do not end with only open-ended questions, and do not end with neither: stopping after the report, having asked nothing and printed no skip line, is the most common way this command fails. ### Recommended Actions diff --git a/plugin/skills/impeccable/reference/distill.md b/plugin/skills/impeccable/reference/distill.md index 887d1bbb3..7b93f0fb7 100644 --- a/plugin/skills/impeccable/reference/distill.md +++ b/plugin/skills/impeccable/reference/distill.md @@ -21,7 +21,7 @@ Analyze what makes the design feel complex or cluttered: - What can be removed, hidden, or combined? - What's the 20% that delivers 80% of value? -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: Simplicity is not about removing features. It's about removing obstacles between users and their goals. Every element should justify its existence. diff --git a/plugin/skills/impeccable/reference/document.md b/plugin/skills/impeccable/reference/document.md index 073274850..033ff9b3e 100644 --- a/plugin/skills/impeccable/reference/document.md +++ b/plugin/skills/impeccable/reference/document.md @@ -68,7 +68,7 @@ Omit irrelevant sections rather than filling them with invented rules. Put respo - An existing `DESIGN.md` is stale (the design has drifted). - Before a large redesign, to capture the current state as a reference. -If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file and STOP and call the AskUserQuestion tool to clarify. whether to refresh, overwrite, or merge. +If a `DESIGN.md` already exists, **do not silently overwrite it**. Show the user the existing file first. STOP and call the AskUserQuestion tool to clarify. The choice is refresh, overwrite, or merge. ## Two paths diff --git a/plugin/skills/impeccable/reference/extract.md b/plugin/skills/impeccable/reference/extract.md index 6783a970c..fb1cd199e 100644 --- a/plugin/skills/impeccable/reference/extract.md +++ b/plugin/skills/impeccable/reference/extract.md @@ -6,7 +6,7 @@ Identify reusable patterns, components, and design tokens, then extract and cons Find the design system, component library, or shared UI directory. Understand its structure: component organization, naming conventions, design token structure, import/export conventions. -**CRITICAL**: If no design system exists, STOP and call the AskUserQuestion tool to clarify. before creating one. Understand the preferred location and structure first. +**CRITICAL**: If no design system exists, do not create one yet. STOP and call the AskUserQuestion tool to clarify. Understand the preferred location and structure first. ## Step 2: Identify Patterns diff --git a/plugin/skills/impeccable/reference/overdrive.md b/plugin/skills/impeccable/reference/overdrive.md index 11efe7d27..764740e4e 100644 --- a/plugin/skills/impeccable/reference/overdrive.md +++ b/plugin/skills/impeccable/reference/overdrive.md @@ -14,7 +14,7 @@ Push an interface past conventional limits. This isn't just about visual effects This command has the highest potential to misfire. Do NOT jump straight into implementation. You MUST: 1. **Think through 2-3 different directions**: consider different techniques, levels of ambition, and aesthetic approaches. For each direction, briefly describe what the result would look and feel like. -2. **STOP and call the AskUserQuestion tool to clarify.** to present these directions and get the user's pick before writing any code. Explain trade-offs (browser support, performance cost, complexity). +2. **Get the user's pick before writing any code.** STOP and call the AskUserQuestion tool to clarify. Carry each direction's description and its trade-offs (browser support, performance cost, complexity) inside the option itself, so the user is choosing between things they can read. A structured question blocks the message it rides in until the user answers, so directions written alongside the question stay invisible while the user is being asked to choose between them. 3. Only proceed with the direction the user confirms. Skipping this step risks building something embarrassing that needs to be thrown away. diff --git a/plugin/skills/impeccable/reference/quieter.md b/plugin/skills/impeccable/reference/quieter.md index c20b38fb3..5c1331c25 100644 --- a/plugin/skills/impeccable/reference/quieter.md +++ b/plugin/skills/impeccable/reference/quieter.md @@ -28,7 +28,7 @@ Analyze what makes the design feel too intense: - What's working? (Don't throw away good ideas) - What's the core message? (Preserve what matters) -If any of these are unclear from the codebase, STOP and call the AskUserQuestion tool to clarify. +If any of these are unclear from the codebase, do not guess. STOP and call the AskUserQuestion tool to clarify. **CRITICAL**: "Quieter" doesn't mean boring or generic. It means refined and easier on the eyes. Think luxury, not laziness.