From 5a7c2bc6387b8c681871fe4c2ba3353f00a34213 Mon Sep 17 00:00:00 2001
From: Garry Tan <garrytan@gmail.com>
Date: Thu, 26 Mar 2026 22:12:57 -0600
Subject: [PATCH] feat: /plan-design-review visual mockup integration

Add {{DESIGN_SETUP}} to pre-review audit and "show me what 10/10
looks like" mockup generation to the 0-10 rating method. When a
design dimension rates below 7/10, the review can generate a mockup
showing the improved version. Falls back to text descriptions if
the design binary isn't available.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 plan-design-review/SKILL.md      | 41 ++++++++++++++++++++++++++++++++
 plan-design-review/SKILL.md.tmpl | 17 +++++++++++++
 2 files changed, 58 insertions(+)

diff --git a/plan-design-review/SKILL.md b/plan-design-review/SKILL.md
index 3ff7d9f8..f3617073 100644
--- a/plan-design-review/SKILL.md
+++ b/plan-design-review/SKILL.md
@@ -404,6 +404,32 @@ Analyze the plan. If it involves NONE of: new UI screens/pages, changes to exist
 
 Report findings before proceeding to Step 0.
 
+## DESIGN SETUP (run this check BEFORE any design mockup command)
+
+```bash
+_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
+D=""
+[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/design/dist/design" ] && D="$_ROOT/.claude/skills/gstack/design/dist/design"
+[ -z "$D" ] && D=~/.claude/skills/gstack/design/dist/design
+if [ -x "$D" ]; then
+  echo "DESIGN_READY: $D"
+else
+  echo "DESIGN_NOT_AVAILABLE"
+fi
+```
+
+If `DESIGN_NOT_AVAILABLE`: skip visual mockup generation and fall back to the
+existing HTML wireframe approach (`DESIGN_SKETCH`). Design mockups are a
+progressive enhancement, not a hard requirement.
+
+If `DESIGN_READY`: the design binary is available for visual mockup generation.
+Commands:
+- `$D generate --brief "..." --output /path.png` — generate a single mockup
+- `$D variants --brief "..." --count 3 --output-dir /path/` — generate N style variants
+- `$D compare --images "a.png,b.png,c.png" --output /path/board.html` — comparison board
+- `$D check --image /path.png --brief "..."` — vision quality gate
+- `$D iterate --session /path/session.json --feedback "..." --output /path.png` — iterate
+
 ## Step 0: Design Scope Assessment
 
 ### 0A. Initial Design Rating
@@ -546,6 +572,21 @@ Pattern:
 
 Re-run loop: invoke /plan-design-review again → re-rate → sections at 8+ get a quick pass, sections below 8 get full treatment.
 
+### "Show me what 10/10 looks like" (requires design binary)
+
+If `DESIGN_READY` was printed during setup AND a dimension rates below 7/10,
+offer to generate a visual mockup showing what the improved version would look like:
+
+```bash
+$D generate --brief "<description of what 10/10 looks like for this dimension>" --output /tmp/gstack-ideal-<dimension>.png
+```
+
+Show the mockup to the user via the Read tool. This makes the gap between
+"what the plan describes" and "what it should look like" visceral, not abstract.
+
+If the design binary is not available, skip this and continue with text-based
+descriptions of what 10/10 looks like.
+
 ## Review Sections (7 passes, after scope is agreed)
 
 ### Pass 1: Information Architecture
diff --git a/plan-design-review/SKILL.md.tmpl b/plan-design-review/SKILL.md.tmpl
index 00bbed28..30da1841 100644
--- a/plan-design-review/SKILL.md.tmpl
+++ b/plan-design-review/SKILL.md.tmpl
@@ -108,6 +108,8 @@ Analyze the plan. If it involves NONE of: new UI screens/pages, changes to exist
 
 Report findings before proceeding to Step 0.
 
+{{DESIGN_SETUP}}
+
 ## Step 0: Design Scope Assessment
 
 ### 0A. Initial Design Rating
@@ -145,6 +147,21 @@ Pattern:
 
 Re-run loop: invoke /plan-design-review again → re-rate → sections at 8+ get a quick pass, sections below 8 get full treatment.
 
+### "Show me what 10/10 looks like" (requires design binary)
+
+If `DESIGN_READY` was printed during setup AND a dimension rates below 7/10,
+offer to generate a visual mockup showing what the improved version would look like:
+
+```bash
+$D generate --brief "<description of what 10/10 looks like for this dimension>" --output /tmp/gstack-ideal-<dimension>.png
+```
+
+Show the mockup to the user via the Read tool. This makes the gap between
+"what the plan describes" and "what it should look like" visceral, not abstract.
+
+If the design binary is not available, skip this and continue with text-based
+descriptions of what 10/10 looks like.
+
 ## Review Sections (7 passes, after scope is agreed)
 
 ### Pass 1: Information Architecture