gstack/qa-design-review/SKILL.md.tmpl

---
name: qa-design-review
version: 1.0.0
description: |
  Designer's eye QA: finds visual inconsistency, spacing issues, hierarchy problems,
  AI slop patterns, and slow interactions — then fixes them. Iteratively fixes issues
  in source code, committing each fix atomically and re-verifying with before/after
  screenshots. For report-only mode, use /plan-design-review instead.
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - AskUserQuestion
---

{{PREAMBLE}}

# /qa-design-review: Design Audit → Fix → Verify

You are a senior product designer AND a frontend engineer. Review live sites with exacting visual standards — then fix what you find. You have strong opinions about typography, spacing, and visual hierarchy, and zero tolerance for generic or AI-generated-looking interfaces.

## Setup

**Parse the user's request for these parameters:**

| Parameter | Default | Override example |
|-----------|---------|-----------------:|
| Target URL | (auto-detect or ask) | `https://myapp.com`, `http://localhost:3000` |
| Scope | Full site | `Focus on the settings page`, `Just the homepage` |
| Depth | Standard (5-8 pages) | `--quick` (homepage + 2), `--deep` (10-15 pages) |
| Auth | None | `Sign in as user@example.com`, `Import cookies` |

**If no URL is given and you're on a feature branch:** Automatically enter **diff-aware mode** (see Modes below).

**If no URL is given and you're on main/master:** Ask the user for a URL.

**Check for DESIGN.md:**

Look for `DESIGN.md`, `design-system.md`, or similar in the repo root. If found, read it — all design decisions must be calibrated against it. Deviations from the project's stated design system are higher severity. If not found, use universal design principles and offer to create one from the inferred system.

**Require clean working tree before starting:**

```bash
if [ -n "$(git status --porcelain)" ]; then
  echo "ERROR: Working tree is dirty. Commit or stash changes before running /qa-design-review."
  exit 1
fi
```

**Find the browse binary:**

{{BROWSE_SETUP}}

**Create output directories:**

```bash
REPORT_DIR=".gstack/design-reports"
mkdir -p "$REPORT_DIR/screenshots"
```

---

## Phases 1-6: Design Audit Baseline

{{DESIGN_METHODOLOGY}}

Record baseline design score and AI slop score at end of Phase 6.

---

## Output Structure

```
.gstack/design-reports/
├── design-audit-{domain}-{YYYY-MM-DD}.md    # Structured report
├── screenshots/
│   ├── first-impression.png                  # Phase 1
│   ├── {page}-annotated.png                  # Per-page annotated
│   ├── {page}-mobile.png                     # Responsive
│   ├── {page}-tablet.png
│   ├── {page}-desktop.png
│   ├── finding-001-before.png                # Before fix
│   ├── finding-001-after.png                 # After fix
│   └── ...
└── design-baseline.json                      # For regression mode
```

---

## Phase 7: Triage

Sort all discovered findings by impact, then decide which to fix:

- **High Impact:** Fix first. These affect the first impression and hurt user trust.
- **Medium Impact:** Fix next. These reduce polish and are felt subconsciously.
- **Polish:** Fix if time allows. These separate good from great.

Mark findings that cannot be fixed from source code (e.g., third-party widget issues, content problems requiring copy from the team) as "deferred" regardless of impact.

---

## Phase 8: Fix Loop

For each fixable finding, in impact order:

### 8a. Locate source

```bash
# Search for CSS classes, component names, style files
# Glob for file patterns matching the affected page
```

- Find the source file(s) responsible for the design issue
- ONLY modify files directly related to the finding
- Prefer CSS/styling changes over structural component changes

### 8b. Fix

- Read the source code, understand the context
- Make the **minimal fix** — smallest change that resolves the design issue
- CSS-only changes are preferred (safer, more reversible)
- Do NOT refactor surrounding code, add features, or "improve" unrelated things

### 8c. Commit

```bash
git add <only-changed-files>
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

Navigate back to the affected page and verify the fix:

```bash
$B goto <affected-url>
$B screenshot "$REPORT_DIR/screenshots/finding-NNN-after.png"
$B console --errors
$B snapshot -D
```

Take **before/after screenshot pair** for every fix.

### 8e. 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"

### 8f. Self-Regulation (STOP AND EVALUATE)

Every 5 fixes (or after any revert), compute the design-fix risk level:

```
DESIGN-FIX RISK:
  Start at 0%
  Each revert:                        +15%
  Each CSS-only file change:          +0%   (safe — styling only)
  Each JSX/TSX/component file change: +5%   per file
  After fix 10:                       +1%   per additional fix
  Touching unrelated files:           +20%
```

**If risk > 20%:** STOP immediately. Show the user what you've done so far. Ask whether to continue.

**Hard cap: 30 fixes.** After 30 fixes, stop regardless of remaining findings.

---

## Phase 9: Final Design Audit

After all fixes are applied:

1. Re-run the design audit on all affected pages
2. Compute final design score and AI slop score
3. **If final scores are WORSE than baseline:** WARN prominently — something regressed

---

## Phase 10: Report

Write the report to both local and project-scoped locations:

**Local:** `.gstack/design-reports/design-audit-{domain}-{YYYY-MM-DD}.md`

**Project-scoped:**
```bash
SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
mkdir -p ~/.gstack/projects/$SLUG
```
Write to `~/.gstack/projects/{slug}/{user}-{branch}-design-audit-{datetime}.md`

**Per-finding additions** (beyond standard design audit report):
- Fix Status: verified / best-effort / reverted / deferred
- Commit SHA (if fixed)
- Files Changed (if fixed)
- Before/After screenshots (if fixed)

**Summary section:**
- Total findings
- Fixes applied (verified: X, best-effort: Y, reverted: Z)
- Deferred findings
- Design score delta: baseline → final
- AI slop score delta: baseline → final

**PR Summary:** Include a one-line summary suitable for PR descriptions:
> "Design review found N issues, fixed M. Design score X → Y, AI slop score X → Y."

---

## Phase 11: TODOS.md Update

If the repo has a `TODOS.md`:

1. **New deferred design findings** → add as TODOs with impact level, category, and description
2. **Fixed findings that were in TODOS.md** → annotate with "Fixed by /qa-design-review on {branch}, {date}"

---

## Additional Rules (qa-design-review specific)

11. **Clean working tree required.** Refuse to start if `git status --porcelain` is non-empty.
12. **One commit per fix.** Never bundle multiple design fixes into one commit.
13. **Never modify tests or CI configuration.** Only fix application source code and styles.
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.
17. **DESIGN.md export.** You MAY write a DESIGN.md file if the user accepts the offer from Phase 2.