From adbdfa73af81ef34165dbb1cbc89aed229439f9c Mon Sep 17 00:00:00 2001 From: MaruPelkar Date: Mon, 30 Mar 2026 22:41:48 -0700 Subject: [PATCH] feat(design-review): add Phase 7 Cognitive Load (S1/S2) audit Every audited screen gets rated on a System 1 / System 2 scale (0-10), grounded in browse data already collected. Screens scoring above 3 that aren't intentional friction get flagged with specific UX law violations (Fitts, Hick, Jakob, Miller, Peak-End, Von Restorff, Zeigarnik, Gestalt, Motivation) and the measurement that proves it. Displayed as ASCII slider. Renumbers existing phases 7-11 to 8-12 and updates all cross-references. Co-Authored-By: Claude Opus 4.6 (1M context) --- design-review/SKILL.md | 50 ++++++++++++++++++++++++++----------- design-review/SKILL.md.tmpl | 50 ++++++++++++++++++++++++++----------- 2 files changed, 70 insertions(+), 30 deletions(-) diff --git a/design-review/SKILL.md b/design-review/SKILL.md index 3be5a7c41..de0b544b4 100644 --- a/design-review/SKILL.md +++ b/design-review/SKILL.md @@ -1134,6 +1134,26 @@ Record baseline design score and AI slop score at end of Phase 6. --- +## Phase 7: Cognitive Load (S1/S2) + +Rate every audited screen on a System 1 ↔ System 2 scale (0-10). Ground scores in browse data already collected: element counts from `snapshot -i`, link counts from `links`, load times from `perf`. + +Every screen should be S1 (0-3). Exceptions: destructive actions (delete account), financial decisions, etc. + +Display as ASCII slider. For any screen above 3 that isn't intentional friction, name which UX laws it breaks (Fitts, Hick, Jakob, Miller, Peak-End, Von Restorff, Zeigarnik, Gestalt, Motivation) and the measurement that proves it: + +``` +Landing S1 |--●-------| S2 [2/10] ✓ +Onboarding S1 |-●--------| S2 [1/10] ✓ +Dashboard S1 |-------●--| S2 [7/10] ✗ Hick (31 items, no filter), Miller (93 data points), Gestalt (no grouping) +Settings S1 |----●-----| S2 [4/10] ✗ Hick (23 toggles on one page) +Delete Account S1 |--------●-| S2 [8/10] ✓ (intentional friction) +``` + +After the slider, list one concise issue per broken screen with the law references in parentheses. Include the slider and issues in the Phase 11 report. + +--- + ## Output Structure ``` @@ -1236,7 +1256,7 @@ Merge findings into the triage with `[codex]` / `[subagent]` / `[cross-model]` t ``` Replace STATUS with "clean" or "issues_found", SOURCE with "codex+subagent", "codex-only", "subagent-only", or "unavailable". -## Phase 7: Triage +## Phase 8: Triage Sort all discovered findings by impact, then decide which to fix: @@ -1248,11 +1268,11 @@ Mark findings that cannot be fixed from source code (e.g., third-party widget is --- -## Phase 8: Fix Loop +## Phase 9: Fix Loop For each fixable finding, in impact order: -### 8a. Locate source +### 9a. Locate source ```bash # Search for CSS classes, component names, style files @@ -1263,7 +1283,7 @@ For each fixable finding, in impact order: - ONLY modify files directly related to the finding - Prefer CSS/styling changes over structural component changes -### 8a.5. Target Mockup (if DESIGN_READY) +### 9a.5. Target Mockup (if DESIGN_READY) If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like: @@ -1275,7 +1295,7 @@ Show the user: "Here's the current state (screenshot) and here's what it should This step is optional — skip for trivial CSS fixes (wrong hex color, missing padding value). Use it for findings where the intended design isn't obvious from the description alone. -### 8b. Fix +### 9b. Fix - Read the source code, understand the context - Make the **minimal fix** — smallest change that resolves the design issue @@ -1283,7 +1303,7 @@ This step is optional — skip for trivial CSS fixes (wrong hex color, missing p - CSS-only changes are preferred (safer, more reversible) - Do NOT refactor surrounding code, add features, or "improve" unrelated things -### 8c. Commit +### 9c. Commit ```bash git add @@ -1293,7 +1313,7 @@ git commit -m "style(design): FINDING-NNN — short description" - One commit per fix. Never bundle multiple fixes. - Message format: `style(design): FINDING-NNN — short description` -### 8d. Re-test +### 9d. Re-test Navigate back to the affected page and verify the fix: @@ -1306,13 +1326,13 @@ $B snapshot -D Take **before/after screenshot pair** for every fix. -### 8e. Classify +### 9e. Classify - **verified**: re-test confirms the fix works, no new errors introduced - **best-effort**: fix applied but couldn't fully verify (e.g., needs specific browser state) - **reverted**: regression detected → `git revert HEAD` → mark finding as "deferred" -### 8e.5. Regression Test (design-review variant) +### 9e.5. Regression Test (design-review variant) Design fixes are typically CSS-only. Only generate regression tests for fixes involving JavaScript behavior changes — broken dropdowns, animation failures, conditional rendering, @@ -1320,11 +1340,11 @@ interactive state issues. For CSS-only fixes: skip entirely. CSS regressions are caught by re-running /design-review. -If the fix involved JS behavior: follow the same procedure as /qa Phase 8e.5 (study existing +If the fix involved JS behavior: follow the same procedure as /qa Phase 9e.5 (study existing test patterns, write a regression test encoding the exact bug condition, run it, commit if passes or defer if fails). Commit format: `test(design): regression test for FINDING-NNN`. -### 8f. Self-Regulation (STOP AND EVALUATE) +### 9f. Self-Regulation (STOP AND EVALUATE) Every 5 fixes (or after any revert), compute the design-fix risk level: @@ -1344,7 +1364,7 @@ DESIGN-FIX RISK: --- -## Phase 9: Final Design Audit +## Phase 10: Final Design Audit After all fixes are applied: @@ -1355,7 +1375,7 @@ After all fixes are applied: --- -## Phase 10: Report +## Phase 11: Report Write the report to `$REPORT_DIR` (already set up in the setup phase): @@ -1385,7 +1405,7 @@ Write a one-line summary to `~/.gstack/projects/{slug}/{user}-{branch}-design-au --- -## Phase 11: TODOS.md Update +## Phase 12: TODOS.md Update If the repo has a `TODOS.md`: @@ -1398,7 +1418,7 @@ If the repo has a `TODOS.md`: 11. **Clean working tree required.** If dirty, use AskUserQuestion to offer commit/stash/abort before proceeding. 12. **One commit per fix.** Never bundle multiple design fixes into one commit. -13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files. +13. **Only modify tests when generating regression tests in Phase 9e.5.** Never modify CI configuration. Never modify existing tests — only create new test files. 14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately. 15. **Self-regulate.** Follow the design-fix risk heuristic. When in doubt, stop and ask. 16. **CSS-first.** Prefer CSS/styling changes over structural component changes. CSS-only changes are safer and more reversible. diff --git a/design-review/SKILL.md.tmpl b/design-review/SKILL.md.tmpl index de57c217b..3fdd5a0f8 100644 --- a/design-review/SKILL.md.tmpl +++ b/design-review/SKILL.md.tmpl @@ -107,6 +107,26 @@ Record baseline design score and AI slop score at end of Phase 6. --- +## Phase 7: Cognitive Load (S1/S2) + +Rate every audited screen on a System 1 ↔ System 2 scale (0-10). Ground scores in browse data already collected: element counts from `snapshot -i`, link counts from `links`, load times from `perf`. + +Every screen should be S1 (0-3). Exceptions: destructive actions (delete account), financial decisions, etc. + +Display as ASCII slider. For any screen above 3 that isn't intentional friction, name which UX laws it breaks (Fitts, Hick, Jakob, Miller, Peak-End, Von Restorff, Zeigarnik, Gestalt, Motivation) and the measurement that proves it: + +``` +Landing S1 |--●-------| S2 [2/10] ✓ +Onboarding S1 |-●--------| S2 [1/10] ✓ +Dashboard S1 |-------●--| S2 [7/10] ✗ Hick (31 items, no filter), Miller (93 data points), Gestalt (no grouping) +Settings S1 |----●-----| S2 [4/10] ✗ Hick (23 toggles on one page) +Delete Account S1 |--------●-| S2 [8/10] ✓ (intentional friction) +``` + +After the slider, list one concise issue per broken screen with the law references in parentheses. Include the slider and issues in the Phase 11 report. + +--- + ## Output Structure ``` @@ -129,7 +149,7 @@ Record baseline design score and AI slop score at end of Phase 6. {{DESIGN_OUTSIDE_VOICES}} -## Phase 7: Triage +## Phase 8: Triage Sort all discovered findings by impact, then decide which to fix: @@ -141,11 +161,11 @@ Mark findings that cannot be fixed from source code (e.g., third-party widget is --- -## Phase 8: Fix Loop +## Phase 9: Fix Loop For each fixable finding, in impact order: -### 8a. Locate source +### 9a. Locate source ```bash # Search for CSS classes, component names, style files @@ -156,7 +176,7 @@ For each fixable finding, in impact order: - ONLY modify files directly related to the finding - Prefer CSS/styling changes over structural component changes -### 8a.5. Target Mockup (if DESIGN_READY) +### 9a.5. Target Mockup (if DESIGN_READY) If the gstack designer is available and the finding involves visual layout, hierarchy, or spacing (not just a CSS value fix like wrong color or font-size), generate a target mockup showing what the corrected version should look like: @@ -168,7 +188,7 @@ Show the user: "Here's the current state (screenshot) and here's what it should This step is optional — skip for trivial CSS fixes (wrong hex color, missing padding value). Use it for findings where the intended design isn't obvious from the description alone. -### 8b. Fix +### 9b. Fix - Read the source code, understand the context - Make the **minimal fix** — smallest change that resolves the design issue @@ -176,7 +196,7 @@ This step is optional — skip for trivial CSS fixes (wrong hex color, missing p - CSS-only changes are preferred (safer, more reversible) - Do NOT refactor surrounding code, add features, or "improve" unrelated things -### 8c. Commit +### 9c. Commit ```bash git add @@ -186,7 +206,7 @@ git commit -m "style(design): FINDING-NNN — short description" - One commit per fix. Never bundle multiple fixes. - Message format: `style(design): FINDING-NNN — short description` -### 8d. Re-test +### 9d. Re-test Navigate back to the affected page and verify the fix: @@ -199,13 +219,13 @@ $B snapshot -D Take **before/after screenshot pair** for every fix. -### 8e. Classify +### 9e. Classify - **verified**: re-test confirms the fix works, no new errors introduced - **best-effort**: fix applied but couldn't fully verify (e.g., needs specific browser state) - **reverted**: regression detected → `git revert HEAD` → mark finding as "deferred" -### 8e.5. Regression Test (design-review variant) +### 9e.5. Regression Test (design-review variant) Design fixes are typically CSS-only. Only generate regression tests for fixes involving JavaScript behavior changes — broken dropdowns, animation failures, conditional rendering, @@ -213,11 +233,11 @@ interactive state issues. For CSS-only fixes: skip entirely. CSS regressions are caught by re-running /design-review. -If the fix involved JS behavior: follow the same procedure as /qa Phase 8e.5 (study existing +If the fix involved JS behavior: follow the same procedure as /qa Phase 9e.5 (study existing test patterns, write a regression test encoding the exact bug condition, run it, commit if passes or defer if fails). Commit format: `test(design): regression test for FINDING-NNN`. -### 8f. Self-Regulation (STOP AND EVALUATE) +### 9f. Self-Regulation (STOP AND EVALUATE) Every 5 fixes (or after any revert), compute the design-fix risk level: @@ -237,7 +257,7 @@ DESIGN-FIX RISK: --- -## Phase 9: Final Design Audit +## Phase 10: Final Design Audit After all fixes are applied: @@ -248,7 +268,7 @@ After all fixes are applied: --- -## Phase 10: Report +## Phase 11: Report Write the report to `$REPORT_DIR` (already set up in the setup phase): @@ -278,7 +298,7 @@ Write a one-line summary to `~/.gstack/projects/{slug}/{user}-{branch}-design-au --- -## Phase 11: TODOS.md Update +## Phase 12: TODOS.md Update If the repo has a `TODOS.md`: @@ -291,7 +311,7 @@ If the repo has a `TODOS.md`: 11. **Clean working tree required.** If dirty, use AskUserQuestion to offer commit/stash/abort before proceeding. 12. **One commit per fix.** Never bundle multiple design fixes into one commit. -13. **Only modify tests when generating regression tests in Phase 8e.5.** Never modify CI configuration. Never modify existing tests — only create new test files. +13. **Only modify tests when generating regression tests in Phase 9e.5.** Never modify CI configuration. Never modify existing tests — only create new test files. 14. **Revert on regression.** If a fix makes things worse, `git revert HEAD` immediately. 15. **Self-regulate.** Follow the design-fix risk heuristic. When in doubt, stop and ask. 16. **CSS-first.** Prefer CSS/styling changes over structural component changes. CSS-only changes are safer and more reversible.