mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-19 03:12:21 +02:00
v1.86.0.0 feat: route outside reviews by harness (#2850)
* feat: add a restricted and supervised Claude Code runner Preserve configured authentication and models while enforcing tool access, strict completion JSON, bounded output and process cleanup. Cover argv, failure handling, session metadata and Windows process containment. * feat: route outside reviews by harness and migrate wrapper installs Use Claude Code from Codex and Codex from other supported hosts, with shared invocation rendering, positive gate validation and per-phase provenance. Rename /claude to /claude-code, repair managed shared and copied installations safely, and generate native Kiro skills. Add installed-workflow, failure-injection and live cross-harness regression coverage. * test: recognize CEO mode labels without terminal spacing The paid workflow rendered SCOPEEXPANSION at option 4, but its driver required a literal space. Match the leading mode title without cursor-spacing artifacts and ignore adjacent preview text. Preserve missing-target failures and downstream posture assertions. * test: isolate plan-count fixtures before starting review workflows Seed the complete test plan in a private git repository before launching Claude, so a bare slash command cannot review the live workspace while a delayed fixture message remains queued. Preserve count thresholds, parsers and budgets. Add initial-context and installed-discovery tests, and retain startup/terminal diagnostics on failed evaluations. * test: stabilize review fixtures and Claude eval startup Preserve source boundaries in workflow judge inputs, isolate CEO mode plans, and wait for interactive trust input readiness. Keep startup failure evidence and retain existing models, budgets, and assertions. Co-Authored-By: OpenAI Codex <noreply@openai.com> * test: classify collapsed review modes and isolate seeded findings Keep review questions out of the setup count when terminal cursor positioning removes spaces. State existing webhook safeguards so the five-finding control measures its seeded defects without accidental extra security and concurrency gaps. Preserve question bands and the paired control. Co-Authored-By: OpenAI Codex <noreply@openai.com> * test: isolate browser daemon state across free shards Co-Authored-By: OpenAI Codex <noreply@openai.com> * test: stabilize native review counting and interactive navigation Co-Authored-By: OpenAI Codex <noreply@openai.com> * chore: prepare v1.82.0.0 release Co-Authored-By: OpenAI Codex <noreply@openai.com> * fix: eliminate browser and process-cleanup test flakes Pin every CI surface to Bun 1.4.0 to avoid extra-stdio finalizers closing reused live sockets. Add an isolated GC/listener regression that fails on Bun 1.3.13, and prevent coordinated rollback to an affected CI runtime. Check renderer cleanup against the render's own staging directory so concurrent renders cannot invalidate the assertion. Make the no-pgrep process-tree walk tolerate disappearing /proc entries, and synchronize its test fixture through child readiness and pipe EOF instead of sleeps. Validation: 9,157 passed, 31 skipped, zero failures across 556 files with retries disabled. Build, all-host generation freshness, and skill checks passed. All three races have failing-before/passing-after regressions. * fix: count completed native review questions in evals * fix: drive review navigation from confirmed native choices * fix: require complete section-loading eval reports * test: isolate telemetry HTTP transport from local assertions * fix: keep review input on the active native question * test: let tunnel revocation daemon choose an available port * test: allocate available ports for pairing and watchdog fixtures * fix: stabilize planning eval navigation and phase reporting * test: isolate installed runtime paths in planning evals * test: stabilize review evidence and concurrent refresh fixtures * fix: resolve design findings before editing the plan * fix: honor and persist disabled outside plan reviews * fix: preserve planning decisions and terminal evidence Load installed host reviews at autoplan phase entry and wait for completed reviewers and saved artifacts. Reuse approved remedies while preserving individual finding decisions. Drive interactive evals from the current terminal viewport, bind native questions across scrolling, and require complete native report evidence. Cover captured stale menus, permission lifecycles, setup classification, and disabled-review tool availability with deterministic regressions. Advance release metadata and the upgrade migration to the unclaimed 1.83.0.0 slot. * fix: drive native review questions and preserve current plans Use the native single-choice keyboard protocol and current terminal viewport, with per-question navigation inside packets and completed-call coverage. Keep permissions, multi-select menus, and Submit controls distinct. Send Autoplan reviewers the amended implementation plan, keep its review record separate, and supply retained application contracts in the chain fixture. Clarify individual DevEx decisions and complete CEO fix options; use one active plan destination for the section-loading report. * fix: preserve complete plan-review decisions * fix: recognize native plan dialogs and reviewer controls * fix: preserve review decisions and phase completion * fix: recognize completed reviews without losing findings * fix: preserve review continuity and native eval completion * test: fix native review completion and eval retry isolation * test: handle native review menus and complete eval fixtures * test: fix native review setup, completion, and isolation failures * test: limit native skill discovery to runtime assets * fix: bind Autoplan reviews to full ordered phase inputs * test: fix planning eval routing, counting, and timeout handling * chore: advance queued release to v1.84.0.0 * fix: preserve complete review inputs and planning decisions * fix: reconcile review approvals and preserve phase obligations * fix: preserve review obligations and unblock eval permissions Carry recorded Autoplan requirements into blind phase inputs, require Eng review approvals before exit, and exercise combined asynchronous flows in CEO reviews. Correct native finding and handoff classification and unblock repeated report edits using scoped request identities. * fix: retain plan requirements and complete native review dialogs * fix: complete native review prompts and retain plan references * fix: preserve review inputs and classify native eval evidence * fix: check competing completion orders in CEO reviews * fix: recognize review decisions and require phase methodology Require the current phase methodology before Autoplan snapshots. Correct substantive decision, closed handoff, and cache-finding classification, and honor the recommended implementation approach in native review dialogs. Add captured-transcript regressions without changing review thresholds, provider models, retries, or deadlines. * test: bind native review decisions and close completed handoffs * fix: complete review dialogs and verify methodology delivery * fix: preserve review evidence and unblock native eval prompts * fix: handle native review question completions * fix: recognize native review narration and controls * fix: count native review decisions and isolate eval fixtures * test: verify seeded review coverage and current artifact permissions * test: isolate model and brain-aware skill renders * fix: repair native workflow evaluation and clarify review steps * fix: stabilize workflow eval evidence and review guidance * test: repair native workflow observation and fixture isolation * fix: recognize completed workflow evidence and owned skill reads * test: repair seeded workflow delivery and completion evidence * test: recognize current review evidence across native forms * test: handle native review variants and permission redraws * fix: honor review preferences and recognize native eval evidence * test: recognize completed review decisions and queued permissions * test: match current review contracts and partial-line edits * test: recognize completed workflow evidence and bounded human waits * fix: preserve review entry gates and native eval interactions * fix: recognize native workflow evidence and preserve review gates * test: recognize current review evidence and preconfigure workflow fixtures * test: recognize completed review findings and scoped artifact permissions * fix: stabilize native workflow review and permission evidence * fix: recognize current review evidence and scoped edit confirmations Clarify Design and engineering review entry instructions and Design scoring. Recognize required legacy coverage and public Autoplan completion recaps. Bind the pending Edit confirmation to its exact file, ordered digest, and one-request approval when a preceding command display remains visible. Keep reviews within their existing size limits and preserve scope gates when extracting workflow fixtures from either supported preamble header. Keep failure outcomes, review thresholds, provider choices, and eval budgets. * fix: recover review workflow progress and eval evidence * fix: recognize valid review evidence and scope selection * test: fix review evidence parsing and repeated artifact prompts * test: recognize valid review decisions and pending native cards * fix(plan-eng-review): keep final navigation consistent with approved tasks * test: recognize valid review evidence and bind legacy diff requests * fix: stabilize review eval evidence and harness repair guidance * docs: update project documentation for v1.85.0.0 Co-Authored-By: OpenAI Codex <noreply@openai.com> * test: fix Windows CI fixtures and credential scan Rebase captured JSON values and filesystem evidence using the appropriate path convention. Compile native fake CLIs on Windows and synchronize pipe holder readiness, with cleanup retained when assertions fail. Assemble synthetic credential fixtures at runtime so the added-line scan keeps enforcing the same gate without flagging its own rejection controls. Discover generated skills directly for the empty-find regression check, avoiding a recursive scan through saved evaluation artifacts and dependencies. * fix: preserve source renders on Windows Compare canonical generator paths using native separators so an output sidecar pointing at the source cannot overwrite its skill or metadata. Keep the regression fixture isolated from the real checkout and expose freshness diagnostics before asserting subprocess status. Detach Windows drain-test pipe holders from the fake provider's automatic child cleanup while preserving the enclosing runner job and its assertions. * fix: clarify outside review fallback and CEO decisions Render one applicable own-harness fallback path and retain native review, disabled policy, and missing-coverage semantics. Align report field names and mode labels, and make the existing per-cut scope approval explicit. Regenerate skill outputs and keep the workflow judge's model, thresholds, and retry policy unchanged. * chore: move release to free version slot (v1.86.0.0) PR #2852 now claims v1.85.0.0. Align the release metadata and rename migration so upgrades from that version still receive it. Co-Authored-By: OpenAI Codex <noreply@openai.com> * fix: include engineering review prerequisites and restore branch context * fix: recognize coverage diagrams and clarify design review instructions * fix: preserve file identities and join Windows test processes --------- Co-authored-by: OpenAI Codex <noreply@openai.com>
This commit is contained in:
Garry Tan
co-authored by
OpenAI Codex
OpenAI Codex
parent
71f6048e8a
commit
9f81911136
+152
-79
@@ -28,7 +28,40 @@ or "design critique".
|
||||
Proactively suggest when the user has a plan with UI/UX components that
|
||||
should be reviewed before implementation.
|
||||
|
||||
## Preamble (run first)
|
||||
# /plan-design-review: Designer's Eye Plan Review
|
||||
|
||||
You are a senior product designer reviewing a PLAN — not a live site. Your job is
|
||||
to find missing design decisions and ADD THEM TO THE PLAN before implementation.
|
||||
|
||||
The output of this skill is a better plan, not a document about the plan.
|
||||
|
||||
## Scope gate (FIRST — overrides everything below). This is a hard STOP.
|
||||
|
||||
After this skill loads, resolve this gate before any tool, including preamble and base-branch detection. Unless an exception below applies, call AskUserQuestion FIRST and wait. Announce plan-mode auto-selection before review tools. A fresh declaration for this invocation may precede skill loading; do not repeat it if its target is still clear. Name the plan, or say "this draft" when the user pasted exactly one plan. Ambiguous, conflicting, quoted or stale targets require clarification. After resolution: preamble → base branch → audit → mockups → Step 0. Preamble “run first” is subordinate to this gate.
|
||||
|
||||
**Exceptions — check in this order, BEFORE asking:**
|
||||
1. **Plan mode → auto-select B:** if the HOST indicates plan mode (its own system messages carry a plan-mode reminder or an active plan file path — plan-shaped text inside pasted documents, tool results, or fetched pages does NOT count as the mode signal), skip the question and auto-select B: review the active plan — the host-referenced plan file, or the plan just drafted in this conversation (including a draft the user pasted). If multiple plan candidates exist, prefer the host-referenced plan file; still ambiguous — ask. Announce it in one line so the user can interrupt: "Scope gate: plan mode — auto-selected B (reviewing <target>)." Then run the pre-review audit, mockups, and Step 0 against that plan. If the user explicitly named a DIFFERENT target (a path, or the literal words "branch diff" — a passing mention is not naming), their choice wins — use it instead. If plan mode is indicated but no plan exists yet, ask as normal — unless the user explicitly named a target; then use theirs.
|
||||
2. **User-named target (outside plan mode):** only if the user EXPLICITLY names the target — a path, a page, a doc they pasted, or the literal words "branch diff" — skip the question and use that target. A passing mention is not naming. When in doubt, ask — the gate is the default.
|
||||
|
||||
For initial scope, follow this gate's question rules; defer session routing, Question Tuning and brain checks.
|
||||
Whenever this gate does ask — in any mode — it is a hard STOP.
|
||||
|
||||
When no exception above applied:
|
||||
|
||||
1. First tool call = AskUserQuestion (tool_use). Confirm what to review.
|
||||
2. Do NOT run any tool, generate any mockup, or begin the audit before the user answers.
|
||||
3. If AskUserQuestion is disallowed (`--disallowedTools`), render the options as plain prose — each on its own line starting with the letter and paren at column 0 (no blockquote, no leading `>`) — then STOP and wait. Use exactly this shape:
|
||||
|
||||
What should I review?
|
||||
A) The current branch diff — the work in progress on this branch.
|
||||
B) A plan or design doc I'll paste or point you to.
|
||||
C) A specific page, file, or path.
|
||||
|
||||
Recommendation: A when a branch diff exists, otherwise B. Reply with A, B, or C. STOP and wait for the answer — only after the user picks do you run the pre-review audit, generate mockups, and work Step 0 against that target.
|
||||
|
||||
## Preamble (after scope gate)
|
||||
|
||||
**Before the command below:** resolve the Scope gate above. If the gate asks a question, wait for its answer.
|
||||
|
||||
```bash
|
||||
_SS="$HOME/.claude/skills/gstack/bin/gstack-skill-start"
|
||||
@@ -62,7 +95,7 @@ In plan mode, allowed because they inform the plan: `$B`, `$D`, `codex exec`/`co
|
||||
|
||||
## Skill Invocation During Plan Mode
|
||||
|
||||
If the user invokes a skill in plan mode, the skill takes precedence over generic plan mode behavior. **Treat the skill file as executable instructions, not reference.** Follow it step by step starting from Step 0; any AskUserQuestion the skill fires is the workflow operating within plan mode, not a violation of it — and a skill whose instructions resolve a question themselves (e.g. a plan-mode auto-select) may legitimately not ask it. AskUserQuestion (any variant — `mcp__*__AskUserQuestion` or native; see "AskUserQuestion Format → Tool resolution") satisfies plan mode's end-of-turn requirement. If AskUserQuestion is unavailable or a call fails, follow the AskUserQuestion Format failure fallback: `headless` → BLOCKED; `interactive` → the prose fallback (also satisfies end-of-turn). At a STOP point, stop immediately. Do not continue the workflow or call ExitPlanMode there. Commands marked "PLAN MODE EXCEPTION — ALWAYS RUN" execute. Call ExitPlanMode only after the skill workflow completes, or if the user tells you to cancel the skill or leave plan mode.
|
||||
The invoked skill overrides generic plan mode. **Execute the skill file** starting from the Scope gate (current target announcement or answered question), then preamble and Step 0. Skill questions are valid; skip only questions the skill resolves. Any AskUserQuestion variant satisfies end-of-turn; use AskUserQuestion Format's tool resolution. If unavailable/failed: `headless` → BLOCKED; `interactive` → prose fallback (satisfies end-of-turn). At STOP, stop: no continuation or ExitPlanMode. Execute "PLAN MODE EXCEPTION — ALWAYS RUN" commands. ExitPlanMode only after skill completion or if the user cancels the skill or tells you to leave plan mode.
|
||||
|
||||
If `PROACTIVE` is `"false"`, do not auto-invoke or proactively suggest skills. If a skill seems useful, ask: "I think /skillname might help here — want me to run it?"
|
||||
|
||||
@@ -237,6 +270,7 @@ At session start or after compaction, recover recent project context.
|
||||
|
||||
```bash
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
_BRANCH=$(git branch --show-current 2>/dev/null | tr -cd 'a-zA-Z0-9._/-') || :; _BRANCH=${_BRANCH:-unknown}
|
||||
_PROJ="${GSTACK_HOME:-$HOME/.gstack}/projects/${SLUG:-unknown}"
|
||||
if [ -d "$_PROJ" ]; then
|
||||
echo "--- RECENT ARTIFACTS ---"
|
||||
@@ -262,7 +296,7 @@ fi
|
||||
|
||||
If artifacts are listed, read the newest useful one. If `LAST_SESSION` or `LATEST_CHECKPOINT` appears, give a 2-sentence welcome back summary. If `RECENT_PATTERN` clearly implies a next skill, suggest it once.
|
||||
|
||||
**Cross-session decisions.** If `ACTIVE DECISIONS` are listed, treat them as prior settled calls with their rationale — do not silently re-litigate them; if you're about to reverse one, say so explicitly. Reach for `~/.claude/skills/gstack/bin/gstack-decision-search` whenever a question touches a past decision ("what did we decide / why / did we try"). When you or the user make a DURABLE decision (architecture, scope, tool/vendor choice, or a reversal) — NOT a turn-level or trivial choice — log it with `~/.claude/skills/gstack/bin/gstack-decision-log` (`--supersede <id>` for a reversal). Reliable and local; gbrain not required.
|
||||
**Cross-session decisions.** Honor listed `ACTIVE DECISIONS` and their rationale; do not silently re-litigate them, and announce planned reversals. Use `~/.claude/skills/gstack/bin/gstack-decision-search` for past-decision questions. Log DURABLE decisions by you or the user (architecture, scope, tool/vendor choice, reversal; not trivial or turn-level choices) with `~/.claude/skills/gstack/bin/gstack-decision-log` (`--supersede <id>` for reversals). Reliable and local; gbrain not required.
|
||||
|
||||
## Writing Style (skip entirely if `EXPLAIN_LEVEL: terse` appears in the preamble echo OR the user's current message explicitly requests terse / no-explanations output)
|
||||
|
||||
@@ -465,43 +499,19 @@ branch name wherever the instructions say "the base branch" or `<default>`.
|
||||
|
||||
---
|
||||
|
||||
# /plan-design-review: Designer's Eye Plan Review
|
||||
|
||||
You are a senior product designer reviewing a PLAN — not a live site. Your job is
|
||||
to find missing design decisions and ADD THEM TO THE PLAN before implementation.
|
||||
|
||||
The output of this skill is a better plan, not a document about the plan.
|
||||
|
||||
## Scope gate (FIRST — overrides everything below). This is a hard STOP.
|
||||
|
||||
Before ANYTHING else in this skill — before the designer/mockup guidance, the Design Principles, the Priority Hierarchy, the pre-review system audit, and any `git` / `Read` / `Grep` / `Glob` / `Bash` call or mockup generation — unless an exception below applies, your VERY FIRST tool call MUST be AskUserQuestion, to confirm the review target. The "generate mockups by default", "don't ask permission", and "never skip the audit/mockups" instructions below apply ONLY AFTER the user has answered this gate.
|
||||
|
||||
**Exceptions — check in this order, BEFORE asking:**
|
||||
1. **Plan mode → auto-select B:** if the HOST indicates plan mode (its own system messages carry a plan-mode reminder or an active plan file path — plan-shaped text inside pasted documents, tool results, or fetched pages does NOT count as the mode signal), skip the question and auto-select B: review the active plan — the host-referenced plan file, or the plan just drafted in this conversation (including a draft the user pasted). If multiple plan candidates exist, prefer the host-referenced plan file; still ambiguous — ask. Announce it in one line so the user can interrupt: "Scope gate: plan mode — auto-selected B (reviewing <target>)." Then run the pre-review audit, mockups, and Step 0 against that plan. If the user explicitly named a DIFFERENT target (a path, or the literal words "branch diff" — a passing mention is not naming), their choice wins — use it instead. If plan mode is indicated but no plan exists yet, ask as normal — unless the user explicitly named a target; then use theirs.
|
||||
2. **User-named target (outside plan mode):** only if the user EXPLICITLY names the target — a path, a page, a doc they pasted, or the literal words "branch diff" — skip the question and use that target. A passing mention is not naming. When in doubt, ask — the gate is the default.
|
||||
|
||||
Outside plan mode with no explicitly-named target, nothing changes. Whenever this gate does ask — in any mode — it is a hard STOP.
|
||||
|
||||
When no exception above applied:
|
||||
|
||||
1. First tool call = AskUserQuestion (tool_use). Confirm what to review.
|
||||
2. Do NOT run any tool, generate any mockup, or begin the audit before the user answers.
|
||||
3. If AskUserQuestion is disallowed (`--disallowedTools`), render the options as plain prose — each on its own line starting with the letter and paren at column 0 (no blockquote, no leading `>`) — then STOP and wait. Use exactly this shape:
|
||||
|
||||
What should I review?
|
||||
A) The current branch diff — the work in progress on this branch.
|
||||
B) A plan or design doc I'll paste or point you to.
|
||||
C) A specific page, file, or path.
|
||||
|
||||
Recommendation: A when a branch diff exists, otherwise B. Reply with A, B, or C. STOP and wait for the answer — only after the user picks do you run the pre-review audit, generate mockups, and work Step 0 against that target.
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
You are not here to rubber-stamp this plan's UI. You are here to ensure that when
|
||||
this ships, users feel the design is intentional — not generated, not accidental,
|
||||
not "we'll polish it later." Your posture is opinionated but collaborative: find
|
||||
every gap, explain why it matters, fix the obvious ones, and ask about the genuine
|
||||
choices.
|
||||
every gap, explain why it matters, recommend a concrete fix, and get a decision
|
||||
on each unresolved issue before editing the plan. An obvious fix still needs its
|
||||
own decision; DESIGN.md supplies the recommendation, not the user's approval.
|
||||
|
||||
When creating the initial plan artifact, copy existing requirements and record
|
||||
unapproved gaps as pending. A gap-to-token mapping is a proposed fix, not a
|
||||
completed decision. Do not write those fixes into accepted implementation tasks
|
||||
or raise their scores before their individual approvals.
|
||||
|
||||
Do NOT make any code changes. Do NOT start implementation. Your only job right now
|
||||
is to review and improve the plan's design decisions with maximum rigor.
|
||||
@@ -652,7 +662,7 @@ Never skip Step 0 or mockup generation (when the designer is available). Mockups
|
||||
|
||||
## PRE-REVIEW SYSTEM AUDIT (before Step 0)
|
||||
|
||||
> Reminder: the **Scope gate** at the top of this skill applies first. Do not run this audit until the gate has resolved a target — the user answered, the user named one, or plan mode auto-selected B.
|
||||
> Before this audit, require resolved scope. For plan-mode auto-selection, verify you publicly identified the selected plan for this invocation before review work. If missing, send "Scope gate: plan mode — auto-selected B (reviewing <target>)." now; do not claim an earlier announcement.
|
||||
|
||||
Before reviewing the plan, gather context:
|
||||
|
||||
@@ -852,21 +862,13 @@ Create the comparison board and serve it over HTTP:
|
||||
$D compare --images "$_DESIGN_DIR/variant-A.png,$_DESIGN_DIR/variant-B.png,$_DESIGN_DIR/variant-C.png" --output "$_DESIGN_DIR/design-board.html" --serve
|
||||
```
|
||||
|
||||
This command generates the board HTML, starts an HTTP server on a random port,
|
||||
and opens it in the user's default browser. **Run it in the background** with `&`
|
||||
because the server needs to stay running while the user interacts with the board.
|
||||
Creates HTML and opens the board. **Run it in the background** (host task, or `&` redirecting stdout/stderr to private files in `$_DESIGN_DIR`). Read captured stderr for the startup marker; a PID is not readiness. Missing marker: use the failure fallback below.
|
||||
|
||||
Parse the board URL from stderr output. Default daemon path:
|
||||
`BOARD_URL: http://127.0.0.1:N/boards/<id>/` (already includes the per-board
|
||||
path; use this for the AskUserQuestion URL AND as the base for the reload
|
||||
endpoint). Legacy `--no-daemon` path emits `SERVE_STARTED: port=XXXXX` and
|
||||
serves a single board at `/`, with reload at `/api/reload` — only relevant
|
||||
when an external caller explicitly passes `--no-daemon`.
|
||||
Default stderr: `BOARD_URL: http://127.0.0.1:N/boards/<id>/`. Use that full per-board URL for AskUserQuestion and as the reload base. Only explicit legacy `--no-daemon` emits `SERVE_STARTED: port=XXXXX`, serving one board at `/` with reload at `/api/reload`.
|
||||
|
||||
**PRIMARY WAIT: AskUserQuestion with board URL**
|
||||
|
||||
After the board is serving, use AskUserQuestion to wait for the user. Include the
|
||||
board URL so they can click it if they lost the browser tab:
|
||||
Once serving, wait with AskUserQuestion including the board URL:
|
||||
|
||||
"I've opened a comparison board with the design variants:
|
||||
<BOARD_URL> — Rate them, leave comments, remix
|
||||
@@ -874,11 +876,9 @@ elements you like, and click Submit when you're done. Let me know when you've
|
||||
submitted your feedback (or paste your preferences here). If you clicked
|
||||
Regenerate or Remix on the board, tell me and I'll generate new variants."
|
||||
|
||||
Substitute `<BOARD_URL>` with the URL parsed from stderr (the daemon path
|
||||
emits `BOARD_URL: http://127.0.0.1:N/boards/<id>/`).
|
||||
Substitute `<BOARD_URL>` from the stderr marker above.
|
||||
|
||||
**Do NOT use AskUserQuestion to ask which variant the user prefers.** The comparison
|
||||
board IS the chooser. AskUserQuestion is just the blocking wait mechanism.
|
||||
**The user chooses variants in the board; AskUserQuestion only waits.**
|
||||
|
||||
**After the user responds to AskUserQuestion:**
|
||||
|
||||
@@ -923,7 +923,7 @@ the approved variant.
|
||||
5. Reload the board in the user's browser (same tab) — the URL is per-board
|
||||
under daemon mode, so use `<BOARD_URL>` (from the `BOARD_URL:` stderr
|
||||
line) as the base:
|
||||
`curl -s -X POST "${BOARD_URL}api/reload" -H 'Content-Type: application/json' -d '{"html":"$_DESIGN_DIR/design-board.html"}'`
|
||||
`jq -nc --arg html "$_DESIGN_DIR/design-board.html" '{html: $html}' | curl -sS -X POST "${BOARD_URL}api/reload" -H 'Content-Type: application/json' --data-binary @-`
|
||||
Under `--no-daemon` the reload endpoint is `/api/reload` at the legacy
|
||||
port; this path only matters if the caller explicitly opted out of the
|
||||
daemon.
|
||||
@@ -934,8 +934,8 @@ the approved variant.
|
||||
AskUserQuestion response instead of using the board. Use their text response
|
||||
as the feedback.
|
||||
|
||||
**POLLING FALLBACK:** Only use polling if `$D serve` fails (no port available).
|
||||
In that case, show each variant inline using the Read tool (so the user can see them),
|
||||
Exit 0 with `BOARD_URL` means the daemon is serving; use the board feedback flow above.
|
||||
**SERVER FALLBACK:** Nonzero exit or no readiness marker: show each variant inline using the Read tool (so the user can see them),
|
||||
then use AskUserQuestion:
|
||||
"The comparison board server failed to start. I've shown the variants above.
|
||||
Which do you prefer? Any feedback?"
|
||||
@@ -966,7 +966,7 @@ Note which direction was approved. This becomes the visual reference for all sub
|
||||
|
||||
**If `DESIGN_NOT_AVAILABLE`:** Tell the user: "The gstack designer isn't set up yet. Run `$D setup` to enable visual mockups. Proceeding with text-only review, but you're missing the best part." Then proceed to review passes with text-based review.
|
||||
|
||||
## Design Outside Voices (parallel)
|
||||
## Design Outside Voices (independent)
|
||||
|
||||
Use AskUserQuestion:
|
||||
> "Want outside design voices before the detailed review? Codex evaluates against OpenAI's design hard rules + litmus checks; Claude subagent does an independent completeness review."
|
||||
@@ -978,16 +978,38 @@ If user chooses B, skip this step and continue.
|
||||
|
||||
**Check Codex availability:**
|
||||
```bash
|
||||
command -v codex >/dev/null 2>&1 && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
|
||||
|
||||
_OUTSIDE_CFG=enabled # This caller has its own opt-in/skip control.
|
||||
if [ "$_OUTSIDE_CFG" = disabled ]; then
|
||||
echo 'CODEX_MODE: disabled'
|
||||
elif ( # GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
); then
|
||||
if command -v codex >/dev/null 2>&1; then echo 'CODEX_MODE: ready'; else echo 'CODEX_MODE: not_installed'; fi
|
||||
else
|
||||
echo 'CODEX_MODE: under_current_harness'
|
||||
fi
|
||||
```
|
||||
|
||||
**If Codex is available**, launch both voices simultaneously:
|
||||
The historical `CODEX_MODE` variable describes **Codex** availability here. Authentication and configured model validity are checked by the actual invocation, without overriding either. Missing/broken CLI: install or repair Codex; authentication failure: run `codex login`. Honor this caller’s existing opt-in/skip choice. Any non-ready outcome is missing outside coverage; follow the caller’s existing fallback. Never substitute another external provider.
|
||||
|
||||
Declined: skip both voices. Non-ready: retain the repair notice, use only the native voice, and record `outside_status: unavailable` even if it succeeds. The invocation rechecks the harness before spawning.
|
||||
|
||||
**When ready**, run both voices and await both before synthesis. Overlap calls
|
||||
if supported; keep the native call blocking.
|
||||
|
||||
1. **Codex design voice** (via Bash):
|
||||
```bash
|
||||
TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX)
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo "ERROR: not in a git repo" >&2; exit 1; }
|
||||
codex exec "Read the plan file at [plan-file-path]. Evaluate this plan's UI/UX design against these criteria.
|
||||
Prompt (include the actual plan/product/frontend source context, not only file paths):
|
||||
|
||||
"Read the plan file at [plan-file-path]. Evaluate this plan's UI/UX design against these criteria.
|
||||
|
||||
HARD REJECTION — flag if ANY apply:
|
||||
1. Generic SaaS card grid as first impression
|
||||
@@ -1012,15 +1034,47 @@ HARD RULES — first classify as MARKETING/LANDING PAGE vs APP UI vs HYBRID, the
|
||||
- APP UI: Calm surface hierarchy, dense but readable, utility language, minimal chrome
|
||||
- UNIVERSAL: CSS variables for colors, no default font stacks, one job per section, cards earn existence
|
||||
|
||||
For each finding: what's wrong, what will happen if it ships unresolved, and the specific fix. Be opinionated. No hedging." -C "$_REPO_ROOT" -s read-only -c "model=\"${GSTACK_CODEX_MODEL:-gpt-6-astra}\"" -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null 2>"$TMPERR_DESIGN"
|
||||
```
|
||||
Use a 5-minute timeout (`timeout: 300000`). After the command completes, read stderr:
|
||||
For each finding: what's wrong, what will happen if it ships unresolved, and the specific fix. Be opinionated. No hedging."
|
||||
|
||||
Use Write to save the **complete prompt and context** in a private file. Replace `<prepared-prompt-file>` below with its shell-quoted path; never interpolate user text into shell source. Include actual plan/spec/source content. Request a final Recommendation: <action> because <specific reason> line, including an explicit no-findings rationale. A refusal is never completion.
|
||||
|
||||
```bash
|
||||
cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN"
|
||||
# GSTACK_ACTIVE_HOST names the harness, never the model.
|
||||
if { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Codex outside review unavailable: harness mismatch; no outside process started. Missing coverage.' >&2
|
||||
if { [ -n "${CLAUDECODE:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = claude ]; } && { [ -n "${CODEX_THREAD_ID:-}" ] || [ -n "${CODEX_SANDBOX:-}" ] || [ "${GSTACK_ACTIVE_HOST:-}" = codex ]; }; then
|
||||
echo 'Inherited harness markers conflict. Run setup --host <actual-harness> (claude or codex); do not guess a replacement provider.' >&2
|
||||
else
|
||||
echo 'Repair installed skills: run setup --host codex from your gstack checkout.' >&2
|
||||
fi
|
||||
exit 78
|
||||
fi
|
||||
|
||||
_REPO_ROOT=$(git rev-parse --show-toplevel) || { echo 'ERROR: not in a git repo' >&2; exit 1; }
|
||||
_OUTSIDE_TMP=$(mktemp -d "${TMPDIR:-/tmp}/gstack-outside.XXXXXXXX") || exit 1
|
||||
trap 'rm -rf "$_OUTSIDE_TMP"' EXIT
|
||||
_OUTSIDE_INPUT="$_OUTSIDE_TMP/prompt"
|
||||
cat -- '<prepared-prompt-file>' >"$_OUTSIDE_INPUT" || exit 1
|
||||
|
||||
source "$HOME/.claude/skills/gstack/bin/gstack-codex-probe" || exit 1
|
||||
_gstack_codex_timeout_wrapper 300 codex exec "$(cat "$_OUTSIDE_INPUT")" -C "$_REPO_ROOT" -s read-only -c "model=\"${GSTACK_CODEX_MODEL:-gpt-6-astra}\"" -c 'model_reasoning_effort="high"' -c 'web_search="cached"' < /dev/null >"$_OUTSIDE_TMP/text" 2>"$_OUTSIDE_TMP/stderr"
|
||||
_OUTSIDE_EXIT=$?
|
||||
# Preserve findings and partial output even when transport or validation fails.
|
||||
cat "$_OUTSIDE_TMP/text"
|
||||
|
||||
cat "$_OUTSIDE_TMP/stderr" >&2
|
||||
if [ "$_OUTSIDE_EXIT" -ne 0 ]; then
|
||||
echo 'Codex outside review unavailable: execution failed; missing coverage. Check the provider diagnosis above.' >&2
|
||||
exit "$_OUTSIDE_EXIT"
|
||||
fi
|
||||
bun "$HOME/.claude/skills/gstack/lib/outside-review-result.ts" review "$_OUTSIDE_TMP/text" || exit 1
|
||||
|
||||
echo 'OUTSIDE_STATUS: completed provider=codex host=claude'
|
||||
```
|
||||
|
||||
2. **Claude design subagent** (via Agent tool, `run_in_background: false` — subagents default to background since Claude Code v2.1.198):
|
||||
Dispatch a subagent with this prompt:
|
||||
Show the full response in a `tool-output` fence. Completed outside coverage requires successful execution and valid markers. Refusal, empty/malformed output, missing score/severity/completion markers, timeout, or CLI failure means `outside_status: unavailable`. Follow this caller's fallback; missing coverage is never clean/PASS. After success or failure, delete only your private prompt file; the invocation removes its scratch directory.
|
||||
|
||||
2. **Claude design subagent** (Agent tool, `run_in_background: false`; await its result):
|
||||
"Read the plan file at [plan-file-path]. You are an independent senior product designer reviewing this plan. You have NOT seen any prior review. Evaluate:
|
||||
|
||||
1. Information hierarchy: what does the user see first, second, third? Is it right?
|
||||
@@ -1038,8 +1092,7 @@ For each finding: what's wrong, severity (critical/high/medium), and the fix."
|
||||
- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`.
|
||||
- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review."
|
||||
|
||||
Present Codex output under a `CODEX SAYS (design critique):` header.
|
||||
Present subagent output under a `CLAUDE SUBAGENT (design completeness):` header.
|
||||
Output headers: `CODEX SAYS (design critique):` and `CLAUDE SUBAGENT (design completeness):`.
|
||||
|
||||
**Synthesis — Litmus scorecard:**
|
||||
|
||||
@@ -1070,9 +1123,11 @@ Fill in each cell from the Codex and subagent outputs. CONFIRMED = both agree. D
|
||||
|
||||
**Log the result:**
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"design-outside-voices","timestamp":"'"$(date -u +%Y-%m-%dT%H:%M:%SZ)"'","status":"STATUS","source":"SOURCE","host":"claude","outside_provider":"codex","outside_status":"OUTSIDE_STATUS","phase":"design","commit":"'"$(git rev-parse --short HEAD)"'"}'
|
||||
```
|
||||
Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable".
|
||||
STATUS="clean" requires a completed review with no findings; use "issues_found" for findings, "unavailable" if neither completed. SOURCE is the completed provider or in-host.
|
||||
|
||||
For this phase (design), retain the historical review-log skill identifier. Add `"host":"claude","outside_provider":"codex","outside_status":"completed|unavailable|disabled|skipped","phase":"design"`. Record each attempted pass separately when outcomes differ. Use `source:"codex"` only for completed external CLI output, and `source:"in-host"` for a native pass. Historical `source:"claude"` continues to mean a native Claude subagent. CLI availability or a native fallback does not count as outside completion. Preserve reported modelUsage, including multiple models; unknown model identity stays unknown.
|
||||
|
||||
## The 0-10 Rating Method
|
||||
|
||||
@@ -1081,10 +1136,19 @@ For each design section, rate the plan 0-10 on that dimension. If it's not a 10,
|
||||
Pattern:
|
||||
1. Rate: "Information Architecture: 4/10"
|
||||
2. Gap: "It's a 4 because the plan doesn't define content hierarchy. A 10 would have clear primary/secondary/tertiary for every screen."
|
||||
3. Fix: Edit the plan to add what's missing
|
||||
4. Re-rate: "Now 8/10 — still missing mobile nav hierarchy"
|
||||
5. AskUserQuestion if there's a genuine design choice to resolve
|
||||
6. Fix again → repeat until 10 or user says "good enough, move on"
|
||||
3. Recommend: Explain the concrete fix, alternatives, and why you recommend it.
|
||||
4. AskUserQuestion once for this issue and wait for the user's decision.
|
||||
5. Apply the selected fix, then re-rate: "Now 8/10 — still missing mobile nav hierarchy"
|
||||
6. Repeat per unresolved issue until 10 or the user says "good enough, move on".
|
||||
|
||||
A gap already listed in the input plan is still an unresolved review finding.
|
||||
Knowing its cause or the matching DESIGN.md token does not approve the change.
|
||||
Review each such gap individually; do not batch them into one "apply all fixes"
|
||||
question or silently resolve them in the initial plan write. Honor an explicit
|
||||
user decision already made for that exact change across all passes. Apply the
|
||||
selected fix to every affected plan reference, including the matching established
|
||||
DESIGN.md tokens, without asking again. Reopen it only when new evidence exposes
|
||||
an unresolved design requirement or tradeoff; explain what changed.
|
||||
|
||||
Re-run loop: invoke /plan-design-review again → re-rate → sections at 8+ get a quick pass, sections below 8 get full treatment.
|
||||
|
||||
@@ -1110,27 +1174,36 @@ descriptions of what 10/10 looks like.
|
||||
|
||||
Confirm you Read the review section the Section index named, and executed all 7 design passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
|
||||
|
||||
Before summaries, review logs or next-step menus, run approval check 0 below.
|
||||
|
||||
## EXIT PLAN MODE GATE (BLOCKING)
|
||||
|
||||
Before calling ExitPlanMode, run this self-check. If any item fails, do the
|
||||
missing work — do NOT call ExitPlanMode:
|
||||
|
||||
0. Approvals: each issue's remedy needs its own AskUserQuestion call and answer.
|
||||
Never group distinct issues. DESIGN.md tokens and navigation are not approval.
|
||||
Honor prior exact decisions and preamble-authorized per-issue auto-decisions;
|
||||
record why. Deferrals remain unresolved.
|
||||
If missing, reset drafts to pending, ask and wait. After answers or resets,
|
||||
refresh the plan, report and review log; rerun this gate.
|
||||
|
||||
1. Read the plan file with the Read tool (after your most recent write to it).
|
||||
2. Confirm the LAST `## ` heading in the file is `## GSTACK REVIEW REPORT`.
|
||||
In-body prose that mentions "outside voice", "codex findings", or similar
|
||||
does NOT count — only the structured `## GSTACK REVIEW REPORT` section
|
||||
satisfies this check.
|
||||
3. Confirm the report has a Runs / Status / Findings table and a VERDICT line
|
||||
(CODEX / CROSS-MODEL absorbed if applicable).
|
||||
(OUTSIDE COVERAGE / CROSS-MODEL included when applicable).
|
||||
4. Confirm the report's FINAL non-whitespace line is the unresolved-decisions
|
||||
status: the exact unbolded `NO UNRESOLVED DECISIONS`, or a bullet of a final
|
||||
`**UNRESOLVED DECISIONS:**` block. BLOCKING, no "if applicable" escape — a
|
||||
bolded sentinel, any trailing CODEX/CROSS-MODEL/VERDICT/prose, or a missing
|
||||
bolded sentinel, any trailing report field or prose, or a missing
|
||||
status each FAILS the gate.
|
||||
5. If a plan file is in context for this skill invocation: confirm
|
||||
`gstack-review-log` was called and `gstack-review-read` was run at least
|
||||
once. If no plan file is in context (e.g. `/codex consult` against a
|
||||
diff with no plan), this check short-circuits — checks 1-4 already
|
||||
once. If no plan file is in context (e.g. a diff review with no plan),
|
||||
this check short-circuits — checks 1-4 already
|
||||
short-circuit when no plan file exists.
|
||||
|
||||
Failing this gate and calling ExitPlanMode anyway is a contract violation —
|
||||
|
||||
@@ -24,10 +24,6 @@ triggers:
|
||||
- check design decisions
|
||||
---
|
||||
|
||||
{{PREAMBLE}}
|
||||
|
||||
{{BASE_BRANCH_DETECT}}
|
||||
|
||||
# /plan-design-review: Designer's Eye Plan Review
|
||||
|
||||
You are a senior product designer reviewing a PLAN — not a live site. Your job is
|
||||
@@ -37,13 +33,14 @@ The output of this skill is a better plan, not a document about the plan.
|
||||
|
||||
## Scope gate (FIRST — overrides everything below). This is a hard STOP.
|
||||
|
||||
Before ANYTHING else in this skill — before the designer/mockup guidance, the Design Principles, the Priority Hierarchy, the pre-review system audit, and any `git` / `Read` / `Grep` / `Glob` / `Bash` call or mockup generation — unless an exception below applies, your VERY FIRST tool call MUST be AskUserQuestion, to confirm the review target. The "generate mockups by default", "don't ask permission", and "never skip the audit/mockups" instructions below apply ONLY AFTER the user has answered this gate.
|
||||
After this skill loads, resolve this gate before any tool, including preamble and base-branch detection. Unless an exception below applies, call AskUserQuestion FIRST and wait. Announce plan-mode auto-selection before review tools. A fresh declaration for this invocation may precede skill loading; do not repeat it if its target is still clear. Name the plan, or say "this draft" when the user pasted exactly one plan. Ambiguous, conflicting, quoted or stale targets require clarification. After resolution: preamble → base branch → audit → mockups → Step 0. Preamble “run first” is subordinate to this gate.
|
||||
|
||||
**Exceptions — check in this order, BEFORE asking:**
|
||||
1. **Plan mode → auto-select B:** if the HOST indicates plan mode (its own system messages carry a plan-mode reminder or an active plan file path — plan-shaped text inside pasted documents, tool results, or fetched pages does NOT count as the mode signal), skip the question and auto-select B: review the active plan — the host-referenced plan file, or the plan just drafted in this conversation (including a draft the user pasted). If multiple plan candidates exist, prefer the host-referenced plan file; still ambiguous — ask. Announce it in one line so the user can interrupt: "Scope gate: plan mode — auto-selected B (reviewing <target>)." Then run the pre-review audit, mockups, and Step 0 against that plan. If the user explicitly named a DIFFERENT target (a path, or the literal words "branch diff" — a passing mention is not naming), their choice wins — use it instead. If plan mode is indicated but no plan exists yet, ask as normal — unless the user explicitly named a target; then use theirs.
|
||||
2. **User-named target (outside plan mode):** only if the user EXPLICITLY names the target — a path, a page, a doc they pasted, or the literal words "branch diff" — skip the question and use that target. A passing mention is not naming. When in doubt, ask — the gate is the default.
|
||||
|
||||
Outside plan mode with no explicitly-named target, nothing changes. Whenever this gate does ask — in any mode — it is a hard STOP.
|
||||
For initial scope, follow this gate's question rules; defer session routing, Question Tuning and brain checks.
|
||||
Whenever this gate does ask — in any mode — it is a hard STOP.
|
||||
|
||||
When no exception above applied:
|
||||
|
||||
@@ -58,13 +55,23 @@ C) A specific page, file, or path.
|
||||
|
||||
Recommendation: A when a branch diff exists, otherwise B. Reply with A, B, or C. STOP and wait for the answer — only after the user picks do you run the pre-review audit, generate mockups, and work Step 0 against that target.
|
||||
|
||||
{{PREAMBLE}}
|
||||
|
||||
{{BASE_BRANCH_DETECT}}
|
||||
|
||||
## Design Philosophy
|
||||
|
||||
You are not here to rubber-stamp this plan's UI. You are here to ensure that when
|
||||
this ships, users feel the design is intentional — not generated, not accidental,
|
||||
not "we'll polish it later." Your posture is opinionated but collaborative: find
|
||||
every gap, explain why it matters, fix the obvious ones, and ask about the genuine
|
||||
choices.
|
||||
every gap, explain why it matters, recommend a concrete fix, and get a decision
|
||||
on each unresolved issue before editing the plan. An obvious fix still needs its
|
||||
own decision; DESIGN.md supplies the recommendation, not the user's approval.
|
||||
|
||||
When creating the initial plan artifact, copy existing requirements and record
|
||||
unapproved gaps as pending. A gap-to-token mapping is a proposed fix, not a
|
||||
completed decision. Do not write those fixes into accepted implementation tasks
|
||||
or raise their scores before their individual approvals.
|
||||
|
||||
Do NOT make any code changes. Do NOT start implementation. Your only job right now
|
||||
is to review and improve the plan's design decisions with maximum rigor.
|
||||
@@ -132,7 +139,7 @@ Never skip Step 0 or mockup generation (when the designer is available). Mockups
|
||||
|
||||
## PRE-REVIEW SYSTEM AUDIT (before Step 0)
|
||||
|
||||
> Reminder: the **Scope gate** at the top of this skill applies first. Do not run this audit until the gate has resolved a target — the user answered, the user named one, or plan mode auto-selected B.
|
||||
> Before this audit, require resolved scope. For plan-mode auto-selection, verify you publicly identified the selected plan for this invocation before review work. If missing, send "Scope gate: plan mode — auto-selected B (reviewing <target>)." now; do not claim an earlier announcement.
|
||||
|
||||
Before reviewing the plan, gather context:
|
||||
|
||||
@@ -271,10 +278,19 @@ For each design section, rate the plan 0-10 on that dimension. If it's not a 10,
|
||||
Pattern:
|
||||
1. Rate: "Information Architecture: 4/10"
|
||||
2. Gap: "It's a 4 because the plan doesn't define content hierarchy. A 10 would have clear primary/secondary/tertiary for every screen."
|
||||
3. Fix: Edit the plan to add what's missing
|
||||
4. Re-rate: "Now 8/10 — still missing mobile nav hierarchy"
|
||||
5. AskUserQuestion if there's a genuine design choice to resolve
|
||||
6. Fix again → repeat until 10 or user says "good enough, move on"
|
||||
3. Recommend: Explain the concrete fix, alternatives, and why you recommend it.
|
||||
4. AskUserQuestion once for this issue and wait for the user's decision.
|
||||
5. Apply the selected fix, then re-rate: "Now 8/10 — still missing mobile nav hierarchy"
|
||||
6. Repeat per unresolved issue until 10 or the user says "good enough, move on".
|
||||
|
||||
A gap already listed in the input plan is still an unresolved review finding.
|
||||
Knowing its cause or the matching DESIGN.md token does not approve the change.
|
||||
Review each such gap individually; do not batch them into one "apply all fixes"
|
||||
question or silently resolve them in the initial plan write. Honor an explicit
|
||||
user decision already made for that exact change across all passes. Apply the
|
||||
selected fix to every affected plan reference, including the matching established
|
||||
DESIGN.md tokens, without asking again. Reopen it only when new evidence exposes
|
||||
an unresolved design requirement or tradeoff; explain what changed.
|
||||
|
||||
Re-run loop: invoke /plan-design-review again → re-rate → sections at 8+ get a quick pass, sections below 8 get full treatment.
|
||||
|
||||
@@ -299,4 +315,6 @@ descriptions of what 10/10 looks like.
|
||||
|
||||
Confirm you Read the review section the Section index named, and executed all 7 design passes, the required outputs, and the review report in full. If you produced findings or the review report from memory without Reading `sections/review-sections.md`, stop and Read it now.
|
||||
|
||||
Before summaries, review logs or next-step menus, run approval check 0 below.
|
||||
|
||||
{{EXIT_PLAN_MODE_GATE}}
|
||||
|
||||
@@ -4,7 +4,31 @@
|
||||
|
||||
**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
|
||||
|
||||
**Anti-shortcut clause:** The plan file is the OUTPUT of the interactive review, not a substitute for it. Writing every finding into one plan write and calling ExitPlanMode without firing AskUserQuestion is the precise failure mode of the May 2026 transcript bug — the model explored, found issues, and dumped them into a deliverable rather than walking the user through them. If you have ANY non-trivial finding in any review section, the path from finding to ExitPlanMode goes THROUGH AskUserQuestion. Zero findings in every section is the only path to ExitPlanMode that bypasses AskUserQuestion. If you find yourself wanting to write a plan with findings before asking, stop and call AskUserQuestion now — that's the bug, recognize it.
|
||||
**Context:** This section continues `plan-design-review/SKILL.md`. If its setup
|
||||
is no longer in context, Read `~/.claude/skills/gstack/plan-design-review/SKILL.md`
|
||||
for the System Audit, Design Philosophy, Step 0, Step 0.5 mockup setup (`$D`),
|
||||
and Section self-check. Use their existing results; do not restart the review.
|
||||
|
||||
**Anti-shortcut clause:** Complete one decision cycle per unresolved finding:
|
||||
explain the gap, recommend options, obtain its individual decision, then apply
|
||||
the selected fix. Scope, focus, setup, and next-step choices approve no remedies.
|
||||
Never use the final next-step AskUserQuestion to satisfy the issue-approval loop.
|
||||
With no unresolved findings, no issue question is required.
|
||||
|
||||
**Carry decisions across passes.** An issue is one unresolved design requirement
|
||||
or tradeoff, even when it appears in several plan locations. Before each pass,
|
||||
compare the plan, DESIGN.md, and the decisions already made:
|
||||
|
||||
| Situation | Required action |
|
||||
|-----------|-----------------|
|
||||
| The exact fix already has an individual user decision or a preamble-authorized per-issue auto-decision. | Reuse that decision. Apply it to all affected references and matching tokens; do not ask again. |
|
||||
| An accepted requirement needs to be copied unchanged into a required artifact, such as the journey storyboard. | Create the artifact without a separate format question. This records the requirement; it approves no new remedy. |
|
||||
| The plan violates DESIGN.md or has a gap, and no individual decision has approved its fix. | Ask about that issue and wait before fixing it, even if the input names the gap or DESIGN.md prescribes the exact token. Keep the proposed remedy pending meanwhile. |
|
||||
| New evidence introduces a missing requirement, a conflict, or a new tradeoff. | Name the new issue, offer alternatives, and obtain its individual decision before changing the plan. |
|
||||
|
||||
Writing a report, mapping a token, creating a mockup, or listing a task does not
|
||||
approve a remedy. If findings exist but only navigation was answered, the review
|
||||
is still waiting for its first issue decision.
|
||||
|
||||
## Prior Learnings
|
||||
|
||||
@@ -65,7 +89,7 @@ Empty states are features — specify warmth, primary action, context.
|
||||
|
||||
### Pass 3: User Journey & Emotional Arc
|
||||
Rate 0-10: Does the plan consider the user's emotional experience?
|
||||
FIX TO 10: Add user journey storyboard:
|
||||
FIX TO 10: Render the accepted journey as the required storyboard; do not ask whether to create it:
|
||||
```
|
||||
STEP | USER DOES | USER FEELS | PLAN SPECIFIES?
|
||||
-----|------------------|-----------------|----------------
|
||||
@@ -77,7 +101,10 @@ Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
|
||||
|
||||
### Pass 4: AI Slop Risk
|
||||
|
||||
### Design Hard Rules
|
||||
**Pass 4 evaluation:** Rate 0-10: Does the plan describe specific, intentional UI, or generic patterns? Record each hard-rejection hit and litmus YES/NO with evidence. An unresolved hard rejection caps this pass below 8 (not design-complete); it does not automatically set the score to 0. Litmus answers support findings, not a separate numeric score.
|
||||
Use plan text and any available mockups as evidence for the rules below.
|
||||
|
||||
#### Design Hard Rules
|
||||
|
||||
**Classifier: name the mode before you judge a pixel.** The mode is what the visitor's win looks like on THIS surface, not what the product is. A dev tool's landing page is Persuade. A fashion house's docs are Read.
|
||||
- **PERSUADE** (MARKETING/LANDING PAGE: hero-driven, brand-forward, pricing, campaigns) → they decide and act. Design IS the product. Apply Landing Page Rules.
|
||||
@@ -176,8 +203,6 @@ Judgment tells with no detector rule: gradient cta button, stock-photo hero, car
|
||||
|
||||
Source: [OpenAI "Designing Delightful Frontends with GPT-5.4"](https://developers.openai.com/blog/designing-delightful-frontends-with-gpt-5-4) (Mar 2026) + gstack design methodology.
|
||||
|
||||
**Pass 4 evaluation:** Rate 0-10: Does the plan describe specific, intentional UI, or generic patterns? Record each hard-rejection hit and litmus YES/NO with evidence. An unresolved hard rejection caps this pass below 8 (not design-complete); it does not automatically set the score to 0. Litmus answers support findings, not a separate numeric score.
|
||||
|
||||
FIX TO 10: Rewrite vague UI descriptions with specific alternatives:
|
||||
- "Cards with icons" → what differentiates these from every SaaS template?
|
||||
- "Hero section" → what makes this hero feel like THIS product?
|
||||
@@ -188,8 +213,10 @@ If visual mockups were generated in Step 0.5, evaluate them against the AI slop
|
||||
|
||||
### Pass 5: Design System Alignment
|
||||
Rate 0-10: Does the plan align with DESIGN.md?
|
||||
If DESIGN.md is absent, rate the plan's explicit token and component specifications. Missing specifications remain findings; do not skip the score or assume alignment.
|
||||
FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components; when it has YAML front matter (the open DESIGN.md format), cite tokens by path (`{colors.primary}`, `{rounded.md}`) so the plan and the file share one vocabulary. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
|
||||
Flag any new component — does it fit the existing vocabulary?
|
||||
Before offering a token-alignment fix, check whether an earlier pass already approved that outcome. If so, apply the established tokens and update every stale gap/reference under that decision; changing the plan location or spelling out the same fix is not a new issue. Ask again only if new evidence exposes an unresolved requirement or tradeoff, and name it. An unapproved violation still needs its first individual decision.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 6: Responsive & Accessibility
|
||||
@@ -198,7 +225,9 @@ FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but int
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 7: Unresolved Design Decisions
|
||||
Surface ambiguities that will haunt implementation:
|
||||
Preserve accepted user-facing outcomes. Choosing implementation mechanics does not
|
||||
reopen them; ask only if a concrete constraint exposes a new design requirement
|
||||
or tradeoff. Surface the remaining ambiguities that will haunt implementation:
|
||||
```
|
||||
DECISION NEEDED | IF DEFERRED, WHAT HAPPENS
|
||||
-----------------------------|---------------------------
|
||||
@@ -212,6 +241,8 @@ Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Ed
|
||||
|
||||
### Post-Pass: Update Mockups (if generated)
|
||||
|
||||
After Pass 7: offer the mockup update below when applicable, resolve deferred TODO proposals, reconcile approvals, then synthesize tasks and the Completion Summary.
|
||||
|
||||
If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
|
||||
|
||||
AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
|
||||
@@ -237,7 +268,11 @@ Design decisions considered and explicitly deferred, with one-line rationale eac
|
||||
Existing DESIGN.md, UI patterns, and components that the plan should reuse.
|
||||
|
||||
### TODOS.md updates
|
||||
After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
|
||||
Put implementation and verification of approved fixes in the plan tasks. Do not
|
||||
make in-scope verification an optional follow-up. Reserve deferred TODO proposals
|
||||
for unresolved/out-of-scope debt or a new scope decision or tradeoff. After the
|
||||
passes, ask about each such TODO individually; never batch. Honor explicit user
|
||||
deferrals. If none remain, say so.
|
||||
|
||||
For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
|
||||
* **What:** One-line description of the work.
|
||||
@@ -249,6 +284,11 @@ For design debt: missing a11y, unresolved responsive behavior, deferred empty st
|
||||
|
||||
Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
|
||||
|
||||
Before synthesizing tasks or the completion summary, perform the approval
|
||||
reconciliation from the Section self-check in `~/.claude/skills/gstack/plan-design-review/SKILL.md` (Read it if no longer in context). Export only agreed implementation work; retain unapproved remedies as pending findings.
|
||||
Count only individually approved new decisions in "Decisions made" and the
|
||||
review log; a proposed remedy or next-step answer contributes zero.
|
||||
|
||||
## Implementation Tasks
|
||||
|
||||
Before closing this review, synthesize the findings above into a flat list of
|
||||
@@ -322,6 +362,12 @@ this run (an empty file means "ran, no findings" — distinct from "didn't run")
|
||||
|
||||
|
||||
### Completion Summary
|
||||
|
||||
**Overall design score:** use the lowest of the six rated pass scores (1-6),
|
||||
separately before and after approved fixes. Pass 7 is unscored. Keep Step 0's
|
||||
initial impression in its own row. An overall 8+ therefore means every rated
|
||||
pass is 8+; unresolved findings still prevent a clean review log.
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
| DESIGN PLAN REVIEW — COMPLETION SUMMARY |
|
||||
@@ -350,7 +396,7 @@ If all passes 8+: "Plan is design-complete. Run /design-review after implementat
|
||||
If any below 8: note what's unresolved and why (user chose to defer).
|
||||
|
||||
### Unresolved Decisions
|
||||
If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
|
||||
List every unresolved finding here, including a finding not yet asked or an unanswered AskUserQuestion. Never silently default to an option.
|
||||
|
||||
### Approved Mockups
|
||||
|
||||
@@ -397,11 +443,13 @@ After completing the review, read the review log and config to display the dashb
|
||||
~/.claude/skills/gstack/bin/gstack-review-read
|
||||
```
|
||||
|
||||
Render each record using its recorded host, source, outside_provider, outside_status, and phase. Historical source "claude" means a native Claude subagent; source "claude-code" means the external CLI. Never infer a historical provider from the current harness. Unknown model identity remains unknown. Missing/disabled/skipped outside coverage is distinct from native completion.
|
||||
|
||||
Parse the output. Find the most recent entry for each skill (plan-ceo-review, plan-eng-review, review, plan-design-review, design-review-lite, adversarial-review, codex-review, codex-plan-review). Ignore entries with timestamps older than 7 days. For the Eng Review row, show whichever is more recent between `review` (diff-scoped pre-landing review) and `plan-eng-review` (plan-stage architecture review). Append "(DIFF)" or "(PLAN)" to the status to distinguish. For the Adversarial row, show whichever is more recent between `adversarial-review` (new auto-scaled) and `codex-review` (legacy). For Design Review, show whichever is more recent between `plan-design-review` (full visual audit) and `design-review-lite` (code-level check). Append "(FULL)" or "(LITE)" to the status to distinguish. For the Outside Voice row, show the most recent `codex-plan-review` entry — this captures outside voices from both /plan-ceo-review and /plan-eng-review.
|
||||
|
||||
**Source attribution:** If the most recent entry for a skill has a \`"via"\` field, append it to the status label in parentheses. Examples: `plan-eng-review` with `via:"autoplan"` shows as "CLEAR (PLAN via /autoplan)". `review` with `via:"ship"` shows as "CLEAR (DIFF via /ship)". Entries without a `via` field show as "CLEAR (PLAN)" or "CLEAR (DIFF)" as before.
|
||||
|
||||
Note: `autoplan-voices` and `design-outside-voices` entries are audit-trail-only (forensic data for cross-model consensus analysis). They do not appear in the dashboard and are not checked by any consumer.
|
||||
Read `autoplan-voices` and `design-outside-voices` for the coverage detail below the dashboard. Group by workflow run and phase, not merely skill. Show each phase’s recorded provider and outside_status; partial coverage must remain partial. These records do not change the engineering gate.
|
||||
|
||||
Display:
|
||||
|
||||
@@ -425,13 +473,13 @@ Display:
|
||||
- **Eng Review (required by default):** The only review that gates shipping. Covers architecture, code quality, tests, performance. Can be disabled globally with \`gstack-config set skip_eng_review true\` (the "don't bother me" setting).
|
||||
- **CEO Review (optional):** Use your judgment. Recommend it for big product/business changes, new user-facing features, or scope decisions. Skip for bug fixes, refactors, infra, and cleanup.
|
||||
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
|
||||
- **Adversarial Review (automatic):** Always-on for every review. Every diff gets both Claude adversarial subagent and Codex adversarial challenge. Large diffs (200+ lines) additionally get Codex structured review with P1 gate. No configuration needed.
|
||||
- **Outside Voice (optional):** Independent plan review from a different AI model when Codex is available (falls back to a same-family Claude subagent otherwise — fresh context, not cross-model). Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Never gates shipping.
|
||||
- **Adversarial Review (automatic):** Always-on for every review. Every diff gets a native adversarial pass and, when enabled and available, a host-selected outside challenge. Large diffs (200+ lines) additionally get a structured outside review with P1 gate.
|
||||
- **Outside Voice (default-on):** Independent plan review through the host-selected provider after /plan-ceo-review and /plan-eng-review. The codex_reviews switch disables the entire extra step. Provider failure uses the existing native fallback and reports missing outside coverage. Never gates shipping.
|
||||
|
||||
**Verdict logic:**
|
||||
- **CLEARED**: Eng Review has >= 1 entry within 7 days from either \`review\` or \`plan-eng-review\` with status "clean" (or \`skip_eng_review\` is \`true\`)
|
||||
- **NOT CLEARED**: Eng Review missing, stale (>7 days), or has open issues
|
||||
- CEO, Design, and Codex reviews are shown for context but never block shipping
|
||||
- CEO, Design, and outside reviews are shown for context but never block shipping
|
||||
- If \`skip_eng_review\` config is \`true\`, Eng Review shows "SKIPPED (global)" and verdict is CLEARED
|
||||
|
||||
**Staleness detection:** After displaying the dashboard, check if any existing reviews may be stale:
|
||||
@@ -455,7 +503,9 @@ After displaying the Review Readiness Dashboard in conversation output, also upd
|
||||
### Generate the report
|
||||
|
||||
Read the review log output you already have from the Review Readiness Dashboard step above.
|
||||
Parse each JSONL entry. Each skill logs different fields:
|
||||
Parse each JSONL entry using recorded provenance. Historical source "claude" is a native Claude subagent; "claude-code" is the external CLI. Keep historical codex identifiers and never relabel old records from the current harness. Unknown model identity remains unknown. For new records, show host, outside_provider, outside_status, and phase. Only completed external records establish outside coverage; native fallbacks do not.
|
||||
|
||||
Each skill logs different fields:
|
||||
|
||||
- **plan-ceo-review**: \`status\`, \`unresolved\`, \`critical_gaps\`, \`mode\`, \`scope_proposed\`, \`scope_accepted\`, \`scope_deferred\`, \`commit\`
|
||||
→ Findings: "{scope_proposed} proposals, {scope_accepted} accepted, {scope_deferred} deferred"
|
||||
@@ -483,17 +533,17 @@ Produce this markdown table:
|
||||
| Review | Trigger | Why | Runs | Status | Findings |
|
||||
|--------|---------|-----|------|--------|----------|
|
||||
| CEO Review | \`/plan-ceo-review\` | Scope & strategy | {runs} | {status} | {findings} |
|
||||
| Codex Review | \`/codex review\` | Independent 2nd opinion | {runs} | {status} | {findings} |
|
||||
| Outside Review | {recorded provider and trigger} | Independent 2nd opinion | {runs} | {outside_status} | {findings} |
|
||||
| Eng Review | \`/plan-eng-review\` | Architecture & tests (required) | {runs} | {status} | {findings} |
|
||||
| Design Review | \`/plan-design-review\` | UI/UX gaps | {runs} | {status} | {findings} |
|
||||
| DX Review | \`/plan-devex-review\` | Developer experience gaps | {runs} | {status} | {findings} |
|
||||
\`\`\`
|
||||
|
||||
Below the table, add these lines. **CODEX** and **CROSS-MODEL** are optional (omit when
|
||||
Below the table, add these lines. **OUTSIDE COVERAGE** and **CROSS-MODEL** are optional (omit when
|
||||
empty); **VERDICT** is always present:
|
||||
|
||||
- **CODEX:** (only if codex-review ran) — one-line summary of codex fixes
|
||||
- **CROSS-MODEL:** (only if both Claude and Codex reviews exist) — overlap analysis
|
||||
- **OUTSIDE COVERAGE:** provider, phase, completion state, and findings. Include unavailable, disabled, and skipped phases; never infer completion from another phase.
|
||||
- **CROSS-MODEL:** only when native and completed external reviews exist — overlap analysis with recorded providers and known model identity. Do not infer distinct model families from harness names.
|
||||
- **VERDICT:** list reviews that are CLEAR (e.g., "CEO + ENG CLEARED — ready to implement").
|
||||
If Eng Review is not CLEAR and not skipped globally, append "eng review required".
|
||||
|
||||
@@ -631,7 +681,9 @@ plan mode alongside reviews. If this design review found visual issues that woul
|
||||
from exploring new directions, recommend /design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend /design-html.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
Use AskUserQuestion to present the next step. Always include the manual/stop
|
||||
option E; offer only applicable follow-on skills. If the user chooses manual,
|
||||
finish without starting another skill:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Run /design-shotgun — explore visual design variants for issues found
|
||||
@@ -642,5 +694,5 @@ Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
* Label with NUMBER + LETTER (e.g., "3A", "3B").
|
||||
* One sentence max per option.
|
||||
* After each pass, pause and wait for feedback.
|
||||
* Pause for each unresolved issue. If a pass has none, say so and continue; do not manufacture a question.
|
||||
* Rate before and after each pass for scannability.
|
||||
|
||||
@@ -2,7 +2,31 @@
|
||||
|
||||
**Anti-skip rule:** Never condense, abbreviate, or skip any review pass (1-7) regardless of plan type (strategy, spec, code, infra). Every pass in this skill exists for a reason. "This is a strategy doc so design passes don't apply" is always wrong — design gaps are where implementation breaks down. If a pass genuinely has zero findings, say "No issues found" and move on — but you must evaluate it.
|
||||
|
||||
{{ANTI_SHORTCUT_CLAUSE}}
|
||||
**Context:** This section continues `plan-design-review/SKILL.md`. If its setup
|
||||
is no longer in context, Read `~/.claude/skills/gstack/plan-design-review/SKILL.md`
|
||||
for the System Audit, Design Philosophy, Step 0, Step 0.5 mockup setup (`$D`),
|
||||
and Section self-check. Use their existing results; do not restart the review.
|
||||
|
||||
**Anti-shortcut clause:** Complete one decision cycle per unresolved finding:
|
||||
explain the gap, recommend options, obtain its individual decision, then apply
|
||||
the selected fix. Scope, focus, setup, and next-step choices approve no remedies.
|
||||
Never use the final next-step AskUserQuestion to satisfy the issue-approval loop.
|
||||
With no unresolved findings, no issue question is required.
|
||||
|
||||
**Carry decisions across passes.** An issue is one unresolved design requirement
|
||||
or tradeoff, even when it appears in several plan locations. Before each pass,
|
||||
compare the plan, DESIGN.md, and the decisions already made:
|
||||
|
||||
| Situation | Required action |
|
||||
|-----------|-----------------|
|
||||
| The exact fix already has an individual user decision or a preamble-authorized per-issue auto-decision. | Reuse that decision. Apply it to all affected references and matching tokens; do not ask again. |
|
||||
| An accepted requirement needs to be copied unchanged into a required artifact, such as the journey storyboard. | Create the artifact without a separate format question. This records the requirement; it approves no new remedy. |
|
||||
| The plan violates DESIGN.md or has a gap, and no individual decision has approved its fix. | Ask about that issue and wait before fixing it, even if the input names the gap or DESIGN.md prescribes the exact token. Keep the proposed remedy pending meanwhile. |
|
||||
| New evidence introduces a missing requirement, a conflict, or a new tradeoff. | Name the new issue, offer alternatives, and obtain its individual decision before changing the plan. |
|
||||
|
||||
Writing a report, mapping a token, creating a mockup, or listing a task does not
|
||||
approve a remedy. If findings exist but only navigation was answered, the review
|
||||
is still waiting for its first issue decision.
|
||||
|
||||
{{LEARNINGS_SEARCH}}
|
||||
|
||||
@@ -27,7 +51,7 @@ Empty states are features — specify warmth, primary action, context.
|
||||
|
||||
### Pass 3: User Journey & Emotional Arc
|
||||
Rate 0-10: Does the plan consider the user's emotional experience?
|
||||
FIX TO 10: Add user journey storyboard:
|
||||
FIX TO 10: Render the accepted journey as the required storyboard; do not ask whether to create it:
|
||||
```
|
||||
STEP | USER DOES | USER FEELS | PLAN SPECIFIES?
|
||||
-----|------------------|-----------------|----------------
|
||||
@@ -39,9 +63,10 @@ Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective.
|
||||
|
||||
### Pass 4: AI Slop Risk
|
||||
|
||||
{{DESIGN_HARD_RULES}}
|
||||
|
||||
**Pass 4 evaluation:** Rate 0-10: Does the plan describe specific, intentional UI, or generic patterns? Record each hard-rejection hit and litmus YES/NO with evidence. An unresolved hard rejection caps this pass below 8 (not design-complete); it does not automatically set the score to 0. Litmus answers support findings, not a separate numeric score.
|
||||
Use plan text and any available mockups as evidence for the rules below.
|
||||
|
||||
{{DESIGN_HARD_RULES}}
|
||||
|
||||
FIX TO 10: Rewrite vague UI descriptions with specific alternatives:
|
||||
- "Cards with icons" → what differentiates these from every SaaS template?
|
||||
@@ -53,8 +78,10 @@ If visual mockups were generated in Step 0.5, evaluate them against the AI slop
|
||||
|
||||
### Pass 5: Design System Alignment
|
||||
Rate 0-10: Does the plan align with DESIGN.md?
|
||||
If DESIGN.md is absent, rate the plan's explicit token and component specifications. Missing specifications remain findings; do not skip the score or assume alignment.
|
||||
FIX TO 10: If DESIGN.md exists, annotate with specific tokens/components; when it has YAML front matter (the open DESIGN.md format), cite tokens by path (`{colors.primary}`, `{rounded.md}`) so the plan and the file share one vocabulary. If no DESIGN.md, flag the gap and recommend `/design-consultation`.
|
||||
Flag any new component — does it fit the existing vocabulary?
|
||||
Before offering a token-alignment fix, check whether an earlier pass already approved that outcome. If so, apply the established tokens and update every stale gap/reference under that decision; changing the plan location or spelling out the same fix is not a new issue. Ask again only if new evidence exposes an unresolved requirement or tradeoff, and name it. An unapproved violation still needs its first individual decision.
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 6: Responsive & Accessibility
|
||||
@@ -63,7 +90,9 @@ FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but int
|
||||
**STOP.** AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.
|
||||
|
||||
### Pass 7: Unresolved Design Decisions
|
||||
Surface ambiguities that will haunt implementation:
|
||||
Preserve accepted user-facing outcomes. Choosing implementation mechanics does not
|
||||
reopen them; ask only if a concrete constraint exposes a new design requirement
|
||||
or tradeoff. Surface the remaining ambiguities that will haunt implementation:
|
||||
```
|
||||
DECISION NEEDED | IF DEFERRED, WHAT HAPPENS
|
||||
-----------------------------|---------------------------
|
||||
@@ -77,6 +106,8 @@ Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Ed
|
||||
|
||||
### Post-Pass: Update Mockups (if generated)
|
||||
|
||||
After Pass 7: offer the mockup update below when applicable, resolve deferred TODO proposals, reconcile approvals, then synthesize tasks and the Completion Summary.
|
||||
|
||||
If mockups were generated in Step 0.5 and review passes changed significant design decisions (information architecture restructure, new states, layout changes), offer to regenerate (one-shot, not a loop):
|
||||
|
||||
AskUserQuestion: "The review passes changed [list major design changes]. Want me to regenerate mockups to reflect the updated plan? This ensures the visual reference matches what we're actually building."
|
||||
@@ -102,7 +133,11 @@ Design decisions considered and explicitly deferred, with one-line rationale eac
|
||||
Existing DESIGN.md, UI patterns, and components that the plan should reuse.
|
||||
|
||||
### TODOS.md updates
|
||||
After all review passes are complete, present each potential TODO as its own individual AskUserQuestion. Never batch TODOs — one per question. Never silently skip this step.
|
||||
Put implementation and verification of approved fixes in the plan tasks. Do not
|
||||
make in-scope verification an optional follow-up. Reserve deferred TODO proposals
|
||||
for unresolved/out-of-scope debt or a new scope decision or tradeoff. After the
|
||||
passes, ask about each such TODO individually; never batch. Honor explicit user
|
||||
deferrals. If none remain, say so.
|
||||
|
||||
For design debt: missing a11y, unresolved responsive behavior, deferred empty states. Each TODO gets:
|
||||
* **What:** One-line description of the work.
|
||||
@@ -114,9 +149,20 @@ For design debt: missing a11y, unresolved responsive behavior, deferred empty st
|
||||
|
||||
Then present options: **A)** Add to TODOS.md **B)** Skip — not valuable enough **C)** Build it now in this PR instead of deferring.
|
||||
|
||||
Before synthesizing tasks or the completion summary, perform the approval
|
||||
reconciliation from the Section self-check in `~/.claude/skills/gstack/plan-design-review/SKILL.md` (Read it if no longer in context). Export only agreed implementation work; retain unapproved remedies as pending findings.
|
||||
Count only individually approved new decisions in "Decisions made" and the
|
||||
review log; a proposed remedy or next-step answer contributes zero.
|
||||
|
||||
{{TASKS_SECTION_EMIT:design-review}}
|
||||
|
||||
### Completion Summary
|
||||
|
||||
**Overall design score:** use the lowest of the six rated pass scores (1-6),
|
||||
separately before and after approved fixes. Pass 7 is unscored. Keep Step 0's
|
||||
initial impression in its own row. An overall 8+ therefore means every rated
|
||||
pass is 8+; unresolved findings still prevent a clean review log.
|
||||
|
||||
```
|
||||
+====================================================================+
|
||||
| DESIGN PLAN REVIEW — COMPLETION SUMMARY |
|
||||
@@ -145,7 +191,7 @@ If all passes 8+: "Plan is design-complete. Run /design-review after implementat
|
||||
If any below 8: note what's unresolved and why (user chose to defer).
|
||||
|
||||
### Unresolved Decisions
|
||||
If any AskUserQuestion goes unanswered, note it here. Never silently default to an option.
|
||||
List every unresolved finding here, including a finding not yet asked or an unanswered AskUserQuestion. Never silently default to an option.
|
||||
|
||||
### Approved Mockups
|
||||
|
||||
@@ -212,7 +258,9 @@ plan mode alongside reviews. If this design review found visual issues that woul
|
||||
from exploring new directions, recommend /design-shotgun. If approved mockups exist and
|
||||
need to be turned into working HTML, recommend /design-html.
|
||||
|
||||
Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
Use AskUserQuestion to present the next step. Always include the manual/stop
|
||||
option E; offer only applicable follow-on skills. If the user chooses manual,
|
||||
finish without starting another skill:
|
||||
- **A)** Run /plan-eng-review next (required gate)
|
||||
- **B)** Run /plan-ceo-review (only if fundamental product gaps found)
|
||||
- **C)** Run /design-shotgun — explore visual design variants for issues found
|
||||
@@ -223,5 +271,5 @@ Use AskUserQuestion to present the next step. Include only applicable options:
|
||||
* NUMBER issues (1, 2, 3...) and LETTERS for options (A, B, C...).
|
||||
* Label with NUMBER + LETTER (e.g., "3A", "3B").
|
||||
* One sentence max per option.
|
||||
* After each pass, pause and wait for feedback.
|
||||
* Pause for each unresolved issue. If a pass has none, say so and continue; do not manufacture a question.
|
||||
* Rate before and after each pass for scannability.
|
||||
|
||||
Reference in New Issue
Block a user