Skip to content

Commit 0933c8d

Browse files
fix: update all stale Outside Voice references to include Gemini fallback chain
Updated Outside Voice description in Review Readiness Dashboard sections across plan-eng-review, plan-ceo-review, ship, plan-design-review, and design-review SKILL.md files to reflect the new fallback chain: Codex → Gemini (gemini-3.1-pro-preview) → Claude subagent.
1 parent dc5e053 commit 0933c8d

5 files changed

Lines changed: 241 additions & 39 deletions

File tree

design-review/SKILL.md

Lines changed: 116 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -910,16 +910,119 @@ Record baseline design score and AI slop score at end of Phase 6.
910910

911911
## Design Outside Voices (parallel)
912912

913-
**Automatic:** Outside voices run automatically when Codex is available. No opt-in needed.
913+
**Automatic:** Outside voices run automatically when Codex or Gemini is available. No opt-in needed.
914914

915-
**Check Codex availability:**
915+
**Check tool availability:**
916916
```bash
917917
which codex 2>/dev/null && echo "CODEX_AVAILABLE" || echo "CODEX_NOT_AVAILABLE"
918+
which gemini 2>/dev/null && echo "GEMINI_AVAILABLE" || echo "GEMINI_NOT_AVAILABLE"
918919
```
919920

920-
**If Codex is available**, launch both voices simultaneously:
921+
Launch all available voices simultaneously:
921922

922-
1. **Codex design voice** (via Bash):
923+
1. **Gemini visual voice** (PRIORITY — via Bash, if GEMINI_AVAILABLE):
924+
925+
Gemini 3.1 Pro has the strongest multimodal vision of any model. Use it as the **primary visual reviewer** — feed actual screenshots from Phase 1 and Phase 3 directly to Gemini for pixel-level design analysis. This catches issues that source-code-only reviewers miss: visual hierarchy balance, whitespace rhythm, color harmony, compositional weight, and AI slop patterns.
926+
927+
**Collect screenshots from previous phases:**
928+
```bash
929+
SCREENSHOTS=$(find "$REPORT_DIR/screenshots" -name "*.png" -type f 2>/dev/null | head -5)
930+
if [ -z "$SCREENSHOTS" ]; then
931+
echo "NO_SCREENSHOTS"
932+
else
933+
echo "SCREENSHOTS_FOUND: $(echo "$SCREENSHOTS" | wc -l | tr -d ' ')"
934+
fi
935+
```
936+
937+
**If screenshots exist**, feed them to Gemini for visual analysis:
938+
```bash
939+
TMPERR_GM_VISUAL=$(mktemp /tmp/gemini-visual-XXXXXXXX)
940+
TMPOUT_GM_VISUAL=$(mktemp /tmp/gemini-visual-out-XXXXXXXX)
941+
942+
# Build the image args for gemini CLI
943+
IMG_ARGS=""
944+
for img in $SCREENSHOTS; do
945+
IMG_ARGS="$IMG_ARGS --image $img"
946+
done
947+
948+
gemini --model gemini-3.1-pro-preview $IMG_ARGS \
949+
"You are a world-class product designer doing a VISUAL audit of these screenshots. You are looking at the RENDERED output, not source code. Evaluate what you SEE:
950+
951+
VISUAL HIERARCHY & COMPOSITION:
952+
- Where does the eye land first? Is that intentional?
953+
- Is there clear primary > secondary > tertiary hierarchy?
954+
- White space rhythm: intentional or accidental gaps?
955+
- Squint test: does the layout hold when blurred?
956+
- Compositional weight: balanced or lopsided?
957+
958+
COLOR & HARMONY:
959+
- Is the palette cohesive across all screenshots?
960+
- Contrast ratios: any text barely readable?
961+
- Semantic color usage: red=error, green=success consistent?
962+
- Dark mode: surfaces use elevation, not just inverted?
963+
964+
TYPOGRAPHY AS RENDERED:
965+
- Type scale feels systematic or random?
966+
- Line lengths readable (45-75 chars)?
967+
- Font pairing: complementary or competing?
968+
- Heading hierarchy visually clear?
969+
970+
SPACING & RHYTHM:
971+
- Grid alignment: everything snaps or drifts?
972+
- Consistent padding/margin rhythm?
973+
- Border-radius hierarchy or uniform bubbly?
974+
- Inner radius = outer radius - gap on nested elements?
975+
976+
AI SLOP DETECTION (the 10 anti-patterns — visual check):
977+
1. Purple/violet gradient backgrounds?
978+
2. The 3-column feature grid with icon circles?
979+
3. Icons in colored circles as decoration?
980+
4. Centered everything?
981+
5. Uniform bubbly border-radius on all elements?
982+
6. Decorative blobs, floating circles, wavy dividers?
983+
7. Emoji as design elements?
984+
8. Colored left-border on cards?
985+
9. Generic hero copy ('Welcome to...', 'Unlock the power...')?
986+
10. Cookie-cutter section rhythm?
987+
988+
RESPONSIVE (if mobile/tablet screenshots present):
989+
- Mobile layout intentional or just stacked desktop?
990+
- Touch targets >= 44px?
991+
- Navigation appropriate for viewport?
992+
993+
For each finding: describe WHAT you see, WHY it's a problem, and HOW to fix it. Rate severity: critical/high/medium/polish.
994+
995+
LITMUS CHECKS — answer YES/NO based on what you SEE:
996+
1. Brand/product unmistakable in first screen?
997+
2. One strong visual anchor present?
998+
3. Page understandable by scanning headlines only?
999+
4. Each section has one job?
1000+
5. Are cards actually necessary?
1001+
6. Does motion feel intentional (or absent)?
1002+
7. Would design feel premium with all decorative shadows removed?" \
1003+
> "$TMPOUT_GM_VISUAL" 2>"$TMPERR_GM_VISUAL"
1004+
```
1005+
1006+
Use a 5-minute timeout (`timeout: 300000`). After the command completes:
1007+
```bash
1008+
cat "$TMPOUT_GM_VISUAL"
1009+
cat "$TMPERR_GM_VISUAL" && rm -f "$TMPERR_GM_VISUAL" "$TMPOUT_GM_VISUAL"
1010+
```
1011+
1012+
**If no screenshots exist** (Phase 1/3 not yet run), fall back to source-code visual heuristics:
1013+
```bash
1014+
echo "No screenshots available yet — Gemini visual voice deferred to post-Phase 3."
1015+
```
1016+
1017+
Present output under a `GEMINI SAYS (visual audit — pixel-level):` header.
1018+
1019+
**Error handling (non-blocking):**
1020+
- Auth failure: "Gemini auth failed. Check your API key configuration."
1021+
- Timeout: "Gemini timed out after 5 minutes."
1022+
- Empty response: "Gemini returned no response."
1023+
- On any Gemini error: proceed with Codex and/or Claude subagent output only.
1024+
1025+
2. **Codex design voice** (via Bash, if CODEX_AVAILABLE — source-code audit):
9231026
```bash
9241027
TMPERR_DESIGN=$(mktemp /tmp/codex-design-XXXXXXXX)
9251028
codex exec "Review the frontend source code in this repo. Evaluate against these design hard rules:
@@ -958,7 +1061,7 @@ Use a 5-minute timeout (`timeout: 300000`). After the command completes, read st
9581061
cat "$TMPERR_DESIGN" && rm -f "$TMPERR_DESIGN"
9591062
```
9601063

961-
2. **Claude design subagent** (via Agent tool):
1064+
3. **Claude design subagent** (via Agent tool — consistency patterns):
9621065
Dispatch a subagent with this prompt:
9631066
"Review the frontend source code in this repo. You are an independent senior product designer doing a source-code design audit. Focus on CONSISTENCY PATTERNS across files rather than individual violations:
9641067
- Are spacing values systematic across the codebase?
@@ -972,22 +1075,25 @@ For each finding: what's wrong, severity (critical/high/medium), and the file:li
9721075
- **Auth failure:** If stderr contains "auth", "login", "unauthorized", or "API key": "Codex authentication failed. Run `codex login` to authenticate."
9731076
- **Timeout:** "Codex timed out after 5 minutes."
9741077
- **Empty response:** "Codex returned no response."
975-
- On any Codex error: proceed with Claude subagent output only, tagged `[single-model]`.
976-
- If Claude subagent also fails: "Outside voices unavailable — continuing with primary review."
1078+
- On any Codex error: proceed with Gemini and/or Claude subagent output only.
1079+
- On any Gemini error: proceed with Codex and/or Claude subagent output only.
1080+
- If all outside voices fail: "Outside voices unavailable — continuing with primary review."
9771081

1082+
Present Gemini output under a `GEMINI SAYS (visual audit — pixel-level):` header.
9781083
Present Codex output under a `CODEX SAYS (design source audit):` header.
9791084
Present subagent output under a `CLAUDE SUBAGENT (design consistency):` header.
9801085

9811086
**Synthesis — Litmus scorecard:**
9821087

983-
Use the same scorecard format as /plan-design-review (shown above). Fill in from both outputs.
984-
Merge findings into the triage with `[codex]` / `[subagent]` / `[cross-model]` tags.
1088+
Use the same scorecard format as /plan-design-review (shown above). Fill in from all outputs.
1089+
Gemini's visual litmus checks take PRIORITY for visual dimensions (hierarchy, composition, color, spacing) because it evaluates the rendered output, not source code.
1090+
Merge findings into the triage with `[gemini-visual]` / `[codex]` / `[subagent]` / `[cross-model]` tags.
9851091

9861092
**Log the result:**
9871093
```bash
9881094
~/.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)"'"}'
9891095
```
990-
Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable".
1096+
Replace STATUS with "clean" or "issues_found", SOURCE with "gemini+codex+subagent", "gemini+subagent", "gemini+codex", "codex+subagent", "gemini-only", "codex-only", "subagent-only", or "unavailable".
9911097

9921098
## Phase 7: Triage
9931099

plan-ceo-review/SKILL.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1240,7 +1240,7 @@ Parse the output. Find the most recent entry for each skill (plan-ceo-review, pl
12401240
- **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.
12411241
- **Design Review (optional):** Use your judgment. Recommend it for UI/UX changes. Skip for backend-only, infra, or prompt-only changes.
12421242
- **Adversarial Review (automatic):** Auto-scales by diff size. Small diffs (<50 lines) skip adversarial. Medium diffs (50–199) get cross-model adversarial. Large diffs (200+) get all 4 passes: Claude structured, Codex structured, Claude adversarial subagent, Codex adversarial. No configuration needed.
1243-
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Falls back to Claude subagent if Codex is unavailable. Never gates shipping.
1243+
- **Outside Voice (optional):** Independent plan review from a different AI model. Offered after all review sections complete in /plan-ceo-review and /plan-eng-review. Fallback chain: Codex → Gemini (gemini-3.1-pro-preview) → Claude subagent. Never gates shipping.
12441244

12451245
**Verdict logic:**
12461246
- **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\`)

0 commit comments

Comments
 (0)