review-sections.md

<!-- AUTO-GENERATED from review-sections.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Review Sections (7 passes, after scope is agreed)

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.

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:

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

Search for relevant learnings from previous sessions:

_CROSS_PROJ=$(~/.claude/skills/gstack/bin/gstack-config get cross_project_learnings 2>/dev/null || echo "unset")
echo "CROSS_PROJECT: $_CROSS_PROJ"
if [ "$_CROSS_PROJ" = "true" ]; then
  { _LE=$(~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 --cross-project 2>&1 >&3 3>&-); _LR=$?; } 3>&1
else
  { _LE=$(~/.claude/skills/gstack/bin/gstack-learnings-search --limit 10 2>&1 >&3 3>&-); _LR=$?; } 3>&1
fi
[ "$_LR" = 0 ] || { _LE=${_LE%%$'\n'*}; echo "LEARNINGS: unavailable (${_LE:-exit $_LR})"; }

If CROSS_PROJECT is unset (first time): Use AskUserQuestion:

gstack can search learnings from your other projects on this machine to find patterns that might apply here. This stays local (no data leaves your machine). Recommended for solo developers. Skip if you work on multiple client codebases where cross-contamination would be a concern.

Options:

• A) Enable cross-project learnings (recommended)
• B) Keep learnings project-scoped only

If A: run ~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings true If B: run ~/.claude/skills/gstack/bin/gstack-config set cross_project_learnings false

Then re-run the search with the appropriate flag.

If learnings are found, incorporate them into your analysis. When a review finding matches a past learning, display:

"Prior learning applied: [key] (confidence N/10, from [date])"

This makes the compounding visible. The user should see that gstack is getting smarter on their codebase over time.

Evaluate every pass using the plan and referenced existing contracts. An explicitly excluded artifact is not a missing requirement: assess the same dimension with permitted evidence. Reopen that exclusion only for a concrete design gap, and ask before changing it.

Pass protocol (1-6): Record the initial 0-10 score. Every FIX TO 10 below is a proposal: ask about each issue, wait for approval, then edit the plan and re-rate that pass with the reason for the score change. Never edit first and ask afterward.

A declined fix remains documented: the unresolved gap keeps the rating below 10. Carry each pass's before/after scores and remaining gaps into the Completion Summary below. Compute the overall score as specified in the Completion Summary; do not treat litmus answers or Pass 7's decision counts as numeric ratings. Pass 7 is the unscored decision register, not a seventh rating.

A faithful restatement of an existing or already approved contract, such as a wireframe of the unchanged layout, is review evidence rather than a new design choice. Record it directly; ask if producing it would introduce or change a design decision. Finish with the Required Outputs and terminal Plan File Review Report below, including any unanswered decisions.

Pass 1: Information Architecture

Rate 0-10: Does the plan define what the user sees first, second, third? FIX TO 10: Add information hierarchy to the plan. Include ASCII diagram of screen/page structure and navigation flow. Apply "constraint worship" — if you can only show 3 things, which 3? Persuade plan (a landing, marketing, pricing, waitlist, campaign or comparison page; the Pass 4 classifier): the plan settles each check below, or the gap is a Pass 1 finding. Ask the user for missing proof and risk terms; never invent them.

1. One primary action, named; nothing competes with it above the fold, and the closing CTA repeats it.
2. Named objections: the visitor's top objections, each answered where it arises (FAQ of real questions, comparison, guarantee).
3. Proof beside each claim: a supplied customer, quote or figure next to the claim it supports, never a metric row; an unsupported claim is cut or marked [Needs proof: …].
4. A risk reversal the business really offers (free plan, trial, no card, cancel anytime, refund); never an invented one.
5. An index/noindex decision: an ad-only or time-bound page is noindex; an indexed one has a real title and description, and its FAQ ships as FAQPage JSON-LD.

STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY. If no issues, say so and move on. Do NOT proceed until user responds.

Pass 2: Interaction State Coverage

Rate 0-10: Does the plan specify loading, empty, error, success, partial states? FIX TO 10: Add interaction state table to the plan:

  FEATURE              | LOADING | EMPTY | ERROR | SUCCESS | PARTIAL
  ---------------------|---------|-------|-------|---------|--------
  [each UI feature]    | [spec]  | [spec]| [spec]| [spec]  | [spec]

For each state: describe what the user SEES, not backend behavior. Empty states are features — specify warmth, primary action, context. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.

Pass 3: User Journey & Emotional Arc

Rate 0-10: Does the plan consider the user's emotional experience? 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?
  -----|------------------|-----------------|----------------
  1    | Lands on page    | [what emotion?] | [what supports it?]
  ...

Apply time-horizon design: 5-sec visceral, 5-min behavioral, 5-year reflective. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.

Pass 4: AI Slop Risk

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

Review these as UI requirements in the plan, approved mockups, and referenced existing contracts. Inspect pixels or computed values when a rendered surface is available; otherwise assess what the plan specifies and identify concrete gaps.

Classifier: name the mode before you apply the rules. 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.
• OPERATE (APP UI: dashboards, admin, settings, editors, tools) → they finish a task. Scanability and native expectations beat expression; the brand lives in the details. Apply App UI Rules.
• READ (docs, articles, guides, changelogs) → they understand something. Structure for comprehension, then make staying worth it. Apply Read Rules.
• EXPERIENCE (portfolios, galleries, showcases) → they are inside the work. The artifact owns the first viewport; the interface gets out of the way. Apply Experience Rules.
• HYBRID (marketing shell with app-like sections) → classify per section, not per page.

Hard rejection criteria (instant-fail patterns — flag if ANY apply):

1. Generic SaaS card grid as first impression
2. Beautiful image with weak brand
3. Strong headline with no clear action
4. Busy imagery behind text
5. Sections repeating same mood statement
6. Carousel with no narrative purpose
7. App UI made of stacked cards instead of layout

Litmus checks (answer YES/NO for each with evidence; compare with the outside-voice litmus scorecard when available. These support findings, not an additional numeric score):

1. Brand/product unmistakable in first screen?
2. One strong visual anchor present?
3. Page understandable by scanning headlines only?
4. Each section has one job?
5. Are cards actually necessary?
6. Does motion improve hierarchy or atmosphere?
7. Would design feel premium with all decorative shadows removed?

Landing page rules (apply when classifier = PERSUADE / MARKETING/LANDING):

• First viewport reads as one composition, not a dashboard
• Brand-first hierarchy: brand > headline > body > CTA
• Typography: expressive, purposeful — no default stacks (Inter, Roboto, Arial, system)
• No flat single-color backgrounds by default: texture from the brand or a real asset, never a halo, spotlight, stripe, or grid-paper gradient (see the AI Slop blacklist and detector rule ids below)
• Hero: full-bleed, edge-to-edge, no inset/tiled/rounded variants
• Hero budget: brand, one headline, one supporting sentence, one CTA group, one image
• No cards in hero. Cards only when card IS the interaction
• One job per section: one purpose, one headline, one short supporting sentence
• Motion: one authored moment on the first viewport (an entrance or a scroll-linked reveal), ease-out from a visible default; hover states only where they carry information
• Color: define CSS variables, avoid purple-on-white defaults, one accent color default
• Copy: product language not design commentary. "If deleting 30% improves it, keep deleting"
• Beautiful defaults: composition-first, brand as loudest text, two text faces max (plus a mono for data and code), cardless by default, first viewport as one composition, not a document (poster in stance, not in type size: display stays under 6rem)

App UI rules (apply when classifier = OPERATE / APP UI):

• Calm surface hierarchy, strong typography, few colors
• Dense but readable, minimal chrome
• Organize: primary workspace, navigation, secondary context, one accent
• Avoid: dashboard-card mosaics, thick borders, decorative gradients, ornamental icons
• Copy: utility language — orientation, status, action. Not mood/brand/aspiration
• Cards only when card IS the interaction
• Section headings state what area is or what user can do ("Selected KPIs", "Plan status")

Read rules (apply when classifier = READ):

• Measure 65-75ch, one reading column, headings closer to what follows than to what precedes
• Wayfinding is a feature: where am I, what is next, where do I search
• A docs index is Read, not Persuade: no hero, no CTA theater

Experience rules (apply when classifier = EXPERIENCE):

• The work fills the first viewport; chrome earns every pixel
• One authored transition, not a scroll-jacked tour
• Never crop the artifact to fit a template

Universal rules (apply to ALL types):

• Define CSS variables for color system
• No default font stacks as the display voice (Inter, Roboto, Arial, system); DM Sans, Instrument Sans, IBM Plex Sans are allowed for body/UI on an Operate or Read surface when the proposal explicitly assigns that role
• One job per section
• "If deleting 30% of the copy improves it, keep deleting"
• Cards earn their existence — no decorative card grids
• NEVER use small, low-contrast type (body text < 16px or contrast ratio < 4.5:1 on body text)
• NEVER put labels inside form fields as the only label (placeholder-as-label pattern — labels must be visible when the field has content)
• ALWAYS preserve visited vs unvisited link distinction (visited links must have a different color)
• NEVER float headings between paragraphs (heading must be visually closer to the section it introduces than to the preceding section)

Reflexes no detector catches (check by hand, every time):

• Browser surfaces carry the design. Selection color, caret, scrollbars, focus rings, underline offset, tabular numerals all ship with browser defaults that belong to no design system. Theme them from the palette. Cheapest tell that a page was designed rather than assembled, and the one models skip most.
• One authored motion moment. Not the same entrance on every section, not a hover effect on everything. Exponential ease-out from an already-visible default. Content never hides behind animation timing.
• Depth has an offset. Shadows are offset plus soft blur. A zero-offset colored halo is decoration, not depth.
• Secondary text on a colored surface is tinted from that hue. Never gray.
• More space above a heading than below it. Read the computed values.
• Light or dark comes from the use scene. Who, where, under what light: one sentence. Never from the category.

Calibration: the three looks. AI-built interfaces land in one of three looks no matter what the product is: (1) cream ground, high-contrast serif display, terracotta or signal-red accent; (2) near-black, one neon accent, glowing edges; (3) broadsheet hairlines, italic display serif, tiny tracked mono labels. Each is fine when the brief asks for it. If the brief left the look open and you landed in one anyway, you stopped looking. The test: could someone guess your look from the category alone? From "the category, but avoiding the obvious"? Either way, start over. "It's about books, so cream and a serif" fails this test. Book cloth and jackets come in every saturated color there is.

AI Slop blacklist (the 11 patterns that scream "AI-generated"):

1. Purple/violet/indigo gradient backgrounds or blue-to-purple color schemes
2. The 3-column feature grid: icon-in-colored-circle + bold title + 2-line description, repeated 3x symmetrically. THE most recognizable AI layout.
3. Icons in colored circles as section decoration (SaaS starter template look)
4. Centered everything (text-align: center on all headings, descriptions, cards)
5. Uniform bubbly border-radius on every element (same large radius on everything)
6. Decorative blobs, floating circles, wavy SVG dividers (if a section feels empty, it needs better content, not decoration)
7. Emoji as design elements (rockets in headings, emoji as bullet points)
8. Colored left-border on cards (border-left: 3px solid <accent>)
9. Generic hero copy ("Welcome to [X]", "Unlock the power of...", "Your all-in-one solution for...")
10. Cookie-cutter section rhythm (hero → 3 features → testimonials → pricing → CTA, every section same height)
11. system-ui or -apple-system as the PRIMARY display/body font — the "I gave up on typography" signal. Pick a real typeface.

Detector rule ids for the rest of the catalog (a [rule-id] in a finding is one of these): border-accent-on-rounded: Border accent on a rounded card; overused-font: Overused display font; flat-type-hierarchy: Flat type hierarchy; gradient-text: Gradient text; cream-palette: Cream default palette; nested-cards: Nested cards; monotonous-spacing: Monotonous spacing; bounce-easing: Bounce easing; pulsing-dot: Pulsing status dot; blinking-cursor: Blinking cursor effect; shape-assembled-illustration: Shape-assembled illustration; dark-glow: Dark-mode glow; radial-halo: Radial halo; radial-spotlight-glow: Radial spotlight glow; marquee: Logo marquee; icon-tile-stack: Icon tile above every heading; italic-serif-display: Italic serif display; hero-eyebrow-chip: Hero eyebrow chip; kicker-above-heading: Kicker above heading; numbered-section-labels: Numbered section labels; em-dash-overuse: Em-dash overuse; marketing-buzzword: Marketing buzzwords; aphoristic-cadence: Aphoristic cadence; oversized-h1: Oversized h1; extreme-negative-tracking: Extreme negative tracking; gpt-thin-border-wide-shadow: Thin border plus wide shadow; repeating-stripes-gradient: Repeating stripes gradient; codex-grid-background: Grid-paper background; theater-slop-phrase: Theater phrases; image-hover-transform: Image hover zoom. Judgment tells with no detector rule: gradient cta button, stock-photo hero, cards as the default component, generic testimonial section, left-text right-image hero, generic cta labels, hero metric template, identical card grids, glassmorphism, hand-drawn svg illustration, modal by default, monospace as costume, content stand-ins, mode picked by category, unthemed browser surfaces, missing states.

Source: OpenAI "Designing Delightful Frontends with GPT-5.4" (Mar 2026) + gstack design methodology.

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?
• "Clean, modern UI" → meaningless. Replace with actual design decisions.
• "Dashboard with widgets" → what makes this NOT every other dashboard?
• "Trusted by thousands", "99.9% uptime" → on a Persuade plan, supplied proof beside the claim (Pass 1, check 3), or no claim.

If visual mockups were generated in Step 0.5, evaluate them against the AI slop blacklist above. Read each mockup image using the Read tool. Does the mockup fall into generic patterns (3-column grid, centered hero, stock-photo feel)? If so, flag it and offer to regenerate with more specific direction via $D iterate --feedback "$(cat "$FEEDBACK_FILE")" (the feedback in a private file, never inline); use its printed outputPath for any later view, check or board. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.

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

Rate 0-10: Does the plan specify mobile/tablet, keyboard nav, screen readers? FIX TO 10: Add responsive specs per viewport — not "stacked on mobile" but intentional layout changes. Add a11y: keyboard nav patterns, ARIA landmarks, touch target sizes (44px min), color contrast requirements. STOP. AskUserQuestion once per issue. Do NOT batch. Recommend + WHY.

Pass 7: Unresolved Design Decisions

Start from unresolved choices recorded in earlier passes. For each new item, cite an actual in-scope element and the missing decision in the plan, source, DESIGN.md, or approved mockup. Page/section names and outside-review suggestions do not establish that a control exists. Check the available artifacts first; if its existence is unknown, keep the item conditional and state what must be verified. Do not invent controls or reopen accepted treatments for a hypothetical element. Surface real missing decisions and concrete conflicts; approval of one treatment does not settle a different known element.

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
  -----------------------------|---------------------------
  What does empty state look like? | Engineer ships "No items found."
  Mobile nav pattern?          | Desktop nav hides behind hamburger
  ...

If visual mockups were generated in Step 0.5, reference them as evidence when surfacing unresolved decisions. A mockup makes decisions concrete — e.g., "Your approved mockup shows a sidebar nav, but the plan doesn't specify mobile behavior. What happens to this sidebar on 375px?" Each decision = one AskUserQuestion with recommendation + WHY + alternatives. Edit the plan with each decision as it's made. STOP. Wait for each answer before editing or advancing. Record unanswered decisions as unresolved.

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."

If yes, use $D iterate with feedback summarizing the changes, or $D variants with an updated brief; either text goes in a brief or feedback file, never inline. Save to the same $_DESIGN_DIR directory; nothing is overwritten, so do round accounting and carry the printed paths into any new board (rebuild it with the board block, which rewrites board-images.json) or check.

How to ask questions

Follow the AskUserQuestion format from the Preamble above. Additional rules for plan design reviews:

• One issue = one AskUserQuestion call. Never combine multiple issues into one question. Each call contains exactly one question; multiple question tabs in one call are also batching. If a user could choose either remedy without choosing the other, ask separately, even when both affect the same component or token file. Shared implementation work does not make independent design choices inseparable.
• Describe the design gap concretely — what's missing, what the user will experience if it's not specified.
• Present 2-3 options. For each: effort to specify now, risk if deferred.
• Map to Design Principles above. One sentence connecting your recommendation to a specific principle.
• A gap with an "obvious fix" still needs the user's approval before it lands in the plan.
• Never use AskUserQuestion to ask which variant the user prefers. The comparison board ($D compare --serve) is the chooser; AskUserQuestion only says the board is open and waits.

Required Outputs

"NOT in scope" section

Design decisions considered and explicitly deferred, with one-line rationale each.

"What already exists" section

Existing DESIGN.md, UI patterns, and components that the plan should reuse.

TODOS.md updates

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, Why, Pros, Cons, Context (enough for someone in 3 months) and Depends on.

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 build-actionable tasks. Each task derives from a specific finding — no padding. Emit the markdown section AND write a JSONL artifact that /autoplan can aggregate across phases.

Markdown section (always emit)

## Implementation Tasks
Synthesized from this review's findings. Each task derives from a specific
finding above. Run with Claude Code or Codex; checkbox as you ship.

- [ ] **T1 (P1, human: ~2h / CC: ~15min)** — <component> — <imperative title>
  - Surfaced by: <section name> — <specific finding text or line reference>
  - Files: <paths to touch>
  - Verify: <test command or manual check>
- [ ] **T2 (P2, human: ~30min / CC: ~5min)** — ...

Rules:

• P1 blocks ship; P2 should land same branch; P3 is a follow-up TODO.
• If a finding produced no actionable task, do not invent one.
• If a section had zero findings, emit _No new tasks from <section>._
• Show human-team and CC+gstack effort estimates. Default task-type ratios (human ÷ CC time): scaffolding ~100x, tests ~50x, features ~30x, bug fix with regression ~20x, architecture ~5x, research ~3x. Adjust to the actual work and state the assumption.

JSONL artifact (always write, even if zero tasks)

/autoplan reads this file to aggregate across phases. Build each line with jq -nc so titles and source findings containing quotes, newlines, or backslashes serialize cleanly — never use hand-rolled echo / printf.

GSTACK_STATE_ROOT=$(~/.claude/skills/gstack/bin/gstack-paths --get GSTACK_STATE_ROOT); : "${GSTACK_STATE_ROOT:?gstack-paths failed; reinstall with ./setup or /gstack-upgrade}"
SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null)
TASKS_DIR="$GSTACK_STATE_ROOT/projects/${SLUG:-unknown}"
mkdir -p "$TASKS_DIR"
TASKS_FILE="$TASKS_DIR/tasks-design-review-$(date +%Y%m%d-%H%M%S).jsonl"
COMMIT=$(git rev-parse HEAD 2>/dev/null || echo unknown)
# The task record keeps the raw git branch; artifact filenames keep gstack-slug's sanitized BRANCH.
GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo unknown)
RUN_ID="$(date -u +%Y%m%dT%H%M%SZ)-$$"

# Repeat ONE jq invocation per task identified during this review.
# Substitute the placeholders inline with shell variables you set per task:
#   TASK_ID (T1, T2, ...), PRIORITY (P1/P2/P3), COMPONENT, TITLE,
#   SOURCE_FINDING, EFFORT_HUMAN, EFFORT_CC, FILES_JSON (a JSON array literal
#   like '["browse/src/sanitize.ts","browse/src/server.ts"]').
jq -nc \
  --arg phase 'design-review' \
  --arg run_id "$RUN_ID" \
  --arg branch "$GIT_BRANCH" \
  --arg commit "$COMMIT" \
  --arg id "$TASK_ID" \
  --arg priority "$PRIORITY" \
  --arg component "$COMPONENT" \
  --arg effort_human "$EFFORT_HUMAN" \
  --arg effort_cc "$EFFORT_CC" \
  --arg title "$TITLE" \
  --arg source_finding "$SOURCE_FINDING" \
  --argjson files "$FILES_JSON" \
  '{phase:$phase, run_id:$run_id, branch:$branch, commit:$commit, id:$id, priority:$priority, component:$component, files:$files, effort_human:$effort_human, effort_cc:$effort_cc, title:$title, source_finding:$source_finding}' \
  >> "$TASKS_FILE"

If jq is not installed, fall back to skipping the JSONL write and warn the user to install jq for autoplan aggregation. Never hand-roll JSONL.

If zero tasks were identified in this review, still touch the JSONL file (: > "$TASKS_FILE") so the aggregator sees that the phase produced output this run (an empty file means "ran, no findings" — distinct from "didn't run").

Completion Summary

Prepare this for the saved review; announce completion after the Read-back gate below. In the plan file, write it as its own ## Design Review Completion Summary section (the box, the deferred list and the Unresolved Decisions below) above the terminal ## GSTACK REVIEW REPORT, replacing this review's earlier one. Never write it inside the report: the next plan review deletes and regenerates everything under that heading.

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                    |
  +====================================================================+
  | System Audit         | [DESIGN.md status, UI scope]                |
  | Step 0               | [initial rating, focus areas]               |
  | Pass 1  (Info Arch)  | ___/10 → ___/10 after fixes                |
  | Pass 2  (States)     | ___/10 → ___/10 after fixes                |
  | Pass 3  (Journey)    | ___/10 → ___/10 after fixes                |
  | Pass 4  (AI Slop)    | ___/10 → ___/10 after fixes                |
  | Pass 5  (Design Sys) | ___/10 → ___/10 after fixes                |
  | Pass 6  (Responsive) | ___/10 → ___/10 after fixes                |
  | Pass 7  (Decisions)  | ___ resolved, ___ deferred                 |
  +--------------------------------------------------------------------+
  | NOT in scope         | written (___ items)                         |
  | What already exists  | written                                     |
  | TODOS.md updates     | ___ items proposed                          |
  | Approved Mockups     | ___ generated, ___ approved                  |
  | Decisions made       | ___ added to plan                           |
  | Decisions deferred   | ___ (listed below)                          |
  | Overall design score | ___/10 → ___/10                             |
  +====================================================================+

After Read-back, if all passes 8+: "Plan is design-complete. Run /design-review after implementation for visual QA." If any below 8: note what's unresolved and why (user chose to defer).

Unresolved Decisions

List every unresolved finding here, including a finding not yet asked or an unanswered AskUserQuestion. Never silently default to an option.

Approved Mockups

If visual mockups were generated during this review, add to the plan file:

## Approved Mockups

| Screen/Section | Mockup Path | Direction | Notes |
|----------------|-------------|-----------|-------|
| [screen name]  | [absolute $_DESIGN_DIR]/[filename].png | [brief description] | [constraints from review] |

Use the full path of each chosen variant. Omit this section when no mockups were generated.

Plan File Review Report

Save the accepted plan changes and full review output, including the report below, before logging or announcing completion.

Detect the plan file

Use an explicitly requested output/report file first. Otherwise use the reviewed plan named by the user, then the host active plan. If no file is in scope, skip this section; ordinary no-file review logging still applies.

Generate the report

Run ~/.claude/skills/gstack/bin/gstack-review-read for prior review entries. Use the current Completion Summary or DX Scorecard for this review's status and findings; apply the Review Log field rules below and add exactly one to its prior run count. Do not pre-log this run to populate the report. Use prior entries for other reviews, retaining their status, attribution and freshness.

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" → If scope fields are 0 or missing (HOLD/REDUCTION mode): "mode: {mode}, {critical_gaps} critical gaps"
• plan-eng-review: \status\, \unresolved\, \critical_gaps\, \issues_found\, \mode\, \commit\ → Findings: "{issues_found} issues, {critical_gaps} critical gaps"
• plan-design-review: \status\, \initial_score\, \overall_score\, \unresolved\, \decisions_made\, \commit\ → Findings: "score: {initial_score}/10 → {overall_score}/10, {decisions_made} decisions"
• plan-devex-review: \status\, \initial_score\, \overall_score\, \product_type\, \tthw_current\, \tthw_target\, \mode\, \persona\, \competitive_tier\, \unresolved\, \commit\ → Findings: "score: {initial_score}/10 → {overall_score}/10, TTHW: {tthw_current} → {tthw_target}"
• devex-review: \status\, \overall_score\, \product_type\, \tthw_measured\, \dimensions_tested\, \dimensions_inferred\, \boomerang\, \commit\ → Findings: "score: {overall_score}/10, TTHW: {tthw_measured}, {dimensions_tested} tested/{dimensions_inferred} inferred"
• codex-review: \status\, \gate\, \findings\, \findings_fixed\ → Findings: "{findings} findings, {findings_fixed}/{findings} fixed"

The current row and its later log must describe the same saved review.

Produce this markdown table:

\\\`markdown

GSTACK REVIEW REPORT

\\\`

Below the table, add these lines. OUTSIDE COVERAGE and CROSS-MODEL are conditional: include them when the phase ran, was disabled/skipped/unavailable, or has findings; omit them only when no such phase applies. VERDICT is always present:

• 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".

Unresolved-decisions status (MANDATORY — never omitted; the report's final non-whitespace line). After VERDICT, end the report (content under the \## GSTACK REVIEW REPORT\ heading — a bold label, never a new \## \ heading; exempt from the "omit when empty" rule) with exactly one: the exact unbolded line \NO UNRESOLVED DECISIONS\ (a bolded one does NOT count), OR a \**UNRESOLVED DECISIONS:**\ header + one bullet per open item (last bullet = final line; add \+ N unresolved from prior reviews\ only when N > 0). This avoids double-counting: list THIS review's open items from context; for prior reviews sum \unresolved\ over the latest fresh row per skill (dashboard 7-day window) after you DROP the current skill's row; emit the sentinel only when both are zero.

Write to the plan file

PLAN MODE EXCEPTION — ALWAYS RUN: Save the complete reviewed plan/report with only accepted changes applied; keep unresolved choices pending.

The report must always be the LAST section of the plan file — never mid-file. Use a single delete-then-append flow:

1. Read the existing plan/report, if present. Preserve its content and apply only accepted changes; include the full review output. Locate any existing ## GSTACK REVIEW REPORT section.
2. If found, use the Edit tool to DELETE the entire existing section. Match from \## GSTACK REVIEW REPORT\ through either the next \## \ heading or end of file, whichever comes first. Replace with the empty string. This applies regardless of where the section currently lives — mid-file deletion is intentional, not a special case. If the Edit fails (e.g., concurrent edit changed the content), re-read the plan file and retry once.
3. If a report was deleted, Read the updated file. Append the new \## GSTACK REVIEW REPORT\ at EOF. Use Edit to match the suffix confirmed by the latest Read, or Write the full file with the report last. Append whether or not a prior report existed. "Unresolved Decisions" is not an EOF anchor when other sections follow it.
4. Read-back gate: Read the saved file. Verify the accepted changes, full review output, current review row, verdict and final unresolved-decisions status, with ## GSTACK REVIEW REPORT as the last section. If writing or verification fails, report the error and stop before Review Log or decision logging.

Do NOT replace the section in place; delete it and append the new report at EOF, so the review report is always the plan's last section.

Review Log

When a plan/report file is in scope, persist only after its successful write and Read-back above. On failure, report the error and stop; do not log completion or an accepted decision. PLAN MODE EXCEPTION — ALWAYS RUN after verification: these commands write review metadata to ~/.gstack/; the following dashboard reads the saved result.

~/.claude/skills/gstack/bin/gstack-review-log '{"skill":"plan-design-review","timestamp":"TIMESTAMP","status":"STATUS","initial_score":N,"overall_score":N,"unresolved":N,"decisions_made":N,"commit":"COMMIT"}'

Substitute values from the Completion Summary:

• TIMESTAMP: current ISO 8601 datetime
• STATUS: "clean" if overall score 8+ AND 0 unresolved; otherwise "issues_open"
• initial_score: initial overall design score before fixes (0-10)
• overall_score: final overall design score after fixes (0-10)
• unresolved: number of unresolved design decisions
• decisions_made: number of design decisions added to the plan
• COMMIT: output of git rev-parse --short HEAD

Review Readiness Dashboard

After completing the review, read the review log and config to display the dashboard.

~/.claude/skills/gstack/bin/gstack-review-read

1. Choose the records to display. Use the latest record for each row below. Do not use a record older than 7 days to clear a row, and never substitute an older success for a newer failure. Ship metrics are not review records.

Keep each record's host, source, outside_provider, outside_status and phase. Historical source "claude" is a native subagent; "claude-code" is the external CLI. Do not infer old providers or unknown models from today's harness. A native result does not fill missing, disabled or skipped outside coverage.

Source attribution: Append a recorded via to the suffix ("CLEAR (PLAN via /autoplan)"); without one, keep "CLEAR (PLAN)" or "CLEAR (DIFF)". Below the dashboard, group autoplan-voices and design-outside-voices by workflow run and phase. Show each phase's provider and outside_status; retain partial coverage. These details do not clear Eng Review.

2. Check freshness before choosing a verdict.

• Content-first rule: For review, adversarial-review, codex-review, ship-stage reviews and design-review-lite, use review_freshness.status and show its reason. CURRENT means a completed clean review whose start and end content fingerprints equal the current ---WTREE--- fingerprint. STALE or UNVERIFIED cannot clear Eng Review. Missing review_freshness, including legacy log-only records, means UNVERIFIED. Never fall back to HEAD equality or commit distance for diff evidence, even at zero commits. Show recorded cycles, completed/converged fields and missing source/phase coverage. Unknown coverage is not a pass.
• Plan records (plan-ceo-review, plan-eng-review, plan-design-review and codex-plan-review) use the 7-day window, not the working-tree fingerprint. If plan_sha256 is present, you may compare the plan file and report a mismatch. Compare the recorded commit with ---HEAD---; if different, run git rev-list --count STORED_COMMIT..HEAD and report "Note: {skill} review from {date} may be stale — {N} commits since review". A failed command means UNKNOWN, treated as stale; without commit tracking, suggest a re-run. Omit notes when all reviews are current.

3. Choose the historical verdict. CLEARED requires the selected Eng Review to be clean, within 7 days and fresh under step 2. Otherwise report NOT CLEARED and its missing, stale or open-issue reason. If skip_eng_review is true, show "SKIPPED (global)" for Eng Review and CLEARED for this dashboard. Eng Review is required by default; gstack-config set skip_eng_review true disables that requirement.

Other rows provide context, not a substitute for Eng Review:

• Recommend CEO Review for product/business or scope decisions, not routine fixes or cleanup.
• Recommend Design Review for UI/UX work, not backend, infrastructure or prompt-only work.
• Adversarial review always includes a native pass. Available, enabled outside challenges supplement it; diffs of 200+ lines also get the structured P1 gate.
• Outside Voice is the default-on plan review after CEO/Eng review. codex_reviews disables that extra step. Provider failure uses native fallback and records missing outside coverage; this dashboard row never gates shipping.

4. Display the dashboard. Show missing, stale, disabled or unavailable results explicitly, never as CLEAR. Display a fresh clean result as CLEAR and issues_open as ISSUES OPEN without changing the stored status.

+====================================================================+
|                    REVIEW READINESS DASHBOARD                       |
+====================================================================+
| Review          | Runs | Last Run            | Status    | Required |
|-----------------|------|---------------------|-----------|----------|
| Eng Review      |  1   | 2026-03-16 15:00    | CLEAR     | YES      |
| CEO Review      |  0   | —                   | —         | no       |
| Design Review   |  0   | —                   | —         | no       |
| Adversarial     |  0   | —                   | —         | no       |
| Outside Voice   |  0   | —                   | —         | no       |
+--------------------------------------------------------------------+
| VERDICT: CLEARED — Eng Review passed                                |
+====================================================================+

Capture Learnings

If you discovered a non-obvious pattern, pitfall, or architectural insight during this session, log it for future sessions:

~/.claude/skills/gstack/bin/gstack-learnings-log '{"skill":"plan-design-review","type":"TYPE","key":"SHORT_KEY","insight":"DESCRIPTION","confidence":N,"source":"SOURCE","files":["path/to/relevant/file"]}'

Types: pattern (reusable approach), pitfall (what NOT to do), preference (user stated), architecture (structural decision), tool (library/framework insight), operational (project environment/CLI/workflow knowledge).

Sources: observed (you found this in the code), user-stated (user told you), inferred (AI deduction), cross-model (both Claude and Codex agree).

Confidence: 1-10. Be honest. An observed pattern you verified in the code is 8-9. An inference you're not sure about is 4-5. A user preference they explicitly stated is 10.

files: Include the specific file paths this learning references. This enables staleness detection: if those files are later deleted, the learning can be flagged.

Only log genuine discoveries. Don't log obvious things. Don't log things the user already knows. A good test: would this insight save time in a future session? If yes, log it.

Brain Calibration Write-Back (gated)

Skip unless BRAIN_CALIBRATION_WRITEBACK is set and the preamble/brain-health output or gstack config shows brain_trust_policy@<endpoint-hash>=personal. If unknown, skip. If both gates pass, record one durable typed prediction with mcp__gbrain__takes_add; if unavailable, use mcp__gbrain__put_page with a gstack:takes fence block.

Take frontmatter:

kind: bet
holder: <user identity from whoami>
claim: <one-line prediction the skill is making>
weight: 0.5
since_date: <today's date>
expected_resolution: <date in 1-3 months depending on skill>
source_skill: plan-design-review

After write, invalidate affected digests:

SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null) || true
  ~/.claude/skills/gstack/bin/gstack-brain-cache invalidate brand --project "$SLUG" 2>/dev/null || true

Brain Cache Background Refresh

After the skill's work completes (and telemetry has logged), kick a background refresh of any cache digest that's getting close to its TTL. This is non-blocking — the user doesn't wait. Next invocation benefits from the warm cache.

SLUG=$(~/.claude/skills/gstack/bin/gstack-slug --get SLUG 2>/dev/null) || true
(~/.claude/skills/gstack/bin/gstack-brain-cache refresh --project "$SLUG" 2>/dev/null &) || true

Next Steps — Review Chaining

From the dashboard output, recommend the next review(s):

• /plan-eng-review unless skip_eng_review is true: it is the required shipping gate. Stress it when this review added flows or changed the information architecture; an eng review whose commit predates this review is stale and should be re-run.
• /plan-ceo-review only for fundamental product gaps (initial score below 4/10, major IA problems, or doubt about the problem itself) and no CEO review exists. Most design reviews should not trigger it. If both apply, eng review first.
• /design-shotgun for visual issues worth exploring; /design-html when approved mockups need HTML. Both produce design artifacts, so they fit plan mode.

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
• D) Run /design-html — generate Pretext-native HTML from approved mockups
• E) Skip — I'll handle next steps manually

Formatting Rules

• Number issues and letter options; label each option NUMBER + LETTER ("3A", "3B").
• One sentence max per option.
• 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.