Skip to content

feat(design-review): add Phase 7 - Thinking Fast and Slow - Cognitive Load (S1/S2) audit #696

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MaruPelkar wants to merge 1 commit into
base: main
Choose a base branch
from
+70 −30
Open

feat(design-review): add Phase 7 - Thinking Fast and Slow - Cognitive Load (S1/S2) audit #696

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
50 changes: 35 additions & 15 deletions design-review/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

```
Expand Down Expand Up @@ -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:

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -1275,15 +1295,15 @@ 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
- If a target mockup was generated in 8a.5, use it as the visual reference for the fix
- 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 <only-changed-files>
Expand All @@ -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:

Expand All @@ -1306,25 +1326,25 @@ $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,
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:

Expand All @@ -1344,7 +1364,7 @@ DESIGN-FIX RISK:

---

## Phase 9: Final Design Audit
## Phase 10: Final Design Audit

After all fixes are applied:

Expand All @@ -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):

Expand Down Expand Up @@ -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`:

Expand All @@ -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.
Expand Down
50 changes: 35 additions & 15 deletions design-review/SKILL.md.tmpl
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

```
Expand All @@ -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:

Expand All @@ -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
Expand All @@ -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:

Expand All @@ -168,15 +188,15 @@ 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
- If a target mockup was generated in 8a.5, use it as the visual reference for the fix
- 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 <only-changed-files>
Expand All @@ -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:

Expand All @@ -199,25 +219,25 @@ $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,
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:

Expand All @@ -237,7 +257,7 @@ DESIGN-FIX RISK:

---

## Phase 9: Final Design Audit
## Phase 10: Final Design Audit

After all fixes are applied:

Expand All @@ -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):

Expand Down Expand Up @@ -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`:

Expand All @@ -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.
Expand Down